---
title: "Test a dotAI provider connection"
method: POST
path: "/api/v1/ai/providers/test/{capability}"
tags: ["AI"]
---

# Test a dotAI provider connection

`POST /api/v1/ai/providers/test/{capability}`

## Request

- Base URL: `https://docs.anzworldline-solutions.com.au`
- URL: `https://docs.anzworldline-solutions.com.au/api/v1/ai/providers/test/{capability}`
- Auth: none declared
- TypeScript: <https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/docs/api/v1/ai/providers/test/:capability/post.ts> (a function with typed inputs; its response is checked against the schema)

Builds the provider client for the given capability from the posted configuration and issues one minimal real request against the provider (a short chat reply, a one-line embedding, or a single test image). Masked credential fields ("*****") in the posted config are resolved against the real value already stored for siteId before testing. Returns success=false with a message on any validation or provider error rather than an HTTP error status, so the caller can always render the result.

## Path parameters

- `capability` string, required

## Query parameters

- `siteId` string

## Request body

- string

## Response `200`

Test executed — check the success field for the outcome

- ResponseEntityAiTestConnectionView
  - `errors` ErrorEntity[]
    - `errorCode` string
    - `message` string
    - `fieldName` string
  - `entity` TestConnectionResult
    - `success` boolean
    - `message` string
  - `messages` MessageEntity[]
    - `message` string
  - `i18nMessagesMap` object
  - `permissions` string[]
  - `pagination` Pagination
    - `currentPage` integer
    - `perPage` integer
    - `totalEntries` integer

## Other responses

- `400`: Unknown capability or malformed request body
- `401`: Unauthorized - authentication required
- `403`: Forbidden - requires CMS admin, or access denied to site

## Changes

- **2026-10-30** `4fd8e917d458`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/changes/api/v1/ai/providers/test/:capability/post.md)

---

[API](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api.md) - [All operations](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/revisions/4fd8e917d458?raw)