Skip to content
Kindgi

Fetch a provider

View as Markdown
GET
/v1/providers/{providerId}
curl --request GET \
  --url https://example.com/v1/providers/example \
  --header 'Authorization: Bearer <token>'

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
providerId
required
string

ProviderId — opaque string identifier chosen by the deployment.

Responses

Section titled “Responses”

200

Section titled “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

Fallback cap on output tokens. Adapters that require max_tokens on every request (e.g. Anthropic) use this when ModelCallInput.maxOutputTokens is unset.

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, so a call that wants as little as it allows (a judge’s) gets it. Absent: it doesn’t think, or nothing is known.

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
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"
      }
    }
  ]
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also