Test AI Provider Connection
Builds a temporary client from the submitted configuration and runs one short completion (the model is asked to say hello and name itself). Nothing is saved. Use it to check a key, model or endpoint before saving.
Reusing the stored key. An empty api_key probes with the key stored for the provider, so a model change can be checked without retyping it. With no stored key the request is refused with 79004. The stored key is only sent to the endpoint it is stored for (an empty base_url means the vendor's own): testing another base_url with it is refused with 10002 (domain 83). Send the key to test another endpoint.
Allowed targets. The endpoint must be public https, or an in-cluster host the environment lists; anything else is refused with 10001 (domain 83) before anything is sent.
A vendor failure is still a 200, with ok: false and the reason in error. On success, sample_answer carries the model's reply.
Platform owner only. The caller's node must be the platform root node; any other caller is refused with 403 / 10005.
Required permission: ai-provider:update
Request
POST /v2/admin/ai-providers/test
Headers
| Name | Description |
|---|---|
Authorization | Required. Bearer <access_token> |
Content-Type | Required. application/json |
Body
| Field | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | Provider key: claude or openai |
model | string | Yes | Model to run the completion with |
api_key | string | No | API key to probe with. Empty means the stored key |
base_url | string | No | API base URL. Empty means the vendor's own endpoint |
timeout | integer | No | Request timeout in seconds, 0 or greater |
Example
curl --request POST \
--url '{{baseUrl}}/v2/admin/ai-providers/test' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"provider": "claude",
"api_key": "",
"base_url": "",
"model": "claude-sonnet-4-5",
"timeout": 30
}'
Response
{
"ok": true,
"latency_ms": 1184,
"model": "claude-sonnet-4-5",
"sample_answer": "Hello! I am Claude, a model made by Anthropic."
}
Response Fields
| Field | Type | Description |
|---|---|---|
ok | boolean | Whether the completion succeeded |
latency_ms | integer | Duration of the completion in milliseconds |
model | string | The model that was tested |
sample_answer | string | Only when ok is true: the model's reply |
error | string | Only when ok is false: why the completion failed |
Errors
| Status | Code | Description |
|---|---|---|
| 400 | 10015 | Validation failed (provider or model missing, negative timeout) — see details |
| 400 | 79001 | Unsupported provider key (domain 79) |
| 400 | 79004 | api_key is empty and no key is stored for the provider (domain 79) |
| 400 | 10001 | Target refused: not https, does not resolve, or resolves to a private or metadata address (domain 83) |
| 400 | 10002 | The stored key would be sent to an endpoint other than the one it is stored for (domain 83) |
| 403 | 10005 | The caller is not the platform owner (domain 2) |
See Errors for the error format and common codes.