Fetch a provider

GET

/v1/providers/{providerId}

curl --request GET \
  --url https://example.com/v1/providers/example \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

Returns the wire-safe ProviderMetadata (routing metadata only — secrets never cross the wire).

Authorizations

• bearerAuth

Parameters

Path Parameters

providerId

required

string

ProviderId — opaque string identifier chosen by the deployment.

Responses

200

Provider metadata.

Media typeapplication/json

object

id

required

string

>= 1 characters

region

required

Region the connection routes to. All models on this provider share the region (the same models served from two clouds or regions are separate providers). 'unspecified' when not region-scoped.

string

>= 1 characters /^[a-z][a-z0-9-]{0,62}$/

models

required

Models this connection exposes. Non-empty. models[i].name must be unique within the list.

Array<object>

>= 1 items

object

name

required

Vendor-facing model id passed to the SDK (e.g. claude-sonnet-5-5).

string

>= 1 characters

contextWindow

required

Context window in tokens.

integer

>= 1

features

required

Features this model supports (tool-use, thinking, structured-output, …).

Array<string>

Allowed values: structured-output vision audio-input audio-output tool-use parallel-tool-use thinking long-context code-execution web-search file-search streaming batch

cost

required

USD per 1K tokens. An adapter may take more rate fields (see the adapter’s README).

object

promptUsdPer1kTokens

required

number

completionUsdPer1kTokens

required

number

key

additional properties

any

p95LatencyMs

Best-effort p95 latency estimate in milliseconds. Varies by model.

number

maxOutputTokens

The default cap on a call’s output tokens: what a call asks for when it sets none. A call’s own ModelCallInput.maxOutputTokens (its agent’s maxOutputTokens) replaces it. Not the model’s own maximum, which its vendor sets.

integer

>= 1

sampling

Whether the model takes sampling settings (temperature). false: its API rejects a non-default value, so the call goes without one and the answer’s warnings say so (sampling-unsupported). Absent: it takes them.

boolean

thinking

How the model thinks before it answers, and the levels it takes, so a call’s level (an agent’s model settings, or a judge’s lowest) is sent as one it takes: any other is rounded to the next one it takes, or its highest, with a thinking-level-adjusted warning. Absent: it doesn’t think, or nothing is known, and nothing is sent for it.

object

mode

required

adaptive: on unless turned down. always: on, and it can only be lowered.

string

Allowed values: adaptive always

lowest

required

The vendor’s own setting for the least thinking: for Anthropic disabled, between_tools or an effort (low); for Gemini a thinking level (low, minimal); for OpenAI a reasoning effort (low, none).

string

>= 1 characters

levels

The levels the model takes besides lowest, least first. Absent: low, medium and high, which every thinking model takes, plus minimal when lowest is minimal, minus those below lowest when it is low, medium or high (any case).

Array<string>

unique items

Allowed values: minimal low medium high xhigh max

default

The level a call that asks none is sent. It must be lowest or one the model takes (levels), or the registration is refused. Absent: the vendor’s default.

string

Allowed values: lowest minimal low medium high xhigh max

description

Short per-model description surfaced in logs.

string

defaultModel

The model to use when an agent doesn’t choose: one of models[].name. When candidates rank equally, it comes before the provider’s other models; without it, ties break by model name. A preset sets it. A runtime before 0.1.4 ignores it.

string

>= 1 characters

attributes

Soft attributes for preference-ranking (local, lower-cost, higher-accuracy, …). Matched by string equality against Preference.feature.

Array<string>

description

Short human description of the connection.

string

capabilityKind

Kind of resource this provider fulfils. Absent = llm-inference. Adapters for other kinds (embedding, gpu-compute, sandbox-exec, …) set this explicitly.

string

fallback

A fallback serves a capability only when no other provider satisfies it (e.g. kindgi dev’s scripted dev-echo); an agent turn routed to one carries a fallback-provider warning. Absent = false.

boolean

labels

Bookkeeping, such as who manages the provider; the router ignores labels. At most 32 keys; a key is 1-63 lowercase letters and digits, with ., -, _ or / inside; a value is at most 256 characters. The convention key kindgi.com/managed-by names the manager (kindgi-dev, kindgi-deploy:<environment>). Out of bounds: 400 invalid-provider, reason invalid-labels.

object

<= 32 properties

key

additional properties

string

<= 256 characters

Example

{
  "models": [
    {
      "features": [
        "structured-output"
      ],
      "thinking": {
        "mode": "adaptive",
        "levels": [
          "minimal"
        ],
        "default": "lowest"
      }
    }
  ]
}

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Not a member of the tenant (permission-denied). Without an authorization store, anyone reads it.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No provider with that id under this tenant.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also

• GET /v1/providers/{providerId}/capabilities: List capabilities a provider satisfies
• GET /v1/providers/{providerId}/check: Check a provider's registration
• POST /v1/providers/{providerId}/unregister: Unregister a model provider
• Error code database-busy
• Error code permission-denied
• Every error code