Skip to content
Kindgi

Register a model provider

POST
/v1/providers
curl --request POST \
  --url https://example.com/v1/providers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "metadata": { "id": "example", "region": "example", "models": [ { "name": "example", "contextWindow": 1, "features": [ "structured-output" ], "cost": { "promptUsdPer1kTokens": 1, "completionUsdPer1kTokens": 1 }, "p95LatencyMs": 1, "maxOutputTokens": 1, "description": "example" } ], "attributes": [ "example" ], "description": "example", "capabilityKind": "example", "fallback": true }, "adapter_id": "example", "secret_ref": { "envName": "example", "name": "example" }, "adapter_config": { "additionalProperty": "example" } }'

Body is a full ProviderMetadata. Server validates shape: provider-level id + region non-empty; models[] non-empty with unique name per entry; per-model contextWindow positive integer; per-model features against the closed enum; per-model cost non-negative; optional per-model p95LatencyMs / maxOutputTokens well-shaped — same rules as @kindgi/capabilities.createProviderRegistry. Secrets (API keys, endpoints) are NOT part of the wire shape; deployments store them inside the binding.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
metadata
required
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-4-6).

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
description

Short per-model description surfaced in logs.

string
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
adapter_id
required

The adapter that instantiates this provider (e.g. @kindgi/adapter-model-gemini). Must be registered for the tenant.

string
>= 1 characters
secret_ref

The tenant secret holding the adapter’s credential (an API key, a service-account key). Absent when the adapter needs none or finds its own (a cloud’s default credentials).

object
envName
required
string
>= 1 characters
name
required
string
>= 1 characters
adapter_config

The adapter’s connection settings: flat, non-secret values (a cloud project, a base URL). Each adapter documents its keys. Credentials go in secret_ref, never here.

object
key
additional properties
Any of:
string

Responses

Section titled “Responses”

201

Section titled “201”

Provider registered.

Media typeapplication/json
object
providerId
required
string
Examplegenerated
{
  "providerId": "example"
}

400

Section titled “400”

Validation failed (see details.reason).

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

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

409

Section titled “409”

Provider already registered at that id.

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

500

Section titled “500”

Server error (unmapped domain code or framework crash).

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