Get started

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 AiProviderConfig object

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.

provider

string

required

One of: anthropic, mistral

The configured provider. It cannot be changed in place: delete the configuration and create one to switch providers.

model

string

required

The configured model id, one of the provider's models in the catalog getAiProviders returns.

base_url

string (uri) | null

required

The provider API base URL override, an absolute https URL, or null when completions go to the provider's default endpoint.

credential_hint

string

required

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.

etag

string

required

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.

List the AI provider catalog

Returns 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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

array of AiProviderCatalog

required

Errors 400, 401, 403, 429, 500, 504. See Errors.

# Catalog only. It says which providers exist and what each one needs collected,
# never a stored credential.
curl -s https://api.mountaya.com/v1/ai-providers \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": [
    {
      "provider": "anthropic",
      "label": "Anthropic",
      "models": [
        "claude-opus-5-5",
        "claude-sonnet-5-5"
      ],
      "default_model": "claude-sonnet-5-5",
      "credential_fields": [
        {
          "key": "api_key",
          "label": "API key"
        }
      ]
    }
  ]
}

Retrieve an organization's AI provider configuration

GET
/v1/organizations/{organization_id}/ai-provider-config

Returns 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_id

string (uuid)

in path

required

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

AiProviderConfig | null

required

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

# The stored credential is never returned. `credential_hint` shows enough of it to
# recognize which key is configured.
curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/ai-provider-config \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": {
    "provider": "anthropic",
    "model": "claude-sonnet-5-5",
    "base_url": null,
    "credential_hint": "IjkL",
    "etag": "\"d2\""
  }
}

Configure an organization's AI provider

POST
/v1/organizations/{organization_id}/ai-provider-config

Creates 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 is deleteOrganizationAiProviderConfig and 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 getAiProviders lists 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_id

string (uuid)

in path

required

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-Key

string

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.

provider

string

in body

required

One of: anthropic, mistral

The AI provider to use. It cannot be changed afterwards: delete the configuration and create one to switch providers.

model

string

in body

required

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_url

string (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.

credential

map of string

in body

required

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

AiProviderConfig

required

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.

See the AiProviderConfig object.

Errors 400, 401, 403, 404, 409, 413, 429, 500, 504. See Errors.

curl -s -X POST https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/ai-provider-config \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "model": "claude-sonnet-5-5",
    "credential": {
      "api_key": "sk-ant-api03-REPLACE_ME"
    }
  }'
201
Response
{
  "data": {
    "provider": "anthropic",
    "model": "claude-sonnet-5-5",
    "base_url": null,
    "credential_hint": "IjkL",
    "etag": "\"d2\""
  }
}

Update an organization's AI provider configuration

PATCH
/v1/organizations/{organization_id}/ai-provider-config

Changes 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).
  • model must be one of the configured provider's models in getAiProviders. base_url set to null clears the override, so completions go to the provider's default endpoint again.
  • credential replaces 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_url other than the one stored must come with credential: 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 null base_url, which returns completions to the provider's own endpoint, keeps the stored credential.
  • The provider is not a field here: switching providers is deleteOrganizationAiProviderConfig and then postOrganizationAiProviderConfig.
  • With none configured there is nothing to change: the answer is a 409 coded AI_PROVIDER_NOT_CONFIGURED, whatever the body or If-Match says. It comes before any 400 this operation judges of the body (a model the provider lacks, a base_url refused or sent without credential, a credential of the wrong shape), since each is judged against the configured provider. Create one with postOrganizationAiProviderConfig.
  • If-Match makes it conditional on the configuration's etag.
  • 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_id

string (uuid)

in path

required

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-Key

string

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-Match

string

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.

model

string

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_url

string (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.

credential

map 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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

AiProviderConfig

required

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.

See the AiProviderConfig object.

Errors 400, 401, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.

# Omit `credential` to keep the stored key. The provider cannot change here.
curl -s -X PATCH https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/ai-provider-config \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-opus-5-5"}'
200
Response
{
  "data": {
    "provider": "anthropic",
    "model": "claude-sonnet-5-5",
    "base_url": null,
    "credential_hint": "IjkL",
    "etag": "\"d2\""
  }
}

Delete an organization's AI provider configuration

DELETE
/v1/organizations/{organization_id}/ai-provider-config

Removes 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-Match names: there is no configuration left for the condition to protect.
  • If-Match makes it conditional on the configuration's etag, 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_id

string (uuid)

in path

required

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-Key

string

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-Match

string

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 403, 404, 409, 412, 429, 500, 504. See Errors.

# Clears the provider and the stored credential together. A run already in flight
# ends with an error at its next model call, and a new one is refused with 409.
curl -s -X DELETE https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/ai-provider-config \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": null
}