Skip to main content
POST
Create a provider record
Adds a provider record to a capability domain. Only a protocol-generic adapter qualifies (for example the inference openai-compatible adapter): vendor-bound adapters are seed-only. The vendor must be approved in the vendor registry, and the connection must have an approved credential. The record is never pinned; priority defaults to 100 and enabled to true. The answer is 201 with the created record. The creation is recorded under the record (<domain>/<providerKey>), so neither listProviderAuditEvents nor the capability audit feed lists it.

Authority and retries

Requires platform:manage at the platform scope. Capability and provider configuration is deployment-wide, so a credential granted platform:manage only at an org unit is refused with 403 and nothing is written. A Forge agent can never hold platform:manage. The write is recorded in the audit log under the calling key or External App, never a person. Send an Idempotency-Key to make a retry safe. The same key and the same body within 24 hours return the recorded 201 only while you still hold platform:manage at the platform scope; otherwise the answer is 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422.

Errors

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Body

application/json

A provider record for a capability domain: a protocol-generic adapterKey (vendor-bound adapters are seed-only), an approved vendorKey, and a connectionName with an approved credential. enabled defaults to true and priority to 100.

domain
string
required

The capability domain, as listCapabilities returns it (e.g. notifications)

Minimum string length: 1
providerKey
string
required

The new record's provider key, unique within the domain

Minimum string length: 1
adapterKey
string
required

A protocol-generic adapter registered for the domain (e.g. openai-compatible)

Minimum string length: 1
vendorKey
string
required

An approved vendor in the vendor registry

Minimum string length: 1
connectionName
string
required

The vendor connection whose approved credential the record uses

Minimum string length: 1
enabled
boolean

Whether the record starts enabled (default true)

priority
integer

Resolution priority, lower first (default 100)

Required range: x >= 0

Response

Create a provider record

data
object
required

The provider record created for a capability domain. A created record is never pinned; priority defaults to 100 and enabled to true.

meta
object
required