AI
The AI providers an organization can route agent runs through, and the credentials it has configured for them. There is no default provider: an organization with none configured cannot start a run, and postAgentRun answers 409 with AI_PROVIDER_NOT_CONFIGURED. Every operation here needs a session token beside the key.
The masked read view of an organization's AI provider configuration for the studio co-pilot. It never contains the credential: it carries the provider, the model, the base URL override if one is set, and a non-sensitive hint (the last four characters of the key) so an admin can recognize which key is in place. An organization with none configured reads null rather than this object, and cannot start an agent run.
providerstring
One of: anthropic, mistral
The configured provider. It cannot be changed in place: delete the configuration and create one to switch providers.
modelstring
The configured model id, one of the provider's models in the catalog getAiProviders returns.
base_urlstring (uri) | null
The provider API base URL override, an absolute https URL, or null when completions go to the provider's default endpoint.
credential_hintstring
A non-sensitive fragment of the configured credential, the last four characters of the provider key, shown so an admin can recognize the key without revealing it. Empty for a key shorter than 12 characters, of which four would be too large a part.
etagstring
The version of the configuration, the one the ETag of a read of it carries, opaque and compared whole. Send it as If-Match to make patchOrganizationAiProviderConfig or deleteOrganizationAiProviderConfig conditional.
/v1/ai-providersReturns the catalog of AI providers an organization may configure for the studio co-pilot: each provider's id, label, selectable model ids, and the credential fields it requires. The catalog is the same for every caller (no per-organization data) and is safe to cache. It asks no member role, so a session token is answered alike whoever it names, or, minted for api, with no user at all; one minted for studio-embedded naming nobody is a 401.
Response 200
The AI providers an organization may route agent runs through, and the credential fields each one needs.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataarray of AiProviderCatalog
Errors 400, 401, 403, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/ai-provider-configReturns the organization's AI provider configuration for the studio co-pilot, masked: the provider, the model, the base URL override if one is set, and a non-sensitive hint of the credential. The credential itself is never returned.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Response 200
The organization's AI provider configuration, or data: null when it has none. The credential is never returned; credential_hint shows enough to recognize which one is stored. ETag carries the configuration's etag, and is absent when data is null.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataAiProviderConfig | null
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/ai-provider-configCreates the organization's AI provider configuration for the studio co-pilot: the provider, the model, the credential, and optionally a base URL override. From then on the organization can start agent runs, which postAgentRun refuses while none is configured.
- Owner or admin only (403 otherwise).
- An organization has one configuration at most: creating one while one exists is a 409. Change it with
patchOrganizationAiProviderConfig; the provider is fixed once configured, so switching providers isdeleteOrganizationAiProviderConfigand then this. - The model must be one of the provider's models, and the credential must carry every field the provider names and no other, each non-empty, as
getAiProviderslists them; anything else is a 400 naming the field. - The credential is write-only: it is encrypted at rest and never returned. The answer is the masked configuration, with a hint of the credential in its place.
Webhook events organization.ai_provider_config.created, recorded by the task organization.ai_provider_config.create.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Body
The AI provider to route this organization's agent runs through, the model, and the credential to reach it with. The credential is write-only; reads return a hint, never the value.
providerstring
in body
One of: anthropic, mistral
The AI provider to use. It cannot be changed afterwards: delete the configuration and create one to switch providers.
modelstring
in body
The model id to use. It must be one of the provider's models in the catalog getAiProviders returns, which is what decides whether a value is accepted; the ceiling below is the envelope bound, not the vocabulary.
base_urlstring (uri)
in body
A provider API base URL override, for routing completions through a gateway of the organization's own. Optional and not nullable: omit it to use the provider's default endpoint.
credentialmap of string
in body
The provider credential as a set of named fields. Each provider declares the fields it requires in the catalog getAiProviders returns; read them from there rather than assuming a shape. Every field the catalog names is sent, each non-empty, or the missing ones are a 400; a field the catalog does not name is a 400 naming it. Write-only: never returned by any operation; a read answers with credential_hint instead.
Response 201
The configuration as created. The credential just sent is not echoed back. Location names this same path, /v1/organizations/{organization_id}/ai-provider-config, since an organization has one configuration, and ETag carries its etag.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataAiProviderConfig
The masked read view of an organization's AI provider configuration for the studio co-pilot. It never contains the credential: it carries the provider, the model, the base URL override if one is set, and a non-sensitive hint (the last four characters of the key) so an admin can recognize which key is in place. An organization with none configured reads null rather than this object, and cannot start an agent run.
Errors 400, 401, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/ai-provider-configChanges the organization's AI provider configuration, merged into what is stored: a field left out keeps its value, and an empty object changes nothing and answers the configuration as it stands.
- Owner or admin only (403 otherwise).
modelmust be one of the configured provider's models ingetAiProviders.base_urlset to null clears the override, so completions go to the provider's default endpoint again.credentialreplaces the stored credential whole, carrying every field the configured provider names, each non-empty; omitted, the stored credential is kept, so the model can be changed without sending the key again. It is write-only and never returned.- A
base_urlother than the one stored must come withcredential: the stored credential is never sent to a host it was not stored for, so a new URL without it is a 400 with one entry at["credential"], and nothing changes. A nullbase_url, which returns completions to the provider's own endpoint, keeps the stored credential. - The provider is not a field here: switching providers is
deleteOrganizationAiProviderConfigand thenpostOrganizationAiProviderConfig. - With none configured there is nothing to change: the answer is a 409 coded
AI_PROVIDER_NOT_CONFIGURED, whatever the body orIf-Matchsays. It comes before any 400 this operation judges of the body (a model the provider lacks, abase_urlrefused or sent withoutcredential, a credential of the wrong shape), since each is judged against the configured provider. Create one withpostOrganizationAiProviderConfig. If-Matchmakes it conditional on the configuration'setag.- A change takes effect at the next model call of every run, a run already in flight included.
Webhook events organization.ai_provider_config.updated, recorded by the task organization.ai_provider_config.update.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
If-Matchstring
in header
Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.
Body
The configuration fields to change. Every field is optional; an omitted field keeps its current value, and a null base_url clears it. A new base_url is the one field that needs another beside it: credential.
modelstring
in body
The model id to use, one of the provider's models in the catalog getAiProviders returns. Optional and not nullable: omit it to keep the current model.
base_urlstring (uri) | null
in body
A provider API base URL override, held to the rules AiProviderConfigCreateParams states for it. Omit it to keep the current one, and send null to clear it, which routes completions to the provider's default endpoint again.
credentialmap of string
in body
A new provider credential, which REPLACES the stored one whole: every field the catalog names for the configured provider is sent, each non-empty, as on a create. Optional and not nullable: omit it to keep the stored credential, so the model can be changed without sending the key again. A base_url changed to a new URL is the exception, and requires it. Write-only: never returned by any operation.
Response 200
The configuration after the change, with its new etag in ETag. A credential just sent is not echoed back.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataAiProviderConfig
The masked read view of an organization's AI provider configuration for the studio co-pilot. It never contains the credential: it carries the provider, the model, the base URL override if one is set, and a non-sensitive hint (the last four characters of the key) so an admin can recognize which key is in place. An organization with none configured reads null rather than this object, and cannot start an agent run.
Errors 400, 401, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/ai-provider-configRemoves the organization's AI provider configuration, the stored credential with it. Without one the co-pilot cannot run for this organization's resources: postAgentRun answers 409 AI_PROVIDER_NOT_CONFIGURED until postOrganizationAiProviderConfig creates a new one, and a run already in flight ends with an error at its next model call.
- Owner or admin only (403 otherwise).
- Deleting is an act on the organization's state, so with none configured it answers 200 and changes nothing, whatever
If-Matchnames: there is no configuration left for the condition to protect. If-Matchmakes it conditional on the configuration'setag, so a configuration somebody changed since it was read is not deleted unseen.
Webhook events organization.ai_provider_config.deleted, recorded by the task organization.ai_provider_config.delete.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
If-Matchstring
in header
Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.
Response 200
The AI provider configuration is removed, or there was none. The organization has no provider until a new one is created, so postAgentRun answers 409 AI_PROVIDER_NOT_CONFIGURED. data is null.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 403, 404, 409, 412, 429, 500, 504. See Errors.