---
title: "Probe Provider"
method: POST
path: "/providers/probe"
tags: ["Secrets"]
---

# Probe Provider

`POST /providers/probe`

## Request body

- ProbeProviderRequest — The credential to test. It is spent on one read and never persisted. `kind` is a StandardProviderKind or CustomProviderKind value; `provider` carries the same field vocabulary the vault stores, so a card can probe what it is about to save without reshaping it. `secret_id` names a connection already stored in the caller's project, and is how a write-only connection is testable at all: its value never comes back to the browser, so there is nothing for the card to send. The stored kind and credentials are the base; anything typed in this request replaces the stored value for that field, which is what lets a card test an edit — a new base URL, say — before saving it.
  - `kind` string, nullable — Provider kind, e.g. 'openai', 'azure', 'custom'. Optional when `secret_id` is given: the stored kind is used unless this overrides it.
  - `provider` ProviderCredentials — Credentials in transit only. Never persisted here, never logged, never echoed. `key` is a `SecretStr` and `extras` is kept out of `repr`, so an accidental log line or traceback that carries this object cannot print the credential. Unwrap the key with `.get_secret_value()` at the point it is put on the wire, never earlier.
    - `key` string, password, nullable
    - `url` string, nullable
    - `version` string, nullable
    - `extras` object, nullable
  - `secret_id` string, uuid, nullable — Test the credential stored under this secret, in the caller's project. Fields sent in `provider` override the stored ones.

## Response `200`

Successful Response

- ProbeProviderResponse
  - `credential` CredentialResult, required
    - `status` 'valid' | 'invalid' | 'unknown', required — Did the provider accept this credential? `unknown` is an honest answer, not a failure: it means Agenta found no free, read-only endpoint that proves the credential works. A public catalog endpoint answering successfully never raises the status above `unknown`.
    - `message` string, required
  - `discovery` DiscoveryResult, required
    - `status` 'fetched' | 'unsupported' | 'failed', required — Which model identifiers did the provider return? `unsupported` means the provider offers no model-list endpoint; `failed` means one exists but this attempt did not get an answer. Either way the caller keeps the shipped catalog rather than narrowing the user's model choice.
    - `models` string[]
  - `fetched_at` string, date-time, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/agenta-ai/apis/agenta-api.md) · [All operations](https://skmtc.dev/agenta-ai/apis/agenta-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agenta-ai/agenta-api/revisions/713e4f3b7519/schema)