API Reference | MCP Stack Docs

MCP Stack

The MCP Stack REST API manages organizations, MCP servers, gateways, hosting, billing, and agents. The CLI wraps many of these same endpoints.

Each row below expands into OpenAPI-sourced request body information, response body schemas, example JSON, and common error statuses. Endpoints that do not accept JSON explicitly say No request body.

Conventions#

Base URL: https://api.mcpstack.com

Auth: send an OAuth access token or a service-account key as a bearer token. Service-account keys (mcpstack_sk_...) are also accepted in the X-API-Key header.

HTTP

Authorization: Bearer <token>
X-API-Key: mcpstack_sk_...

Organization scope: most endpoints live under one organization root. Throughout this page that root is shown inline as /api/v1/organizations/{orgId}, so every signature is complete and unambiguous. A handful of endpoints sit above the org root and are shown with their full /api/v1/... path.

Schema source: request and response bodies are generated from the MCP Stack OpenAPI document. Business validation can be stricter than OpenAPI nullability, so 400 responses include a request-specific error message when a field is missing or invalid.

Error response shape

Most public API errors return a JSON object with an `error` string. Authentication middleware may return an empty body for some `401` or `403` responses.

{
  "error": "Human-readable request-specific error message."
}

BASH

export BASE="https://api.mcpstack.com"
export TOKEN="mcpstack_sk_..."
 
# List the organizations the token can access
curl -sS --fail-with-body "$BASE/api/v1/organizations" \
  -H "Authorization: Bearer $TOKEN"

Organizations and access#

Identity, organization membership, invitations, service-account keys, and authorization checks.

MethodEndpointDescriptionCopy

GET/api/v1/organizationsList organizations the token can access.List organizations the token can access.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].slug`	`string \| null`	Optional
`[].name`	`string \| null`	Optional
`[].planTier`	`string \| null`	Optional
`[].mcpServerCount`	`integer(int32)`	Optional
`[].memberCount`	`integer(int32)`	Optional
`[].createdOn`	`string(date-time)`	Optional
`[].publicMcpGuidesEnabled`	`boolean`	Optional

[
  {
    "id": "id_123",
    "slug": "support-api",
    "name": "Support API",
    "planTier": "string",
    "mcpServerCount": 1,
    "memberCount": 1,
    "createdOn": "2026-05-29T18:20:11Z",
    "publicMcpGuidesEnabled": true
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizationsCreate an organization.Create an organization.

Request bodyCreateOrganizationRequest · application/json

Field	Type	Required
`name`	`string`	Required
`slug`	`string`	Required

{
  "name": "Support API",
  "slug": "support-api"
}

Response body201OrganizationResponse

Field	Type	Required
`id`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`name`	`string \| null`	Optional
`planTier`	`string \| null`	Optional
`mcpServerCount`	`integer(int32)`	Optional
`memberCount`	`integer(int32)`	Optional
`createdOn`	`string(date-time)`	Optional
`publicMcpGuidesEnabled`	`boolean`	Optional

{
  "id": "id_123",
  "slug": "support-api",
  "name": "Support API",
  "planTier": "string",
  "mcpServerCount": 1,
  "memberCount": 1,
  "createdOn": "2026-05-29T18:20:11Z",
  "publicMcpGuidesEnabled": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}Get the current organization.Get the current organization.

Request bodynone

No request body.

Response body200OrganizationResponse

Field	Type	Required
`id`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`name`	`string \| null`	Optional
`planTier`	`string \| null`	Optional
`mcpServerCount`	`integer(int32)`	Optional
`memberCount`	`integer(int32)`	Optional
`createdOn`	`string(date-time)`	Optional
`publicMcpGuidesEnabled`	`boolean`	Optional

{
  "id": "id_123",
  "slug": "support-api",
  "name": "Support API",
  "planTier": "string",
  "mcpServerCount": 1,
  "memberCount": 1,
  "createdOn": "2026-05-29T18:20:11Z",
  "publicMcpGuidesEnabled": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PATCH/api/v1/organizations/{orgId}Update organization details.Update organization details.

Request bodyUpdateOrganizationRequest · application/json

Field	Type	Required
`name`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`publicMcpGuidesEnabled`	`boolean \| null`	Optional

{
  "name": "Support API",
  "slug": "support-api",
  "publicMcpGuidesEnabled": true
}

Response body200OrganizationResponse

Field	Type	Required
`id`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`name`	`string \| null`	Optional
`planTier`	`string \| null`	Optional
`mcpServerCount`	`integer(int32)`	Optional
`memberCount`	`integer(int32)`	Optional
`createdOn`	`string(date-time)`	Optional
`publicMcpGuidesEnabled`	`boolean`	Optional

{
  "id": "id_123",
  "slug": "support-api",
  "name": "Support API",
  "planTier": "string",
  "mcpServerCount": 1,
  "memberCount": 1,
  "createdOn": "2026-05-29T18:20:11Z",
  "publicMcpGuidesEnabled": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}Delete the organization. Admin only.Delete the organization. Admin only.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/membersList active members.List active members.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].userId`	`string \| null`	Optional
`[].email`	`string \| null`	Optional
`[].firstName`	`string \| null`	Optional
`[].lastName`	`string \| null`	Optional
`[].role`	`string \| null`	Optional
`[].joinedAt`	`string(date-time)`	Optional

[
  {
    "id": "id_123",
    "userId": "id_123",
    "email": "teammate@example.com",
    "firstName": "Support API",
    "lastName": "Support API",
    "role": "developer",
    "joinedAt": "2026-05-29T18:20:11Z"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PATCH/api/v1/organizations/{orgId}/members/{principalId}Change a member's role.Change a member's role.

Request bodyUpdateOrganizationMemberRequest · application/json

Field	Type	Required
`role`	`string`	Required

{
  "role": "developer"
}

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}/members/{principalId}Remove a member.Remove a member.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/invitationsList pending invitations.List pending invitations.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].organizationId`	`string \| null`	Optional
`[].organizationName`	`string \| null`	Optional
`[].email`	`string \| null`	Optional
`[].role`	`string \| null`	Optional
`[].status`	`string \| null`	Optional
`[].inviteUrl`	`string \| null`	Optional
`[].createdAt`	`string(date-time)`	Optional
`[].expiresAt`	`string(date-time)`	Optional
`[].lastSentAt`	`string(date-time) \| null`	Optional
`[].acceptedAt`	`string(date-time) \| null`	Optional
`[].acceptedByUserId`	`string \| null`	Optional
`[].revokedAt`	`string(date-time) \| null`	Optional
`[].revokedReason`	`string \| null`	Optional
`[].lastSendError`	`string \| null`	Optional

[
  {
    "id": "id_123",
    "organizationId": "org_7Hf3kQ2",
    "organizationName": "Support API",
    "email": "teammate@example.com",
    "role": "developer",
    "status": "active",
    "inviteUrl": "https://api.example.com",
    "createdAt": "2026-05-29T18:20:11Z",
    "expiresAt": "2026-05-29T18:20:11Z",
    "lastSentAt": "2026-05-29T18:20:11Z",
    "acceptedAt": "2026-05-29T18:20:11Z",
    "acceptedByUserId": "id_123",
    "revokedAt": "2026-05-29T18:20:11Z",
    "revokedReason": "No longer needed",
    "lastSendError": "string"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/invitationsInvite a teammate by email.Invite a teammate by email.

Request bodyCreateOrganizationInvitationRequest · application/json

Field	Type	Required
`email`	`string`	Required
`role`	`string`	Required

{
  "email": "teammate@example.com",
  "role": "developer"
}

Response body200OrganizationInvitationResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`organizationName`	`string \| null`	Optional
`email`	`string \| null`	Optional
`role`	`string \| null`	Optional
`status`	`string \| null`	Optional
`inviteUrl`	`string \| null`	Optional
`createdAt`	`string(date-time)`	Optional
`expiresAt`	`string(date-time)`	Optional
`lastSentAt`	`string(date-time) \| null`	Optional
`acceptedAt`	`string(date-time) \| null`	Optional
`acceptedByUserId`	`string \| null`	Optional
`revokedAt`	`string(date-time) \| null`	Optional
`revokedReason`	`string \| null`	Optional
`lastSendError`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "organizationName": "Support API",
  "email": "teammate@example.com",
  "role": "developer",
  "status": "active",
  "inviteUrl": "https://api.example.com",
  "createdAt": "2026-05-29T18:20:11Z",
  "expiresAt": "2026-05-29T18:20:11Z",
  "lastSentAt": "2026-05-29T18:20:11Z",
  "acceptedAt": "2026-05-29T18:20:11Z",
  "acceptedByUserId": "id_123",
  "revokedAt": "2026-05-29T18:20:11Z",
  "revokedReason": "No longer needed",
  "lastSendError": "string"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/invitations/{invitationId}/resendResend an invitation email.Resend an invitation email.

Request bodynone

No request body.

Response body200OrganizationInvitationResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`organizationName`	`string \| null`	Optional
`email`	`string \| null`	Optional
`role`	`string \| null`	Optional
`status`	`string \| null`	Optional
`inviteUrl`	`string \| null`	Optional
`createdAt`	`string(date-time)`	Optional
`expiresAt`	`string(date-time)`	Optional
`lastSentAt`	`string(date-time) \| null`	Optional
`acceptedAt`	`string(date-time) \| null`	Optional
`acceptedByUserId`	`string \| null`	Optional
`revokedAt`	`string(date-time) \| null`	Optional
`revokedReason`	`string \| null`	Optional
`lastSendError`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "organizationName": "Support API",
  "email": "teammate@example.com",
  "role": "developer",
  "status": "active",
  "inviteUrl": "https://api.example.com",
  "createdAt": "2026-05-29T18:20:11Z",
  "expiresAt": "2026-05-29T18:20:11Z",
  "lastSentAt": "2026-05-29T18:20:11Z",
  "acceptedAt": "2026-05-29T18:20:11Z",
  "acceptedByUserId": "id_123",
  "revokedAt": "2026-05-29T18:20:11Z",
  "revokedReason": "No longer needed",
  "lastSendError": "string"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/invitations/{invitationId}/revokeRevoke an invitation.Revoke an invitation.

Request bodyRevokeOrganizationInvitationRequest · application/json

Field	Type	Required
`reason`	`string \| null`	Optional

{
  "reason": "No longer needed"
}

Response body200OrganizationInvitationResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`organizationName`	`string \| null`	Optional
`email`	`string \| null`	Optional
`role`	`string \| null`	Optional
`status`	`string \| null`	Optional
`inviteUrl`	`string \| null`	Optional
`createdAt`	`string(date-time)`	Optional
`expiresAt`	`string(date-time)`	Optional
`lastSentAt`	`string(date-time) \| null`	Optional
`acceptedAt`	`string(date-time) \| null`	Optional
`acceptedByUserId`	`string \| null`	Optional
`revokedAt`	`string(date-time) \| null`	Optional
`revokedReason`	`string \| null`	Optional
`lastSendError`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "organizationName": "Support API",
  "email": "teammate@example.com",
  "role": "developer",
  "status": "active",
  "inviteUrl": "https://api.example.com",
  "createdAt": "2026-05-29T18:20:11Z",
  "expiresAt": "2026-05-29T18:20:11Z",
  "lastSentAt": "2026-05-29T18:20:11Z",
  "acceptedAt": "2026-05-29T18:20:11Z",
  "acceptedByUserId": "id_123",
  "revokedAt": "2026-05-29T18:20:11Z",
  "revokedReason": "No longer needed",
  "lastSendError": "string"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/api-keysList service-account keys.List service-account keys.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].name`	`string \| null`	Optional
`[].clientId`	`string \| null`	Optional
`[].description`	`string \| null`	Optional
`[].createdAt`	`string(date-time)`	Optional
`[].lastUsedAt`	`string(date-time) \| null`	Optional
`[].expiresAt`	`string(date-time) \| null`	Optional
`[].isRevoked`	`boolean`	Optional
`[].roleKey`	`string \| null`	Optional
`[].roleName`	`string \| null`	Optional

[
  {
    "id": "id_123",
    "name": "Support API",
    "clientId": "id_123",
    "description": "Routes support ticket operations to MCP clients.",
    "createdAt": "2026-05-29T18:20:11Z",
    "lastUsedAt": "2026-05-29T18:20:11Z",
    "expiresAt": "2026-05-29T18:20:11Z",
    "isRevoked": true,
    "roleKey": "developer",
    "roleName": "Support API"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/api-keys/rolesList roles assignable to keys.List roles assignable to keys.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].key`	`string \| null`	Optional
`[].name`	`string \| null`	Optional
`[].description`	`string \| null`	Optional

[
  {
    "key": "string",
    "name": "Support API",
    "description": "Routes support ticket operations to MCP clients."
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/api-keysCreate a service-account key. The full secret is returned only once.Create a service-account key. The full secret is returned only once.

Request bodyCreateApiKeyRequest · application/json

Field	Type	Required
`name`	`string`	Required
`description`	`string \| null`	Optional
`expiresAt`	`string(date-time) \| null`	Optional
`roleKey`	`string \| null`	Optional

{
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "expiresAt": "2026-05-29T18:20:11Z",
  "roleKey": "developer"
}

Response body201CreateApiKeyResponse

Field	Type	Required
`id`	`string \| null`	Optional
`name`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`fullKey`	`string \| null`	Optional
`createdAt`	`string(date-time)`	Optional
`expiresAt`	`string(date-time) \| null`	Optional
`roleKey`	`string \| null`	Optional
`roleName`	`string \| null`	Optional

{
  "id": "id_123",
  "name": "Support API",
  "clientId": "id_123",
  "fullKey": "string",
  "createdAt": "2026-05-29T18:20:11Z",
  "expiresAt": "2026-05-29T18:20:11Z",
  "roleKey": "developer",
  "roleName": "Support API"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}/api-keys/{keyId}Revoke a service-account key.Revoke a service-account key.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/authorization/checkCheck organization-level permissions.Check organization-level permissions.

Request bodyCheckOrganizationPermissionsRequest · application/json

Field	Type	Required
`permissionKeys`	`string[]`	Required

{
  "permissionKeys": [
    "string"
  ]
}

Response body200CheckOrganizationPermissionsResponse

Field	Type	Required
`organizationId`	`string \| null`	Optional
`resourceId`	`string \| null`	Optional
`permissions`	`object \| null`	Optional

{
  "organizationId": "org_7Hf3kQ2",
  "resourceId": "id_123",
  "permissions": {}
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/authorization/check-entitiesCheck permissions on specific resources.Check permissions on specific resources.

Request bodyCheckEntityPermissionsRequest · application/json

Field	Type	Required
`entities`	`EntityPermissionCheckRequest[]`	Required
`entities[].entityType`	`string`	Required
`entities[].entityId`	`string`	Required
`entities[].permissionKeys`	`string[]`	Required

{
  "entities": [
    {
      "entityType": "string",
      "entityId": "id_123",
      "permissionKeys": [
        "string"
      ]
    }
  ]
}

Response body200CheckEntityPermissionsResponse

Field	Type	Required
`organizationId`	`string \| null`	Optional
`permissions`	`object \| null`	Optional

{
  "organizationId": "org_7Hf3kQ2",
  "permissions": {}
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

MCP servers#

Create a server from an OpenAPI spec, shape the generated tools, deploy it, inspect runtime health, and attach Gateway or custom domains.

Lifecycle and settings#

MethodEndpointDescriptionCopy

GET/api/v1/organizations/{orgId}/mcp-serversList MCP servers.List MCP servers.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].organizationId`	`string \| null`	Optional
`[].slug`	`string \| null`	Optional
`[].gatewayPublicId`	`string \| null`	Optional
`[].name`	`string \| null`	Optional
`[].description`	`string \| null`	Optional
`[].status`	`string \| null`	Optional
`[].kind`	`string \| null`	Optional
`[].runtimeType`	`string \| null`	Optional
`[].openApiSpecUrl`	`string \| null`	Optional
`[].totalInvocations`	`integer(int32)`	Optional
`[].toolCount`	`integer(int32)`	Optional
`[].createdOn`	`string(date-time)`	Optional
`[].hasOpenApiSpec`	`boolean`	Optional
`[].openApiSpecSource`	`string \| null`	Optional
`[].openApiSpecFileName`	`string \| null`	Optional
`[].openApiSpecUpdatedAt`	`string(date-time) \| null`	Optional
`[].hasGateway`	`boolean`	Optional
`[].toolsManaged`	`boolean`	Optional
`[].gateway`	`McpServerGatewayResponse`	Optional
`[].gateway.gatewayId`	`string \| null`	Optional
`[].gateway.gatewayName`	`string \| null`	Optional
`[].gateway.provider`	`string \| null`	Optional
`[].gateway.publicId`	`string \| null`	Optional
`[].gateway.publicGatewayUrl`	`string \| null`	Optional
`[].gateway.protectedResourceMetadataUrl`	`string \| null`	Optional
`[].gateway.pathProtectedResourceMetadataUrl`	`string \| null`	Optional
`[].gateway.hostedAuthorizationServerUrl`	`string \| null`	Optional
`[].gateway.hostedAuthorizationServerMetadataUrl`	`string \| null`	Optional
`[].gateway.authorizationEndpoint`	`string \| null`	Optional
`[].gateway.tokenEndpoint`	`string \| null`	Optional
`[].gateway.registrationEndpoint`	`string \| null`	Optional
`[].gateway.hostedResource`	`string \| null`	Optional
`[].gateway.authorizationServerUrl`	`string \| null`	Optional
`[].gateway.authorizationServerMetadataUrl`	`string \| null`	Optional
`[].gateway.clientId`	`string \| null`	Optional
`[].gateway.gatewayDefaultResource`	`string \| null`	Optional
`[].gateway.gatewayDefaultScopes`	`string[] \| null`	Optional
`[].gateway.resource`	`string \| null`	Optional
`[].gateway.scopes`	`string[] \| null`	Optional
`[].gateway.usesGatewayDefaultResource`	`boolean`	Optional
`[].gateway.usesGatewayDefaultScopes`	`boolean`	Optional
`[].gateway.resourceOverride`	`string \| null`	Optional
`[].gateway.scopesOverride`	`string[] \| null`	Optional
`[].gateway.workerBaseUrl`	`string \| null`	Optional
`[].gateway.runtimeType`	`string \| null`	Optional
`[].catalogStatus`	`string \| null`	Optional
`[].catalogError`	`string \| null`	Optional
`[].installGuideEnabled`	`boolean`	Optional

[
  {
    "id": "id_123",
    "organizationId": "org_7Hf3kQ2",
    "slug": "support-api",
    "gatewayPublicId": "gw_4Jk9nQa",
    "name": "Support API",
    "description": "Routes support ticket operations to MCP clients.",
    "status": "active",
    "kind": "string",
    "runtimeType": "string",
    "openApiSpecUrl": "https://api.example.com",
    "totalInvocations": 1,
    "toolCount": 1,
    "createdOn": "2026-05-29T18:20:11Z",
    "hasOpenApiSpec": true,
    "openApiSpecSource": "upload",
    "openApiSpecFileName": "Support API",
    "openApiSpecUpdatedAt": "2026-05-29T18:20:11Z",
    "hasGateway": true,
    "toolsManaged": true,
    "gateway": {
      "gatewayId": "gw_4Jk9nQa",
      "gatewayName": "Support API",
      "provider": "openai",
      "publicId": "id_123",
      "publicGatewayUrl": "https://api.example.com",
      "protectedResourceMetadataUrl": "https://api.example.com",
      "pathProtectedResourceMetadataUrl": "https://api.example.com",
      "hostedAuthorizationServerUrl": "https://api.example.com",
      "hostedAuthorizationServerMetadataUrl": "https://api.example.com",
      "authorizationEndpoint": "string",
      "tokenEndpoint": "redacted",
      "registrationEndpoint": "string",
      "hostedResource": "string",
      "authorizationServerUrl": "https://api.example.com",
      "authorizationServerMetadataUrl": "https://api.example.com",
      "clientId": "id_123",
      "gatewayDefaultResource": "string",
      "gatewayDefaultScopes": [
        "openid"
      ],
      "resource": "string",
      "scopes": [
        "openid"
      ],
      "usesGatewayDefaultResource": true,
      "usesGatewayDefaultScopes": true,
      "resourceOverride": "string",
      "scopesOverride": [
        "openid"
      ],
      "workerBaseUrl": "https://api.example.com",
      "runtimeType": "string"
    },
    "catalogStatus": "active",
    "catalogError": "string",
    "installGuideEnabled": true
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-serversCreate a server. Generated OpenAPI servers publish through MCP Stack Host.Create a server. Generated OpenAPI servers publish through MCP Stack Host.

Request bodyCreateMcpServerRequest · application/json

Field	Type	Required
`name`	`string`	Required
`slug`	`string`	Required
`kind`	`string \| null`	Optional
`description`	`string \| null`	Optional
`status`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`openApiSpecUrl`	`string \| null`	Optional
`openApiSpecJson`	`string \| null`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional
`apiBaseUrl`	`string \| null`	Optional
`serverUrl`	`string \| null`	Optional
`enabledEndpointsJson`	`string \| null`	Optional
`generationConfigJson`	`string \| null`	Optional
`authConfigJson`	`string \| null`	Optional
`hostingConfigJson`	`string \| null`	Optional
`runtimeConfigJson`	`string \| null`	Optional
`usagePolicyJson`	`string \| null`	Optional
`gatewayId`	`string \| null`	Optional
`gatewayAttachmentPublicId`	`string \| null`	Optional
`gatewayResourceOverride`	`string \| null`	Optional
`gatewayScopesOverride`	`string[] \| null`	Optional

{
  "name": "Support API",
  "slug": "support-api",
  "kind": "string",
  "description": "Routes support ticket operations to MCP clients.",
  "status": "active",
  "runtimeType": "string",
  "openApiSpecUrl": "https://api.example.com",
  "openApiSpecJson": "{ \"openapi\": \"3.1.0\", \"paths\": {} }",
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API",
  "apiBaseUrl": "https://api.example.com",
  "serverUrl": "https://api.example.com",
  "enabledEndpointsJson": "string",
  "generationConfigJson": "string",
  "authConfigJson": "string",
  "hostingConfigJson": "string",
  "runtimeConfigJson": "string",
  "usagePolicyJson": "string",
  "gatewayId": "gw_4Jk9nQa",
  "gatewayAttachmentPublicId": "gw_4Jk9nQa",
  "gatewayResourceOverride": "string",
  "gatewayScopesOverride": [
    "openid"
  ]
}

Response body201McpServerDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`gatewayPublicId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`status`	`string \| null`	Optional
`kind`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`openApiSpecUrl`	`string \| null`	Optional
`hasOpenApiSpec`	`boolean`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional
`openApiSpecUpdatedAt`	`string(date-time) \| null`	Optional
`apiBaseUrl`	`string \| null`	Optional
`serverUrl`	`string \| null`	Optional
`totalInvocations`	`integer(int32)`	Optional
`createdOn`	`string(date-time)`	Optional
`tools`	`ToolResponse[] \| null`	Optional
`tools[].id`	`string \| null`	Optional
`tools[].name`	`string \| null`	Optional
`tools[].toolKey`	`string \| null`	Optional
`tools[].displayName`	`string \| null`	Optional
`tools[].description`	`string \| null`	Optional
`tools[].httpMethod`	`string \| null`	Optional
`tools[].httpPath`	`string \| null`	Optional
`tools[].isEnabled`	`boolean`	Optional
`tools[].toolNamingVersion`	`integer(int32)`	Optional
`tools[].source`	`string \| null`	Optional
`tools[].isManaged`	`boolean`	Optional
`tools[].sourceDescription`	`string \| null`	Optional
`tools[].descriptionOverride`	`string \| null`	Optional
`tools[].instructions`	`string \| null`	Optional
`tools[].whenToUse`	`string \| null`	Optional
`tools[].whenNotToUse`	`string \| null`	Optional
`tools[].examplesJson`	`string \| null`	Optional
`tools[].openApiOperationId`	`string \| null`	Optional
`tools[].lastSeenInSourceAt`	`string(date-time) \| null`	Optional
`tools[].removedFromSourceAt`	`string(date-time) \| null`	Optional
`tools[].rulesLastModifiedOn`	`string(date-time) \| null`	Optional
`hasGateway`	`boolean`	Optional
`toolsManaged`	`boolean`	Optional
`gateway`	`McpServerGatewayResponse`	Optional
`gateway.gatewayId`	`string \| null`	Optional
`gateway.gatewayName`	`string \| null`	Optional
`gateway.provider`	`string \| null`	Optional
`gateway.publicId`	`string \| null`	Optional
`gateway.publicGatewayUrl`	`string \| null`	Optional
`gateway.protectedResourceMetadataUrl`	`string \| null`	Optional
`gateway.pathProtectedResourceMetadataUrl`	`string \| null`	Optional
`gateway.hostedAuthorizationServerUrl`	`string \| null`	Optional
`gateway.hostedAuthorizationServerMetadataUrl`	`string \| null`	Optional
`gateway.authorizationEndpoint`	`string \| null`	Optional
`gateway.tokenEndpoint`	`string \| null`	Optional
`gateway.registrationEndpoint`	`string \| null`	Optional
`gateway.hostedResource`	`string \| null`	Optional
`gateway.authorizationServerUrl`	`string \| null`	Optional
`gateway.authorizationServerMetadataUrl`	`string \| null`	Optional
`gateway.clientId`	`string \| null`	Optional
`gateway.gatewayDefaultResource`	`string \| null`	Optional
`gateway.gatewayDefaultScopes`	`string[] \| null`	Optional
`gateway.resource`	`string \| null`	Optional
`gateway.scopes`	`string[] \| null`	Optional
`gateway.usesGatewayDefaultResource`	`boolean`	Optional
`gateway.usesGatewayDefaultScopes`	`boolean`	Optional
`gateway.resourceOverride`	`string \| null`	Optional
`gateway.scopesOverride`	`string[] \| null`	Optional
`gateway.workerBaseUrl`	`string \| null`	Optional
`gateway.runtimeType`	`string \| null`	Optional
`catalogStatus`	`string \| null`	Optional
`catalogCheckedAt`	`string(date-time) \| null`	Optional
`catalogError`	`string \| null`	Optional
`expectedToolKeys`	`string[] \| null`	Optional
`actualToolKeys`	`string[] \| null`	Optional
`missingToolKeys`	`string[] \| null`	Optional
`unexpectedToolKeys`	`string[] \| null`	Optional
`installGuideEnabled`	`boolean`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "slug": "support-api",
  "gatewayPublicId": "gw_4Jk9nQa",
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "status": "active",
  "kind": "string",
  "runtimeType": "string",
  "openApiSpecUrl": "https://api.example.com",
  "hasOpenApiSpec": true,
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API",
  "openApiSpecUpdatedAt": "2026-05-29T18:20:11Z",
  "apiBaseUrl": "https://api.example.com",
  "serverUrl": "https://api.example.com",
  "totalInvocations": 1,
  "createdOn": "2026-05-29T18:20:11Z",
  "tools": [
    {
      "id": "id_123",
      "name": "Support API",
      "toolKey": "string",
      "displayName": "Support API",
      "description": "Routes support ticket operations to MCP clients.",
      "httpMethod": "POST",
      "httpPath": "/tickets/{id}/notes",
      "isEnabled": true,
      "toolNamingVersion": 1,
      "source": "string",
      "isManaged": true,
      "sourceDescription": "Routes support ticket operations to MCP clients.",
      "descriptionOverride": "Routes support ticket operations to MCP clients.",
      "instructions": "string",
      "whenToUse": "string",
      "whenNotToUse": "string",
      "examplesJson": "string",
      "openApiOperationId": "id_123",
      "lastSeenInSourceAt": "2026-05-29T18:20:11Z",
      "removedFromSourceAt": "2026-05-29T18:20:11Z",
      "rulesLastModifiedOn": "2026-05-29T18:20:11Z"
    }
  ],
  "hasGateway": true,
  "toolsManaged": true,
  "gateway": {
    "gatewayId": "gw_4Jk9nQa",
    "gatewayName": "Support API",
    "provider": "openai",
    "publicId": "id_123",
    "publicGatewayUrl": "https://api.example.com",
    "protectedResourceMetadataUrl": "https://api.example.com",
    "pathProtectedResourceMetadataUrl": "https://api.example.com",
    "hostedAuthorizationServerUrl": "https://api.example.com",
    "hostedAuthorizationServerMetadataUrl": "https://api.example.com",
    "authorizationEndpoint": "string",
    "tokenEndpoint": "redacted",
    "registrationEndpoint": "string",
    "hostedResource": "string",
    "authorizationServerUrl": "https://api.example.com",
    "authorizationServerMetadataUrl": "https://api.example.com",
    "clientId": "id_123",
    "gatewayDefaultResource": "string",
    "gatewayDefaultScopes": [
      "openid"
    ],
    "resource": "string",
    "scopes": [
      "openid"
    ],
    "usesGatewayDefaultResource": true,
    "usesGatewayDefaultScopes": true,
    "resourceOverride": "string",
    "scopesOverride": [
      "openid"
    ],
    "workerBaseUrl": "https://api.example.com",
    "runtimeType": "string"
  },
  "catalogStatus": "active",
  "catalogCheckedAt": "2026-05-29T18:20:11Z",
  "catalogError": "string",
  "expectedToolKeys": [
    "string"
  ],
  "actualToolKeys": [
    "string"
  ],
  "missingToolKeys": [
    "string"
  ],
  "unexpectedToolKeys": [
    "string"
  ],
  "installGuideEnabled": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}Get a server, including its tools.Get a server, including its tools.

Request bodynone

No request body.

Response body200McpServerDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`gatewayPublicId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`status`	`string \| null`	Optional
`kind`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`openApiSpecUrl`	`string \| null`	Optional
`hasOpenApiSpec`	`boolean`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional
`openApiSpecUpdatedAt`	`string(date-time) \| null`	Optional
`apiBaseUrl`	`string \| null`	Optional
`serverUrl`	`string \| null`	Optional
`totalInvocations`	`integer(int32)`	Optional
`createdOn`	`string(date-time)`	Optional
`tools`	`ToolResponse[] \| null`	Optional
`tools[].id`	`string \| null`	Optional
`tools[].name`	`string \| null`	Optional
`tools[].toolKey`	`string \| null`	Optional
`tools[].displayName`	`string \| null`	Optional
`tools[].description`	`string \| null`	Optional
`tools[].httpMethod`	`string \| null`	Optional
`tools[].httpPath`	`string \| null`	Optional
`tools[].isEnabled`	`boolean`	Optional
`tools[].toolNamingVersion`	`integer(int32)`	Optional
`tools[].source`	`string \| null`	Optional
`tools[].isManaged`	`boolean`	Optional
`tools[].sourceDescription`	`string \| null`	Optional
`tools[].descriptionOverride`	`string \| null`	Optional
`tools[].instructions`	`string \| null`	Optional
`tools[].whenToUse`	`string \| null`	Optional
`tools[].whenNotToUse`	`string \| null`	Optional
`tools[].examplesJson`	`string \| null`	Optional
`tools[].openApiOperationId`	`string \| null`	Optional
`tools[].lastSeenInSourceAt`	`string(date-time) \| null`	Optional
`tools[].removedFromSourceAt`	`string(date-time) \| null`	Optional
`tools[].rulesLastModifiedOn`	`string(date-time) \| null`	Optional
`hasGateway`	`boolean`	Optional
`toolsManaged`	`boolean`	Optional
`gateway`	`McpServerGatewayResponse`	Optional
`gateway.gatewayId`	`string \| null`	Optional
`gateway.gatewayName`	`string \| null`	Optional
`gateway.provider`	`string \| null`	Optional
`gateway.publicId`	`string \| null`	Optional
`gateway.publicGatewayUrl`	`string \| null`	Optional
`gateway.protectedResourceMetadataUrl`	`string \| null`	Optional
`gateway.pathProtectedResourceMetadataUrl`	`string \| null`	Optional
`gateway.hostedAuthorizationServerUrl`	`string \| null`	Optional
`gateway.hostedAuthorizationServerMetadataUrl`	`string \| null`	Optional
`gateway.authorizationEndpoint`	`string \| null`	Optional
`gateway.tokenEndpoint`	`string \| null`	Optional
`gateway.registrationEndpoint`	`string \| null`	Optional
`gateway.hostedResource`	`string \| null`	Optional
`gateway.authorizationServerUrl`	`string \| null`	Optional
`gateway.authorizationServerMetadataUrl`	`string \| null`	Optional
`gateway.clientId`	`string \| null`	Optional
`gateway.gatewayDefaultResource`	`string \| null`	Optional
`gateway.gatewayDefaultScopes`	`string[] \| null`	Optional
`gateway.resource`	`string \| null`	Optional
`gateway.scopes`	`string[] \| null`	Optional
`gateway.usesGatewayDefaultResource`	`boolean`	Optional
`gateway.usesGatewayDefaultScopes`	`boolean`	Optional
`gateway.resourceOverride`	`string \| null`	Optional
`gateway.scopesOverride`	`string[] \| null`	Optional
`gateway.workerBaseUrl`	`string \| null`	Optional
`gateway.runtimeType`	`string \| null`	Optional
`catalogStatus`	`string \| null`	Optional
`catalogCheckedAt`	`string(date-time) \| null`	Optional
`catalogError`	`string \| null`	Optional
`expectedToolKeys`	`string[] \| null`	Optional
`actualToolKeys`	`string[] \| null`	Optional
`missingToolKeys`	`string[] \| null`	Optional
`unexpectedToolKeys`	`string[] \| null`	Optional
`installGuideEnabled`	`boolean`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "slug": "support-api",
  "gatewayPublicId": "gw_4Jk9nQa",
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "status": "active",
  "kind": "string",
  "runtimeType": "string",
  "openApiSpecUrl": "https://api.example.com",
  "hasOpenApiSpec": true,
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API",
  "openApiSpecUpdatedAt": "2026-05-29T18:20:11Z",
  "apiBaseUrl": "https://api.example.com",
  "serverUrl": "https://api.example.com",
  "totalInvocations": 1,
  "createdOn": "2026-05-29T18:20:11Z",
  "tools": [
    {
      "id": "id_123",
      "name": "Support API",
      "toolKey": "string",
      "displayName": "Support API",
      "description": "Routes support ticket operations to MCP clients.",
      "httpMethod": "POST",
      "httpPath": "/tickets/{id}/notes",
      "isEnabled": true,
      "toolNamingVersion": 1,
      "source": "string",
      "isManaged": true,
      "sourceDescription": "Routes support ticket operations to MCP clients.",
      "descriptionOverride": "Routes support ticket operations to MCP clients.",
      "instructions": "string",
      "whenToUse": "string",
      "whenNotToUse": "string",
      "examplesJson": "string",
      "openApiOperationId": "id_123",
      "lastSeenInSourceAt": "2026-05-29T18:20:11Z",
      "removedFromSourceAt": "2026-05-29T18:20:11Z",
      "rulesLastModifiedOn": "2026-05-29T18:20:11Z"
    }
  ],
  "hasGateway": true,
  "toolsManaged": true,
  "gateway": {
    "gatewayId": "gw_4Jk9nQa",
    "gatewayName": "Support API",
    "provider": "openai",
    "publicId": "id_123",
    "publicGatewayUrl": "https://api.example.com",
    "protectedResourceMetadataUrl": "https://api.example.com",
    "pathProtectedResourceMetadataUrl": "https://api.example.com",
    "hostedAuthorizationServerUrl": "https://api.example.com",
    "hostedAuthorizationServerMetadataUrl": "https://api.example.com",
    "authorizationEndpoint": "string",
    "tokenEndpoint": "redacted",
    "registrationEndpoint": "string",
    "hostedResource": "string",
    "authorizationServerUrl": "https://api.example.com",
    "authorizationServerMetadataUrl": "https://api.example.com",
    "clientId": "id_123",
    "gatewayDefaultResource": "string",
    "gatewayDefaultScopes": [
      "openid"
    ],
    "resource": "string",
    "scopes": [
      "openid"
    ],
    "usesGatewayDefaultResource": true,
    "usesGatewayDefaultScopes": true,
    "resourceOverride": "string",
    "scopesOverride": [
      "openid"
    ],
    "workerBaseUrl": "https://api.example.com",
    "runtimeType": "string"
  },
  "catalogStatus": "active",
  "catalogCheckedAt": "2026-05-29T18:20:11Z",
  "catalogError": "string",
  "expectedToolKeys": [
    "string"
  ],
  "actualToolKeys": [
    "string"
  ],
  "missingToolKeys": [
    "string"
  ],
  "unexpectedToolKeys": [
    "string"
  ],
  "installGuideEnabled": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PATCH/api/v1/organizations/{orgId}/mcp-servers/{serverId}Update server metadata or stored spec fields.Update server metadata or stored spec fields.

Request bodyUpdateMcpServerRequest · application/json

Field	Type	Required
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`status`	`string \| null`	Optional
`serverUrl`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`openApiSpecUrl`	`string \| null`	Optional
`openApiSpecJson`	`string \| null`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional
`runtimeConfigJson`	`string \| null`	Optional
`usagePolicyJson`	`string \| null`	Optional
`gatewayId`	`string \| null`	Optional
`gatewayAttachmentPublicId`	`string \| null`	Optional
`installGuideEnabled`	`boolean \| null`	Optional

{
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "status": "active",
  "serverUrl": "https://api.example.com",
  "runtimeType": "string",
  "openApiSpecUrl": "https://api.example.com",
  "openApiSpecJson": "{ \"openapi\": \"3.1.0\", \"paths\": {} }",
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API",
  "runtimeConfigJson": "string",
  "usagePolicyJson": "string",
  "gatewayId": "gw_4Jk9nQa",
  "gatewayAttachmentPublicId": "gw_4Jk9nQa",
  "installGuideEnabled": true
}

Response body200McpServerDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`gatewayPublicId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`status`	`string \| null`	Optional
`kind`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`openApiSpecUrl`	`string \| null`	Optional
`hasOpenApiSpec`	`boolean`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional
`openApiSpecUpdatedAt`	`string(date-time) \| null`	Optional
`apiBaseUrl`	`string \| null`	Optional
`serverUrl`	`string \| null`	Optional
`totalInvocations`	`integer(int32)`	Optional
`createdOn`	`string(date-time)`	Optional
`tools`	`ToolResponse[] \| null`	Optional
`tools[].id`	`string \| null`	Optional
`tools[].name`	`string \| null`	Optional
`tools[].toolKey`	`string \| null`	Optional
`tools[].displayName`	`string \| null`	Optional
`tools[].description`	`string \| null`	Optional
`tools[].httpMethod`	`string \| null`	Optional
`tools[].httpPath`	`string \| null`	Optional
`tools[].isEnabled`	`boolean`	Optional
`tools[].toolNamingVersion`	`integer(int32)`	Optional
`tools[].source`	`string \| null`	Optional
`tools[].isManaged`	`boolean`	Optional
`tools[].sourceDescription`	`string \| null`	Optional
`tools[].descriptionOverride`	`string \| null`	Optional
`tools[].instructions`	`string \| null`	Optional
`tools[].whenToUse`	`string \| null`	Optional
`tools[].whenNotToUse`	`string \| null`	Optional
`tools[].examplesJson`	`string \| null`	Optional
`tools[].openApiOperationId`	`string \| null`	Optional
`tools[].lastSeenInSourceAt`	`string(date-time) \| null`	Optional
`tools[].removedFromSourceAt`	`string(date-time) \| null`	Optional
`tools[].rulesLastModifiedOn`	`string(date-time) \| null`	Optional
`hasGateway`	`boolean`	Optional
`toolsManaged`	`boolean`	Optional
`gateway`	`McpServerGatewayResponse`	Optional
`gateway.gatewayId`	`string \| null`	Optional
`gateway.gatewayName`	`string \| null`	Optional
`gateway.provider`	`string \| null`	Optional
`gateway.publicId`	`string \| null`	Optional
`gateway.publicGatewayUrl`	`string \| null`	Optional
`gateway.protectedResourceMetadataUrl`	`string \| null`	Optional
`gateway.pathProtectedResourceMetadataUrl`	`string \| null`	Optional
`gateway.hostedAuthorizationServerUrl`	`string \| null`	Optional
`gateway.hostedAuthorizationServerMetadataUrl`	`string \| null`	Optional
`gateway.authorizationEndpoint`	`string \| null`	Optional
`gateway.tokenEndpoint`	`string \| null`	Optional
`gateway.registrationEndpoint`	`string \| null`	Optional
`gateway.hostedResource`	`string \| null`	Optional
`gateway.authorizationServerUrl`	`string \| null`	Optional
`gateway.authorizationServerMetadataUrl`	`string \| null`	Optional
`gateway.clientId`	`string \| null`	Optional
`gateway.gatewayDefaultResource`	`string \| null`	Optional
`gateway.gatewayDefaultScopes`	`string[] \| null`	Optional
`gateway.resource`	`string \| null`	Optional
`gateway.scopes`	`string[] \| null`	Optional
`gateway.usesGatewayDefaultResource`	`boolean`	Optional
`gateway.usesGatewayDefaultScopes`	`boolean`	Optional
`gateway.resourceOverride`	`string \| null`	Optional
`gateway.scopesOverride`	`string[] \| null`	Optional
`gateway.workerBaseUrl`	`string \| null`	Optional
`gateway.runtimeType`	`string \| null`	Optional
`catalogStatus`	`string \| null`	Optional
`catalogCheckedAt`	`string(date-time) \| null`	Optional
`catalogError`	`string \| null`	Optional
`expectedToolKeys`	`string[] \| null`	Optional
`actualToolKeys`	`string[] \| null`	Optional
`missingToolKeys`	`string[] \| null`	Optional
`unexpectedToolKeys`	`string[] \| null`	Optional
`installGuideEnabled`	`boolean`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "slug": "support-api",
  "gatewayPublicId": "gw_4Jk9nQa",
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "status": "active",
  "kind": "string",
  "runtimeType": "string",
  "openApiSpecUrl": "https://api.example.com",
  "hasOpenApiSpec": true,
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API",
  "openApiSpecUpdatedAt": "2026-05-29T18:20:11Z",
  "apiBaseUrl": "https://api.example.com",
  "serverUrl": "https://api.example.com",
  "totalInvocations": 1,
  "createdOn": "2026-05-29T18:20:11Z",
  "tools": [
    {
      "id": "id_123",
      "name": "Support API",
      "toolKey": "string",
      "displayName": "Support API",
      "description": "Routes support ticket operations to MCP clients.",
      "httpMethod": "POST",
      "httpPath": "/tickets/{id}/notes",
      "isEnabled": true,
      "toolNamingVersion": 1,
      "source": "string",
      "isManaged": true,
      "sourceDescription": "Routes support ticket operations to MCP clients.",
      "descriptionOverride": "Routes support ticket operations to MCP clients.",
      "instructions": "string",
      "whenToUse": "string",
      "whenNotToUse": "string",
      "examplesJson": "string",
      "openApiOperationId": "id_123",
      "lastSeenInSourceAt": "2026-05-29T18:20:11Z",
      "removedFromSourceAt": "2026-05-29T18:20:11Z",
      "rulesLastModifiedOn": "2026-05-29T18:20:11Z"
    }
  ],
  "hasGateway": true,
  "toolsManaged": true,
  "gateway": {
    "gatewayId": "gw_4Jk9nQa",
    "gatewayName": "Support API",
    "provider": "openai",
    "publicId": "id_123",
    "publicGatewayUrl": "https://api.example.com",
    "protectedResourceMetadataUrl": "https://api.example.com",
    "pathProtectedResourceMetadataUrl": "https://api.example.com",
    "hostedAuthorizationServerUrl": "https://api.example.com",
    "hostedAuthorizationServerMetadataUrl": "https://api.example.com",
    "authorizationEndpoint": "string",
    "tokenEndpoint": "redacted",
    "registrationEndpoint": "string",
    "hostedResource": "string",
    "authorizationServerUrl": "https://api.example.com",
    "authorizationServerMetadataUrl": "https://api.example.com",
    "clientId": "id_123",
    "gatewayDefaultResource": "string",
    "gatewayDefaultScopes": [
      "openid"
    ],
    "resource": "string",
    "scopes": [
      "openid"
    ],
    "usesGatewayDefaultResource": true,
    "usesGatewayDefaultScopes": true,
    "resourceOverride": "string",
    "scopesOverride": [
      "openid"
    ],
    "workerBaseUrl": "https://api.example.com",
    "runtimeType": "string"
  },
  "catalogStatus": "active",
  "catalogCheckedAt": "2026-05-29T18:20:11Z",
  "catalogError": "string",
  "expectedToolKeys": [
    "string"
  ],
  "actualToolKeys": [
    "string"
  ],
  "missingToolKeys": [
    "string"
  ],
  "unexpectedToolKeys": [
    "string"
  ],
  "installGuideEnabled": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}/mcp-servers/{serverId}Delete a server. Hosted runtime cleanup is automatic.Delete a server. Hosted runtime cleanup is automatic.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/configGet the resolved server configuration.Get the resolved server configuration.

Request bodynone

No request body.

Response body200McpServerConfigResponse

Field	Type	Required
`id`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`gatewayPublicId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`kind`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`openApiSpecUrl`	`string \| null`	Optional
`hasOpenApiSpec`	`boolean`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional
`openApiSpecUpdatedAt`	`string(date-time) \| null`	Optional
`apiBaseUrl`	`string \| null`	Optional
`serverUrl`	`string \| null`	Optional
`enabledEndpointsJson`	`string \| null`	Optional
`generationConfigJson`	`string \| null`	Optional
`authConfigJson`	`string \| null`	Optional
`hostingConfigJson`	`string \| null`	Optional
`runtimeConfigJson`	`string \| null`	Optional
`usagePolicyJson`	`string \| null`	Optional
`gatewayId`	`string \| null`	Optional

{
  "id": "id_123",
  "slug": "support-api",
  "gatewayPublicId": "gw_4Jk9nQa",
  "name": "Support API",
  "kind": "string",
  "runtimeType": "string",
  "openApiSpecUrl": "https://api.example.com",
  "hasOpenApiSpec": true,
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API",
  "openApiSpecUpdatedAt": "2026-05-29T18:20:11Z",
  "apiBaseUrl": "https://api.example.com",
  "serverUrl": "https://api.example.com",
  "enabledEndpointsJson": "string",
  "generationConfigJson": "string",
  "authConfigJson": "string",
  "hostingConfigJson": "string",
  "runtimeConfigJson": "string",
  "usagePolicyJson": "string",
  "gatewayId": "gw_4Jk9nQa"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/configUpdate stored OpenAPI spec configuration.Update stored OpenAPI spec configuration.

Request bodyUpdateServerConfigRequest · application/json

Field	Type	Required
`openApiSpecUrl`	`string \| null`	Optional
`openApiSpecJson`	`string \| null`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional

{
  "openApiSpecUrl": "https://api.example.com",
  "openApiSpecJson": "{ \"openapi\": \"3.1.0\", \"paths\": {} }",
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API"
}

Parametersquery

Name	In	Type	Required	Default
`X-API-Key`	header	`string`	Required	`-`

Response body200UpdateServerConfigResponse

Field	Type	Required
`id`	`string \| null`	Optional
`name`	`string \| null`	Optional
`toolCount`	`integer(int32)`	Optional
`message`	`string \| null`	Optional

{
  "id": "id_123",
  "name": "Support API",
  "toolCount": 1,
  "message": "string"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/guide-settingsGet public install-guide settings.Get public install-guide settings.

Request bodynone

No request body.

Response body200McpServerGuideSettingsResponse

Field	Type	Required
`serverId`	`string \| null`	Optional
`serverName`	`string \| null`	Optional
`publicSlug`	`string \| null`	Optional
`guideSlug`	`string \| null`	Optional
`directGuideUrl`	`string \| null`	Optional
`libraryGuideUrl`	`string \| null`	Optional
`organizationPublicGuidesEnabled`	`boolean`	Optional
`installGuideEnabled`	`boolean`	Optional
`isListedInLibrary`	`boolean`	Optional
`isIndexable`	`boolean`	Optional
`title`	`string \| null`	Optional
`providerDisplayName`	`string \| null`	Optional
`shortDescription`	`string \| null`	Optional
`longDescription`	`string \| null`	Optional
`logoUrl`	`string \| null`	Optional
`logoAltText`	`string \| null`	Optional
`category`	`string \| null`	Optional
`tags`	`string[] \| null`	Optional
`supportedClients`	`string[] \| null`	Optional

{
  "serverId": "mcp_5Qp8wYz",
  "serverName": "Support API",
  "publicSlug": "support-api",
  "guideSlug": "support-api",
  "directGuideUrl": "https://api.example.com",
  "libraryGuideUrl": "https://api.example.com",
  "organizationPublicGuidesEnabled": true,
  "installGuideEnabled": true,
  "isListedInLibrary": true,
  "isIndexable": true,
  "title": "string",
  "providerDisplayName": "Support API",
  "shortDescription": "Routes support ticket operations to MCP clients.",
  "longDescription": "Routes support ticket operations to MCP clients.",
  "logoUrl": "https://api.example.com",
  "logoAltText": "string",
  "category": "string",
  "tags": [
    "string"
  ],
  "supportedClients": [
    "string"
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PATCH/api/v1/organizations/{orgId}/mcp-servers/{serverId}/guide-settingsUpdate public install-guide settings.Update public install-guide settings.

Request bodyUpdateMcpServerGuideSettingsRequest · application/json

Field	Type	Required
`title`	`string \| null`	Optional
`providerDisplayName`	`string \| null`	Optional
`shortDescription`	`string \| null`	Optional
`longDescription`	`string \| null`	Optional
`logoUrl`	`string \| null`	Optional
`logoAltText`	`string \| null`	Optional
`category`	`string \| null`	Optional
`tags`	`string[] \| null`	Optional
`supportedClients`	`string[] \| null`	Optional
`isListedInLibrary`	`boolean \| null`	Optional

{
  "title": "string",
  "providerDisplayName": "Support API",
  "shortDescription": "Routes support ticket operations to MCP clients.",
  "longDescription": "Routes support ticket operations to MCP clients.",
  "logoUrl": "https://api.example.com",
  "logoAltText": "string",
  "category": "string",
  "tags": [
    "string"
  ],
  "supportedClients": [
    "string"
  ],
  "isListedInLibrary": true
}

Response body200McpServerGuideSettingsResponse

Field	Type	Required
`serverId`	`string \| null`	Optional
`serverName`	`string \| null`	Optional
`publicSlug`	`string \| null`	Optional
`guideSlug`	`string \| null`	Optional
`directGuideUrl`	`string \| null`	Optional
`libraryGuideUrl`	`string \| null`	Optional
`organizationPublicGuidesEnabled`	`boolean`	Optional
`installGuideEnabled`	`boolean`	Optional
`isListedInLibrary`	`boolean`	Optional
`isIndexable`	`boolean`	Optional
`title`	`string \| null`	Optional
`providerDisplayName`	`string \| null`	Optional
`shortDescription`	`string \| null`	Optional
`longDescription`	`string \| null`	Optional
`logoUrl`	`string \| null`	Optional
`logoAltText`	`string \| null`	Optional
`category`	`string \| null`	Optional
`tags`	`string[] \| null`	Optional
`supportedClients`	`string[] \| null`	Optional

{
  "serverId": "mcp_5Qp8wYz",
  "serverName": "Support API",
  "publicSlug": "support-api",
  "guideSlug": "support-api",
  "directGuideUrl": "https://api.example.com",
  "libraryGuideUrl": "https://api.example.com",
  "organizationPublicGuidesEnabled": true,
  "installGuideEnabled": true,
  "isListedInLibrary": true,
  "isIndexable": true,
  "title": "string",
  "providerDisplayName": "Support API",
  "shortDescription": "Routes support ticket operations to MCP clients.",
  "longDescription": "Routes support ticket operations to MCP clients.",
  "logoUrl": "https://api.example.com",
  "logoAltText": "string",
  "category": "string",
  "tags": [
    "string"
  ],
  "supportedClients": [
    "string"
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/logsPage through request logs.Page through request logs.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`cursor`	query	`string`	Optional	`-`
`pageSize`	query	`integer(int32)`	Optional	`50`
`status`	query	`string`	Optional	`-`
`search`	query	`string`	Optional	`-`

Response body200RequestLogsListResponse

Field	Type	Required
`logs`	`RequestLogResponse[] \| null`	Optional
`logs[].id`	`string \| null`	Optional
`logs[].toolName`	`string \| null`	Optional
`logs[].durationMs`	`integer(int32)`	Optional
`logs[].success`	`boolean`	Optional
`logs[].errorMessage`	`string \| null`	Optional
`logs[].calledAt`	`string(date-time)`	Optional
`logs[].serviceAccountName`	`string \| null`	Optional
`logs[].toolLabel`	`string \| null`	Optional
`logs[].externalUserId`	`string \| null`	Optional
`pageSize`	`integer(int32)`	Optional
`nextCursor`	`string \| null`	Optional
`hasNextPage`	`boolean`	Optional

{
  "logs": [
    {
      "id": "id_123",
      "toolName": "Support API",
      "durationMs": 1,
      "success": true,
      "errorMessage": "string",
      "calledAt": "2026-05-29T18:20:11Z",
      "serviceAccountName": "Support API",
      "toolLabel": "string",
      "externalUserId": "id_123"
    }
  ],
  "pageSize": 1,
  "nextCursor": "string",
  "hasNextPage": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/analyticsGet server usage analytics.Get server usage analytics.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`days`	query	`integer(int32)`	Optional	`7`

Response body200ServerAnalyticsResponse

Field	Type	Required
`dailyInvocations`	`DailyStats[] \| null`	Optional
`dailyInvocations[].date`	`string \| null`	Optional
`dailyInvocations[].count`	`integer(int32)`	Optional
`dailyInvocations[].successCount`	`integer(int32)`	Optional
`dailyInvocations[].failureCount`	`integer(int32)`	Optional
`dailyInvocations[].avgLatencyMs`	`number(double)`	Optional
`totalInvocations`	`integer(int32)`	Optional
`successCount`	`integer(int32)`	Optional
`failureCount`	`integer(int32)`	Optional
`avgLatencyMs`	`number(double)`	Optional
`topTools`	`ToolUsageStats[] \| null`	Optional
`topTools[].toolName`	`string \| null`	Optional
`topTools[].count`	`integer(int32)`	Optional
`topTools[].toolLabel`	`string \| null`	Optional

{
  "dailyInvocations": [
    {
      "date": "string",
      "count": 1,
      "successCount": 1,
      "failureCount": 1,
      "avgLatencyMs": 0.2
    }
  ],
  "totalInvocations": 1,
  "successCount": 1,
  "failureCount": 1,
  "avgLatencyMs": 0.2,
  "topTools": [
    {
      "toolName": "Support API",
      "count": 1,
      "toolLabel": "string"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

OpenAPI, auth, and tools#

MethodEndpointDescriptionCopy

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/openapiReplace the stored OpenAPI spec.Replace the stored OpenAPI spec.

Request bodyUpdateServerConfigRequest · application/json

Field	Type	Required
`openApiSpecUrl`	`string \| null`	Optional
`openApiSpecJson`	`string \| null`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional

{
  "openApiSpecUrl": "https://api.example.com",
  "openApiSpecJson": "{ \"openapi\": \"3.1.0\", \"paths\": {} }",
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API"
}

Response body200UpdateServerConfigResponse

Field	Type	Required
`id`	`string \| null`	Optional
`name`	`string \| null`	Optional
`toolCount`	`integer(int32)`	Optional
`message`	`string \| null`	Optional

{
  "id": "id_123",
  "name": "Support API",
  "toolCount": 1,
  "message": "string"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/openapi/refreshRe-fetch or re-import an OpenAPI spec and return a merge report.Re-fetch or re-import an OpenAPI spec and return a merge report.

Request bodyUpdateServerConfigRequest · application/json

Field	Type	Required
`openApiSpecUrl`	`string \| null`	Optional
`openApiSpecJson`	`string \| null`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional

{
  "openApiSpecUrl": "https://api.example.com",
  "openApiSpecJson": "{ \"openapi\": \"3.1.0\", \"paths\": {} }",
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API"
}

Response body200MergeReportResponse

Field	Type	Required
`added`	`string[] \| null`	Optional
`updatedSource`	`string[] \| null`	Optional
`unchanged`	`string[] \| null`	Optional
`removedFromSource`	`string[] \| null`	Optional
`reappeared`	`string[] \| null`	Optional
`totalTools`	`integer(int32)`	Optional

{
  "added": [
    "string"
  ],
  "updatedSource": [
    "string"
  ],
  "unchanged": [
    "string"
  ],
  "removedFromSource": [
    "string"
  ],
  "reappeared": [
    "string"
  ],
  "totalTools": 1
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/discover-toolsRe-import tools from the current stored spec.Re-import tools from the current stored spec.

Request bodynone

No request body.

Response body200MergeReportResponse

Field	Type	Required
`added`	`string[] \| null`	Optional
`updatedSource`	`string[] \| null`	Optional
`unchanged`	`string[] \| null`	Optional
`removedFromSource`	`string[] \| null`	Optional
`reappeared`	`string[] \| null`	Optional
`totalTools`	`integer(int32)`	Optional

{
  "added": [
    "string"
  ],
  "updatedSource": [
    "string"
  ],
  "unchanged": [
    "string"
  ],
  "removedFromSource": [
    "string"
  ],
  "reappeared": [
    "string"
  ],
  "totalTools": 1
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/endpointsGet the generated endpoint set and enabled tool keys.Get the generated endpoint set and enabled tool keys.

Request bodynone

No request body.

Response body200EndpointsResponse

Field	Type	Required
`endpoints`	`EndpointInfo[] \| null`	Optional
`endpoints[].displayName`	`string \| null`	Optional
`endpoints[].method`	`string \| null`	Optional
`endpoints[].path`	`string \| null`	Optional
`endpoints[].summary`	`string \| null`	Optional
`endpoints[].description`	`string \| null`	Optional
`endpoints[].isEnabled`	`boolean`	Optional
`endpoints[].toolKey`	`string \| null`	Optional
`enabledCount`	`integer(int32)`	Optional
`totalCount`	`integer(int32)`	Optional

{
  "endpoints": [
    {
      "displayName": "Support API",
      "method": "POST",
      "path": "/tickets/{id}/notes",
      "summary": "string",
      "description": "Routes support ticket operations to MCP clients.",
      "isEnabled": true,
      "toolKey": "string"
    }
  ],
  "enabledCount": 1,
  "totalCount": 1
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PUT/api/v1/organizations/{orgId}/mcp-servers/{serverId}/endpointsUpdate which generated endpoints are exposed.Update which generated endpoints are exposed.

Request bodyUpdateEndpointsRequest · application/json

Field	Type	Required
`enabledToolKeys`	`string[]`	Required

{
  "enabledToolKeys": [
    "string"
  ]
}

Response body200EndpointsResponse

Field	Type	Required
`endpoints`	`EndpointInfo[] \| null`	Optional
`endpoints[].displayName`	`string \| null`	Optional
`endpoints[].method`	`string \| null`	Optional
`endpoints[].path`	`string \| null`	Optional
`endpoints[].summary`	`string \| null`	Optional
`endpoints[].description`	`string \| null`	Optional
`endpoints[].isEnabled`	`boolean`	Optional
`endpoints[].toolKey`	`string \| null`	Optional
`enabledCount`	`integer(int32)`	Optional
`totalCount`	`integer(int32)`	Optional

{
  "endpoints": [
    {
      "displayName": "Support API",
      "method": "POST",
      "path": "/tickets/{id}/notes",
      "summary": "string",
      "description": "Routes support ticket operations to MCP clients.",
      "isEnabled": true,
      "toolKey": "string"
    }
  ],
  "enabledCount": 1,
  "totalCount": 1
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PATCH/api/v1/organizations/{orgId}/mcp-servers/{serverId}/tools/{toolId}Edit one generated or manual tool.Edit one generated or manual tool.

Request bodyUpdateToolRequest · application/json

Field	Type	Required
`isEnabled`	`boolean \| null`	Optional
`displayName`	`string \| null`	Optional
`descriptionOverride`	`string \| null`	Optional
`instructions`	`string \| null`	Optional
`whenToUse`	`string \| null`	Optional
`whenNotToUse`	`string \| null`	Optional
`examplesJson`	`string \| null`	Optional

{
  "isEnabled": true,
  "displayName": "Support API",
  "descriptionOverride": "Routes support ticket operations to MCP clients.",
  "instructions": "string",
  "whenToUse": "string",
  "whenNotToUse": "string",
  "examplesJson": "string"
}

Response body200ToolResponse

Field	Type	Required
`id`	`string \| null`	Optional
`name`	`string \| null`	Optional
`toolKey`	`string \| null`	Optional
`displayName`	`string \| null`	Optional
`description`	`string \| null`	Optional
`httpMethod`	`string \| null`	Optional
`httpPath`	`string \| null`	Optional
`isEnabled`	`boolean`	Optional
`toolNamingVersion`	`integer(int32)`	Optional
`source`	`string \| null`	Optional
`isManaged`	`boolean`	Optional
`sourceDescription`	`string \| null`	Optional
`descriptionOverride`	`string \| null`	Optional
`instructions`	`string \| null`	Optional
`whenToUse`	`string \| null`	Optional
`whenNotToUse`	`string \| null`	Optional
`examplesJson`	`string \| null`	Optional
`openApiOperationId`	`string \| null`	Optional
`lastSeenInSourceAt`	`string(date-time) \| null`	Optional
`removedFromSourceAt`	`string(date-time) \| null`	Optional
`rulesLastModifiedOn`	`string(date-time) \| null`	Optional

{
  "id": "id_123",
  "name": "Support API",
  "toolKey": "string",
  "displayName": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "httpMethod": "POST",
  "httpPath": "/tickets/{id}/notes",
  "isEnabled": true,
  "toolNamingVersion": 1,
  "source": "string",
  "isManaged": true,
  "sourceDescription": "Routes support ticket operations to MCP clients.",
  "descriptionOverride": "Routes support ticket operations to MCP clients.",
  "instructions": "string",
  "whenToUse": "string",
  "whenNotToUse": "string",
  "examplesJson": "string",
  "openApiOperationId": "id_123",
  "lastSeenInSourceAt": "2026-05-29T18:20:11Z",
  "removedFromSourceAt": "2026-05-29T18:20:11Z",
  "rulesLastModifiedOn": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PUT/api/v1/organizations/{orgId}/mcp-servers/{serverId}/toolsBulk-update tool settings.Bulk-update tool settings.

Request bodyBulkUpdateToolsRequest · application/json

Field	Type	Required
`patches`	`BulkToolPatch[]`	Required
`patches[].toolId`	`string`	Required
`patches[].isEnabled`	`boolean \| null`	Optional
`patches[].displayName`	`string \| null`	Optional
`patches[].descriptionOverride`	`string \| null`	Optional
`patches[].instructions`	`string \| null`	Optional
`patches[].whenToUse`	`string \| null`	Optional
`patches[].whenNotToUse`	`string \| null`	Optional
`patches[].examplesJson`	`string \| null`	Optional

{
  "patches": [
    {
      "toolId": "id_123",
      "isEnabled": true,
      "displayName": "Support API",
      "descriptionOverride": "Routes support ticket operations to MCP clients.",
      "instructions": "string",
      "whenToUse": "string",
      "whenNotToUse": "string",
      "examplesJson": "string"
    }
  ]
}

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].name`	`string \| null`	Optional
`[].toolKey`	`string \| null`	Optional
`[].displayName`	`string \| null`	Optional
`[].description`	`string \| null`	Optional
`[].httpMethod`	`string \| null`	Optional
`[].httpPath`	`string \| null`	Optional
`[].isEnabled`	`boolean`	Optional
`[].toolNamingVersion`	`integer(int32)`	Optional
`[].source`	`string \| null`	Optional
`[].isManaged`	`boolean`	Optional
`[].sourceDescription`	`string \| null`	Optional
`[].descriptionOverride`	`string \| null`	Optional
`[].instructions`	`string \| null`	Optional
`[].whenToUse`	`string \| null`	Optional
`[].whenNotToUse`	`string \| null`	Optional
`[].examplesJson`	`string \| null`	Optional
`[].openApiOperationId`	`string \| null`	Optional
`[].lastSeenInSourceAt`	`string(date-time) \| null`	Optional
`[].removedFromSourceAt`	`string(date-time) \| null`	Optional
`[].rulesLastModifiedOn`	`string(date-time) \| null`	Optional

[
  {
    "id": "id_123",
    "name": "Support API",
    "toolKey": "string",
    "displayName": "Support API",
    "description": "Routes support ticket operations to MCP clients.",
    "httpMethod": "POST",
    "httpPath": "/tickets/{id}/notes",
    "isEnabled": true,
    "toolNamingVersion": 1,
    "source": "string",
    "isManaged": true,
    "sourceDescription": "Routes support ticket operations to MCP clients.",
    "descriptionOverride": "Routes support ticket operations to MCP clients.",
    "instructions": "string",
    "whenToUse": "string",
    "whenNotToUse": "string",
    "examplesJson": "string",
    "openApiOperationId": "id_123",
    "lastSeenInSourceAt": "2026-05-29T18:20:11Z",
    "removedFromSourceAt": "2026-05-29T18:20:11Z",
    "rulesLastModifiedOn": "2026-05-29T18:20:11Z"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/auth-configGet runtime auth configuration.Get runtime auth configuration.

Request bodynone

No request body.

Response body200AuthConfigResponse

Field	Type	Required
`authType`	`string \| null`	Optional
`apiKeyHeaderName`	`string \| null`	Optional
`oAuth2AuthorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`loginUrl`	`string \| null`	Optional
`authorizationEndpoint`	`string \| null`	Optional
`tokenUrl`	`string \| null`	Optional
`tokenEndpoint`	`string \| null`	Optional
`registrationEndpoint`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`scopes`	`string \| null`	Optional
`resource`	`string \| null`	Optional
`callbackUrl`	`string \| null`	Optional
`registrationPreference`	`string \| null`	Optional
`authRecipe`	`string \| null`	Optional
`clientIdMetadataDocumentSupported`	`boolean \| null`	Optional
`resourceParameterSupported`	`boolean \| null`	Optional

{
  "authType": "string",
  "apiKeyHeaderName": "Support API",
  "oAuth2AuthorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "loginUrl": "https://api.example.com",
  "authorizationEndpoint": "string",
  "tokenUrl": "https://api.example.com",
  "tokenEndpoint": "redacted",
  "registrationEndpoint": "string",
  "clientId": "id_123",
  "scopes": "openid",
  "resource": "string",
  "callbackUrl": "https://api.example.com",
  "registrationPreference": "string",
  "authRecipe": "string",
  "clientIdMetadataDocumentSupported": true,
  "resourceParameterSupported": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PUT/api/v1/organizations/{orgId}/mcp-servers/{serverId}/auth-configUpdate runtime auth configuration.Update runtime auth configuration.

Request bodyUpdateAuthConfigRequest · application/json

Field	Type	Required
`authType`	`string \| null`	Optional
`apiKeyHeaderName`	`string \| null`	Optional
`oAuth2AuthorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`loginUrl`	`string \| null`	Optional
`authorizationEndpoint`	`string \| null`	Optional
`tokenUrl`	`string \| null`	Optional
`tokenEndpoint`	`string \| null`	Optional
`registrationEndpoint`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`scopes`	`string \| null`	Optional
`resource`	`string \| null`	Optional
`callbackUrl`	`string \| null`	Optional
`registrationPreference`	`string \| null`	Optional
`authRecipe`	`string \| null`	Optional
`clientIdMetadataDocumentSupported`	`boolean \| null`	Optional
`resourceParameterSupported`	`boolean \| null`	Optional

{
  "authType": "string",
  "apiKeyHeaderName": "Support API",
  "oAuth2AuthorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "loginUrl": "https://api.example.com",
  "authorizationEndpoint": "string",
  "tokenUrl": "https://api.example.com",
  "tokenEndpoint": "redacted",
  "registrationEndpoint": "string",
  "clientId": "id_123",
  "scopes": "openid",
  "resource": "string",
  "callbackUrl": "https://api.example.com",
  "registrationPreference": "string",
  "authRecipe": "string",
  "clientIdMetadataDocumentSupported": true,
  "resourceParameterSupported": true
}

Response body200AuthConfigResponse

Field	Type	Required
`authType`	`string \| null`	Optional
`apiKeyHeaderName`	`string \| null`	Optional
`oAuth2AuthorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`loginUrl`	`string \| null`	Optional
`authorizationEndpoint`	`string \| null`	Optional
`tokenUrl`	`string \| null`	Optional
`tokenEndpoint`	`string \| null`	Optional
`registrationEndpoint`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`scopes`	`string \| null`	Optional
`resource`	`string \| null`	Optional
`callbackUrl`	`string \| null`	Optional
`registrationPreference`	`string \| null`	Optional
`authRecipe`	`string \| null`	Optional
`clientIdMetadataDocumentSupported`	`boolean \| null`	Optional
`resourceParameterSupported`	`boolean \| null`	Optional

{
  "authType": "string",
  "apiKeyHeaderName": "Support API",
  "oAuth2AuthorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "loginUrl": "https://api.example.com",
  "authorizationEndpoint": "string",
  "tokenUrl": "https://api.example.com",
  "tokenEndpoint": "redacted",
  "registrationEndpoint": "string",
  "clientId": "id_123",
  "scopes": "openid",
  "resource": "string",
  "callbackUrl": "https://api.example.com",
  "registrationPreference": "string",
  "authRecipe": "string",
  "clientIdMetadataDocumentSupported": true,
  "resourceParameterSupported": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/auth-discoveryProbe the upstream API's auth requirements.Probe the upstream API's auth requirements.

Request bodynone

No request body.

Response body200AuthDiscoveryResponse

Field	Type	Required
`serverUrl`	`string \| null`	Optional
`protectedResourceMetadataFound`	`boolean`	Optional
`protectedResourceMetadataUrl`	`string \| null`	Optional
`authorizationServerMetadataFound`	`boolean`	Optional
`authorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`resource`	`string \| null`	Optional
`discoveredScopes`	`string[] \| null`	Optional
`registrationEndpoint`	`string \| null`	Optional
`clientIdMetadataDocumentSupported`	`boolean \| null`	Optional
`resourceParameterSupported`	`boolean \| null`	Optional
`supportedModes`	`string[] \| null`	Optional
`expectedCallbackUrl`	`string \| null`	Optional
`effectiveClientMode`	`string \| null`	Optional
`manualOverrides`	`string[] \| null`	Optional

{
  "serverUrl": "https://api.example.com",
  "protectedResourceMetadataFound": true,
  "protectedResourceMetadataUrl": "https://api.example.com",
  "authorizationServerMetadataFound": true,
  "authorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "resource": "string",
  "discoveredScopes": [
    "openid"
  ],
  "registrationEndpoint": "string",
  "clientIdMetadataDocumentSupported": true,
  "resourceParameterSupported": true,
  "supportedModes": [
    "string"
  ],
  "expectedCallbackUrl": "https://api.example.com",
  "effectiveClientMode": "string",
  "manualOverrides": [
    "string"
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PUT/api/v1/organizations/{orgId}/mcp-servers/{serverId}/hosting-configUpdate Host runtime settings.Update Host runtime settings.

Request bodyUpdateHostingConfigRequest · application/json

Field	Type	Required
`serverUrl`	`string \| null`	Optional
`hostingConfigJson`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`runtimeConfigJson`	`string \| null`	Optional
`usagePolicyJson`	`string \| null`	Optional

{
  "serverUrl": "https://api.example.com",
  "hostingConfigJson": "string",
  "runtimeType": "string",
  "runtimeConfigJson": "string",
  "usagePolicyJson": "string"
}

Response body200McpServerConfigResponse

Field	Type	Required
`id`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`gatewayPublicId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`kind`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`openApiSpecUrl`	`string \| null`	Optional
`hasOpenApiSpec`	`boolean`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional
`openApiSpecUpdatedAt`	`string(date-time) \| null`	Optional
`apiBaseUrl`	`string \| null`	Optional
`serverUrl`	`string \| null`	Optional
`enabledEndpointsJson`	`string \| null`	Optional
`generationConfigJson`	`string \| null`	Optional
`authConfigJson`	`string \| null`	Optional
`hostingConfigJson`	`string \| null`	Optional
`runtimeConfigJson`	`string \| null`	Optional
`usagePolicyJson`	`string \| null`	Optional
`gatewayId`	`string \| null`	Optional

{
  "id": "id_123",
  "slug": "support-api",
  "gatewayPublicId": "gw_4Jk9nQa",
  "name": "Support API",
  "kind": "string",
  "runtimeType": "string",
  "openApiSpecUrl": "https://api.example.com",
  "hasOpenApiSpec": true,
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API",
  "openApiSpecUpdatedAt": "2026-05-29T18:20:11Z",
  "apiBaseUrl": "https://api.example.com",
  "serverUrl": "https://api.example.com",
  "enabledEndpointsJson": "string",
  "generationConfigJson": "string",
  "authConfigJson": "string",
  "hostingConfigJson": "string",
  "runtimeConfigJson": "string",
  "usagePolicyJson": "string",
  "gatewayId": "gw_4Jk9nQa"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PUT/api/v1/organizations/{orgId}/mcp-servers/{serverId}/generation-configUpdate OpenAPI generation settings.Update OpenAPI generation settings.

Request bodyUpdateGenerationConfigRequest · application/json

Field	Type	Required
`apiBaseUrl`	`string \| null`	Optional
`serverUrl`	`string \| null`	Optional
`enabledEndpointsJson`	`string \| null`	Optional
`generationConfigJson`	`string \| null`	Optional
`authConfigJson`	`string \| null`	Optional
`hostingConfigJson`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`runtimeConfigJson`	`string \| null`	Optional
`usagePolicyJson`	`string \| null`	Optional

{
  "apiBaseUrl": "https://api.example.com",
  "serverUrl": "https://api.example.com",
  "enabledEndpointsJson": "string",
  "generationConfigJson": "string",
  "authConfigJson": "string",
  "hostingConfigJson": "string",
  "runtimeType": "string",
  "runtimeConfigJson": "string",
  "usagePolicyJson": "string"
}

Response body200McpServerConfigResponse

Field	Type	Required
`id`	`string \| null`	Optional
`slug`	`string \| null`	Optional
`gatewayPublicId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`kind`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`openApiSpecUrl`	`string \| null`	Optional
`hasOpenApiSpec`	`boolean`	Optional
`openApiSpecSource`	`string \| null`	Optional
`openApiSpecFileName`	`string \| null`	Optional
`openApiSpecUpdatedAt`	`string(date-time) \| null`	Optional
`apiBaseUrl`	`string \| null`	Optional
`serverUrl`	`string \| null`	Optional
`enabledEndpointsJson`	`string \| null`	Optional
`generationConfigJson`	`string \| null`	Optional
`authConfigJson`	`string \| null`	Optional
`hostingConfigJson`	`string \| null`	Optional
`runtimeConfigJson`	`string \| null`	Optional
`usagePolicyJson`	`string \| null`	Optional
`gatewayId`	`string \| null`	Optional

{
  "id": "id_123",
  "slug": "support-api",
  "gatewayPublicId": "gw_4Jk9nQa",
  "name": "Support API",
  "kind": "string",
  "runtimeType": "string",
  "openApiSpecUrl": "https://api.example.com",
  "hasOpenApiSpec": true,
  "openApiSpecSource": "upload",
  "openApiSpecFileName": "Support API",
  "openApiSpecUpdatedAt": "2026-05-29T18:20:11Z",
  "apiBaseUrl": "https://api.example.com",
  "serverUrl": "https://api.example.com",
  "enabledEndpointsJson": "string",
  "generationConfigJson": "string",
  "authConfigJson": "string",
  "hostingConfigJson": "string",
  "runtimeConfigJson": "string",
  "usagePolicyJson": "string",
  "gatewayId": "gw_4Jk9nQa"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Deploy and operate#

MethodEndpointDescriptionCopy

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-configGet deployment configuration.Get deployment configuration.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200McpDeploymentConfigResponse

Field	Type	Required
`id`	`string \| null`	Optional
`mcpServerId`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`publicSlug`	`string \| null`	Optional
`publicHostName`	`string \| null`	Optional
`publicBaseUrl`	`string \| null`	Optional
`routingMode`	`string \| null`	Optional
`activeDeploymentId`	`string \| null`	Optional
`afdCustomDomainName`	`string \| null`	Optional
`afdRouteName`	`string \| null`	Optional
`afdOriginGroupName`	`string \| null`	Optional
`preferredPublicBaseUrl`	`string \| null`	Optional
`preferredMcpUrl`	`string \| null`	Optional
`customDomain`	`McpServerCustomDomainResponse`	Optional
`customDomain.id`	`string \| null`	Optional
`customDomain.organizationId`	`string \| null`	Optional
`customDomain.mcpServerId`	`string \| null`	Optional
`customDomain.deploymentConfigId`	`string \| null`	Optional
`customDomain.environment`	`string \| null`	Optional
`customDomain.hostName`	`string \| null`	Optional
`customDomain.status`	`string \| null`	Optional
`customDomain.mcpUrl`	`string \| null`	Optional
`customDomain.canonicalMcpUrl`	`string \| null`	Optional
`customDomain.verificationToken`	`string \| null`	Optional
`customDomain.dnsTargetHostName`	`string \| null`	Optional
`customDomain.afdCustomDomainName`	`string \| null`	Optional
`customDomain.afdCustomDomainId`	`string \| null`	Optional
`customDomain.lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`customDomain.lastError`	`string \| null`	Optional
`customDomain.dnsRecords`	`McpServerCustomDomainDnsRecordResponse[] \| null`	Optional
`customDomain.dnsRecords[].type`	`string \| null`	Optional
`customDomain.dnsRecords[].name`	`string \| null`	Optional
`customDomain.dnsRecords[].value`	`string \| null`	Optional
`regions`	`McpDeploymentRegionConfigResponse[] \| null`	Optional
`regions[].id`	`string \| null`	Optional
`regions[].region`	`string \| null`	Optional
`regions[].cpu`	`string \| null`	Optional
`regions[].memory`	`string \| null`	Optional
`regions[].minReplicas`	`integer(int32)`	Optional
`regions[].maxReplicas`	`integer(int32)`	Optional
`regions[].isEnabled`	`boolean`	Optional

{
  "id": "id_123",
  "mcpServerId": "mcp_5Qp8wYz",
  "organizationId": "org_7Hf3kQ2",
  "environment": "prod",
  "publicSlug": "support-api",
  "publicHostName": "app.example.com",
  "publicBaseUrl": "https://api.example.com",
  "routingMode": "string",
  "activeDeploymentId": "id_123",
  "afdCustomDomainName": "Support API",
  "afdRouteName": "Support API",
  "afdOriginGroupName": "https://api.example.com",
  "preferredPublicBaseUrl": "https://api.example.com",
  "preferredMcpUrl": "https://api.example.com",
  "customDomain": {
    "id": "id_123",
    "organizationId": "org_7Hf3kQ2",
    "mcpServerId": "mcp_5Qp8wYz",
    "deploymentConfigId": "id_123",
    "environment": "prod",
    "hostName": "app.example.com",
    "status": "active",
    "mcpUrl": "https://api.example.com",
    "canonicalMcpUrl": "https://api.example.com",
    "verificationToken": "redacted",
    "dnsTargetHostName": "app.example.com",
    "afdCustomDomainName": "Support API",
    "afdCustomDomainId": "id_123",
    "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
    "lastError": "string",
    "dnsRecords": [
      {
        "type": "string",
        "name": "Support API",
        "value": "string"
      }
    ]
  },
  "regions": [
    {
      "id": "id_123",
      "region": "westus3",
      "cpu": "string",
      "memory": "string",
      "minReplicas": 1,
      "maxReplicas": 1,
      "isEnabled": true
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PUT/api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-configUpdate deployment configuration.Update deployment configuration.

Request bodyUpsertMcpDeploymentConfigRequest · application/json

Field	Type	Required
`environment`	`string`	Required
`publicSlug`	`string \| null`	Optional
`regions`	`DeploymentRegionRequest[] \| null`	Optional
`regions[].region`	`string`	Required
`regions[].cpu`	`string \| null`	Optional
`regions[].memory`	`string \| null`	Optional
`regions[].minReplicas`	`integer(int32) \| null`	Optional
`regions[].maxReplicas`	`integer(int32) \| null`	Optional
`regions[].enabled`	`boolean \| null`	Optional

{
  "environment": "prod",
  "publicSlug": "support-api",
  "regions": [
    {
      "region": "westus3",
      "cpu": "string",
      "memory": "string",
      "minReplicas": 1,
      "maxReplicas": 1,
      "enabled": true
    }
  ]
}

Response body200McpDeploymentConfigResponse

Field	Type	Required
`id`	`string \| null`	Optional
`mcpServerId`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`publicSlug`	`string \| null`	Optional
`publicHostName`	`string \| null`	Optional
`publicBaseUrl`	`string \| null`	Optional
`routingMode`	`string \| null`	Optional
`activeDeploymentId`	`string \| null`	Optional
`afdCustomDomainName`	`string \| null`	Optional
`afdRouteName`	`string \| null`	Optional
`afdOriginGroupName`	`string \| null`	Optional
`preferredPublicBaseUrl`	`string \| null`	Optional
`preferredMcpUrl`	`string \| null`	Optional
`customDomain`	`McpServerCustomDomainResponse`	Optional
`customDomain.id`	`string \| null`	Optional
`customDomain.organizationId`	`string \| null`	Optional
`customDomain.mcpServerId`	`string \| null`	Optional
`customDomain.deploymentConfigId`	`string \| null`	Optional
`customDomain.environment`	`string \| null`	Optional
`customDomain.hostName`	`string \| null`	Optional
`customDomain.status`	`string \| null`	Optional
`customDomain.mcpUrl`	`string \| null`	Optional
`customDomain.canonicalMcpUrl`	`string \| null`	Optional
`customDomain.verificationToken`	`string \| null`	Optional
`customDomain.dnsTargetHostName`	`string \| null`	Optional
`customDomain.afdCustomDomainName`	`string \| null`	Optional
`customDomain.afdCustomDomainId`	`string \| null`	Optional
`customDomain.lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`customDomain.lastError`	`string \| null`	Optional
`customDomain.dnsRecords`	`McpServerCustomDomainDnsRecordResponse[] \| null`	Optional
`customDomain.dnsRecords[].type`	`string \| null`	Optional
`customDomain.dnsRecords[].name`	`string \| null`	Optional
`customDomain.dnsRecords[].value`	`string \| null`	Optional
`regions`	`McpDeploymentRegionConfigResponse[] \| null`	Optional
`regions[].id`	`string \| null`	Optional
`regions[].region`	`string \| null`	Optional
`regions[].cpu`	`string \| null`	Optional
`regions[].memory`	`string \| null`	Optional
`regions[].minReplicas`	`integer(int32)`	Optional
`regions[].maxReplicas`	`integer(int32)`	Optional
`regions[].isEnabled`	`boolean`	Optional

{
  "id": "id_123",
  "mcpServerId": "mcp_5Qp8wYz",
  "organizationId": "org_7Hf3kQ2",
  "environment": "prod",
  "publicSlug": "support-api",
  "publicHostName": "app.example.com",
  "publicBaseUrl": "https://api.example.com",
  "routingMode": "string",
  "activeDeploymentId": "id_123",
  "afdCustomDomainName": "Support API",
  "afdRouteName": "Support API",
  "afdOriginGroupName": "https://api.example.com",
  "preferredPublicBaseUrl": "https://api.example.com",
  "preferredMcpUrl": "https://api.example.com",
  "customDomain": {
    "id": "id_123",
    "organizationId": "org_7Hf3kQ2",
    "mcpServerId": "mcp_5Qp8wYz",
    "deploymentConfigId": "id_123",
    "environment": "prod",
    "hostName": "app.example.com",
    "status": "active",
    "mcpUrl": "https://api.example.com",
    "canonicalMcpUrl": "https://api.example.com",
    "verificationToken": "redacted",
    "dnsTargetHostName": "app.example.com",
    "afdCustomDomainName": "Support API",
    "afdCustomDomainId": "id_123",
    "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
    "lastError": "string",
    "dnsRecords": [
      {
        "type": "string",
        "name": "Support API",
        "value": "string"
      }
    ]
  },
  "regions": [
    {
      "id": "id_123",
      "region": "westus3",
      "cpu": "string",
      "memory": "string",
      "minReplicas": 1,
      "maxReplicas": 1,
      "isEnabled": true
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/deploymentGet the active deployment.Get the active deployment.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200McpServerDeploymentResponse

Field	Type	Required
`id`	`string \| null`	Optional
`mcpServerId`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`region`	`string \| null`	Optional
`serverSlug`	`string \| null`	Optional
`publicBaseUrl`	`string \| null`	Optional
`containerAppName`	`string \| null`	Optional
`internalBaseUrl`	`string \| null`	Optional
`imageReference`	`string \| null`	Optional
`currentRevisionName`	`string \| null`	Optional
`previousRevisionName`	`string \| null`	Optional
`deploymentStatus`	`string \| null`	Optional
`cpu`	`string \| null`	Optional
`memory`	`string \| null`	Optional
`minReplicas`	`integer(int32)`	Optional
`maxReplicas`	`integer(int32)`	Optional
`lastDeployStartedAt`	`string(date-time) \| null`	Optional
`lastDeployCompletedAt`	`string(date-time) \| null`	Optional
`operationId`	`string \| null`	Optional
`lastHealthStatusCode`	`integer(int32) \| null`	Optional
`lastHealthCheckedAt`	`string(date-time) \| null`	Optional
`lastError`	`string \| null`	Optional
`deploymentConfigId`	`string \| null`	Optional
`deploymentKind`	`string \| null`	Optional
`afdCustomDomainName`	`string \| null`	Optional
`afdRouteName`	`string \| null`	Optional
`afdOriginGroupName`	`string \| null`	Optional
`preferredPublicBaseUrl`	`string \| null`	Optional
`preferredMcpUrl`	`string \| null`	Optional
`customDomain`	`McpServerCustomDomainResponse`	Optional
`customDomain.id`	`string \| null`	Optional
`customDomain.organizationId`	`string \| null`	Optional
`customDomain.mcpServerId`	`string \| null`	Optional
`customDomain.deploymentConfigId`	`string \| null`	Optional
`customDomain.environment`	`string \| null`	Optional
`customDomain.hostName`	`string \| null`	Optional
`customDomain.status`	`string \| null`	Optional
`customDomain.mcpUrl`	`string \| null`	Optional
`customDomain.canonicalMcpUrl`	`string \| null`	Optional
`customDomain.verificationToken`	`string \| null`	Optional
`customDomain.dnsTargetHostName`	`string \| null`	Optional
`customDomain.afdCustomDomainName`	`string \| null`	Optional
`customDomain.afdCustomDomainId`	`string \| null`	Optional
`customDomain.lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`customDomain.lastError`	`string \| null`	Optional
`customDomain.dnsRecords`	`McpServerCustomDomainDnsRecordResponse[] \| null`	Optional
`customDomain.dnsRecords[].type`	`string \| null`	Optional
`customDomain.dnsRecords[].name`	`string \| null`	Optional
`customDomain.dnsRecords[].value`	`string \| null`	Optional
`targets`	`McpServerDeploymentTargetResponse[] \| null`	Optional
`targets[].id`	`string \| null`	Optional
`targets[].deploymentId`	`string \| null`	Optional
`targets[].region`	`string \| null`	Optional
`targets[].containerAppName`	`string \| null`	Optional
`targets[].containerAppFqdn`	`string \| null`	Optional
`targets[].publicOriginFqdn`	`string \| null`	Optional
`targets[].imageReference`	`string \| null`	Optional
`targets[].currentRevisionName`	`string \| null`	Optional
`targets[].previousRevisionName`	`string \| null`	Optional
`targets[].cpu`	`string \| null`	Optional
`targets[].memory`	`string \| null`	Optional
`targets[].minReplicas`	`integer(int32)`	Optional
`targets[].maxReplicas`	`integer(int32)`	Optional
`targets[].targetStatus`	`string \| null`	Optional
`targets[].afdOriginName`	`string \| null`	Optional
`targets[].routingEnabled`	`boolean`	Optional
`targets[].lastHealthStatusCode`	`integer(int32) \| null`	Optional
`targets[].lastHealthCheckedAt`	`string(date-time) \| null`	Optional
`targets[].lastError`	`string \| null`	Optional

{
  "id": "id_123",
  "mcpServerId": "mcp_5Qp8wYz",
  "organizationId": "org_7Hf3kQ2",
  "environment": "prod",
  "region": "westus3",
  "serverSlug": "support-api",
  "publicBaseUrl": "https://api.example.com",
  "containerAppName": "Support API",
  "internalBaseUrl": "https://api.example.com",
  "imageReference": "string",
  "currentRevisionName": "Support API",
  "previousRevisionName": "Support API",
  "deploymentStatus": "active",
  "cpu": "string",
  "memory": "string",
  "minReplicas": 1,
  "maxReplicas": 1,
  "lastDeployStartedAt": "2026-05-29T18:20:11Z",
  "lastDeployCompletedAt": "2026-05-29T18:20:11Z",
  "operationId": "id_123",
  "lastHealthStatusCode": 1,
  "lastHealthCheckedAt": "2026-05-29T18:20:11Z",
  "lastError": "string",
  "deploymentConfigId": "id_123",
  "deploymentKind": "string",
  "afdCustomDomainName": "Support API",
  "afdRouteName": "Support API",
  "afdOriginGroupName": "https://api.example.com",
  "preferredPublicBaseUrl": "https://api.example.com",
  "preferredMcpUrl": "https://api.example.com",
  "customDomain": {
    "id": "id_123",
    "organizationId": "org_7Hf3kQ2",
    "mcpServerId": "mcp_5Qp8wYz",
    "deploymentConfigId": "id_123",
    "environment": "prod",
    "hostName": "app.example.com",
    "status": "active",
    "mcpUrl": "https://api.example.com",
    "canonicalMcpUrl": "https://api.example.com",
    "verificationToken": "redacted",
    "dnsTargetHostName": "app.example.com",
    "afdCustomDomainName": "Support API",
    "afdCustomDomainId": "id_123",
    "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
    "lastError": "string",
    "dnsRecords": [
      {
        "type": "string",
        "name": "Support API",
        "value": "string"
      }
    ]
  },
  "targets": [
    {
      "id": "id_123",
      "deploymentId": "id_123",
      "region": "westus3",
      "containerAppName": "Support API",
      "containerAppFqdn": "string",
      "publicOriginFqdn": "https://api.example.com",
      "imageReference": "string",
      "currentRevisionName": "Support API",
      "previousRevisionName": "Support API",
      "cpu": "string",
      "memory": "string",
      "minReplicas": 1,
      "maxReplicas": 1,
      "targetStatus": "active",
      "afdOriginName": "https://api.example.com",
      "routingEnabled": true,
      "lastHealthStatusCode": 1,
      "lastHealthCheckedAt": "2026-05-29T18:20:11Z",
      "lastError": "string"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment/logsGet logs for the active deployment.Get logs for the active deployment.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional
`tail`	query	`integer(int32)`	Optional	`100`

Response body200McpServerDeploymentLogsResponse

Field	Type	Required
`mcpServerId`	`string \| null`	Optional
`deploymentId`	`string \| null`	Optional
`lines`	`string[] \| null`	Optional

{
  "mcpServerId": "mcp_5Qp8wYz",
  "deploymentId": "id_123",
  "lines": [
    "string"
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/deploymentsList deployment history.List deployment history.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200McpServerDeploymentRunListResponse

Field	Type	Required
`deployments`	`McpServerDeploymentResponse[] \| null`	Optional
`deployments[].id`	`string \| null`	Optional
`deployments[].mcpServerId`	`string \| null`	Optional
`deployments[].organizationId`	`string \| null`	Optional
`deployments[].environment`	`string \| null`	Optional
`deployments[].region`	`string \| null`	Optional
`deployments[].serverSlug`	`string \| null`	Optional
`deployments[].publicBaseUrl`	`string \| null`	Optional
`deployments[].containerAppName`	`string \| null`	Optional
`deployments[].internalBaseUrl`	`string \| null`	Optional
`deployments[].imageReference`	`string \| null`	Optional
`deployments[].currentRevisionName`	`string \| null`	Optional
`deployments[].previousRevisionName`	`string \| null`	Optional
`deployments[].deploymentStatus`	`string \| null`	Optional
`deployments[].cpu`	`string \| null`	Optional
`deployments[].memory`	`string \| null`	Optional
`deployments[].minReplicas`	`integer(int32)`	Optional
`deployments[].maxReplicas`	`integer(int32)`	Optional
`deployments[].lastDeployStartedAt`	`string(date-time) \| null`	Optional
`deployments[].lastDeployCompletedAt`	`string(date-time) \| null`	Optional
`deployments[].operationId`	`string \| null`	Optional
`deployments[].lastHealthStatusCode`	`integer(int32) \| null`	Optional
`deployments[].lastHealthCheckedAt`	`string(date-time) \| null`	Optional
`deployments[].lastError`	`string \| null`	Optional
`deployments[].deploymentConfigId`	`string \| null`	Optional
`deployments[].deploymentKind`	`string \| null`	Optional
`deployments[].afdCustomDomainName`	`string \| null`	Optional
`deployments[].afdRouteName`	`string \| null`	Optional
`deployments[].afdOriginGroupName`	`string \| null`	Optional
`deployments[].preferredPublicBaseUrl`	`string \| null`	Optional
`deployments[].preferredMcpUrl`	`string \| null`	Optional
`deployments[].customDomain`	`McpServerCustomDomainResponse`	Optional
`deployments[].customDomain.id`	`string \| null`	Optional
`deployments[].customDomain.organizationId`	`string \| null`	Optional
`deployments[].customDomain.mcpServerId`	`string \| null`	Optional
`deployments[].customDomain.deploymentConfigId`	`string \| null`	Optional
`deployments[].customDomain.environment`	`string \| null`	Optional
`deployments[].customDomain.hostName`	`string \| null`	Optional
`deployments[].customDomain.status`	`string \| null`	Optional
`deployments[].customDomain.mcpUrl`	`string \| null`	Optional
`deployments[].customDomain.canonicalMcpUrl`	`string \| null`	Optional
`deployments[].customDomain.verificationToken`	`string \| null`	Optional
`deployments[].customDomain.dnsTargetHostName`	`string \| null`	Optional
`deployments[].customDomain.afdCustomDomainName`	`string \| null`	Optional
`deployments[].customDomain.afdCustomDomainId`	`string \| null`	Optional
`deployments[].customDomain.lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`deployments[].customDomain.lastError`	`string \| null`	Optional
`deployments[].customDomain.dnsRecords`	`McpServerCustomDomainDnsRecordResponse[] \| null`	Optional
`deployments[].targets`	`McpServerDeploymentTargetResponse[] \| null`	Optional

{
  "deployments": [
    {
      "id": "id_123",
      "mcpServerId": "mcp_5Qp8wYz",
      "organizationId": "org_7Hf3kQ2",
      "environment": "prod",
      "region": "westus3",
      "serverSlug": "support-api",
      "publicBaseUrl": "https://api.example.com",
      "containerAppName": "Support API",
      "internalBaseUrl": "https://api.example.com",
      "imageReference": "string",
      "currentRevisionName": "Support API",
      "previousRevisionName": "Support API",
      "deploymentStatus": "active",
      "cpu": "string",
      "memory": "string",
      "minReplicas": 1,
      "maxReplicas": 1,
      "lastDeployStartedAt": "2026-05-29T18:20:11Z",
      "lastDeployCompletedAt": "2026-05-29T18:20:11Z",
      "operationId": "id_123",
      "lastHealthStatusCode": 1,
      "lastHealthCheckedAt": "2026-05-29T18:20:11Z",
      "lastError": "string",
      "deploymentConfigId": "id_123",
      "deploymentKind": "string",
      "afdCustomDomainName": "Support API",
      "afdRouteName": "Support API",
      "afdOriginGroupName": "https://api.example.com",
      "preferredPublicBaseUrl": "https://api.example.com",
      "preferredMcpUrl": "https://api.example.com",
      "customDomain": {
        "id": "id_123",
        "organizationId": "org_7Hf3kQ2",
        "mcpServerId": "mcp_5Qp8wYz",
        "deploymentConfigId": "id_123",
        "environment": "prod",
        "hostName": "app.example.com",
        "status": "active",
        "mcpUrl": "https://api.example.com",
        "canonicalMcpUrl": "https://api.example.com",
        "verificationToken": "redacted",
        "dnsTargetHostName": "app.example.com",
        "afdCustomDomainName": "Support API",
        "afdCustomDomainId": "id_123",
        "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
        "lastError": "string",
        "dnsRecords": []
      },
      "targets": [
        {}
      ]
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployments/{deploymentId}Get one deployment.Get one deployment.

Request bodynone

No request body.

Response body200McpServerDeploymentResponse

Field	Type	Required
`id`	`string \| null`	Optional
`mcpServerId`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`region`	`string \| null`	Optional
`serverSlug`	`string \| null`	Optional
`publicBaseUrl`	`string \| null`	Optional
`containerAppName`	`string \| null`	Optional
`internalBaseUrl`	`string \| null`	Optional
`imageReference`	`string \| null`	Optional
`currentRevisionName`	`string \| null`	Optional
`previousRevisionName`	`string \| null`	Optional
`deploymentStatus`	`string \| null`	Optional
`cpu`	`string \| null`	Optional
`memory`	`string \| null`	Optional
`minReplicas`	`integer(int32)`	Optional
`maxReplicas`	`integer(int32)`	Optional
`lastDeployStartedAt`	`string(date-time) \| null`	Optional
`lastDeployCompletedAt`	`string(date-time) \| null`	Optional
`operationId`	`string \| null`	Optional
`lastHealthStatusCode`	`integer(int32) \| null`	Optional
`lastHealthCheckedAt`	`string(date-time) \| null`	Optional
`lastError`	`string \| null`	Optional
`deploymentConfigId`	`string \| null`	Optional
`deploymentKind`	`string \| null`	Optional
`afdCustomDomainName`	`string \| null`	Optional
`afdRouteName`	`string \| null`	Optional
`afdOriginGroupName`	`string \| null`	Optional
`preferredPublicBaseUrl`	`string \| null`	Optional
`preferredMcpUrl`	`string \| null`	Optional
`customDomain`	`McpServerCustomDomainResponse`	Optional
`customDomain.id`	`string \| null`	Optional
`customDomain.organizationId`	`string \| null`	Optional
`customDomain.mcpServerId`	`string \| null`	Optional
`customDomain.deploymentConfigId`	`string \| null`	Optional
`customDomain.environment`	`string \| null`	Optional
`customDomain.hostName`	`string \| null`	Optional
`customDomain.status`	`string \| null`	Optional
`customDomain.mcpUrl`	`string \| null`	Optional
`customDomain.canonicalMcpUrl`	`string \| null`	Optional
`customDomain.verificationToken`	`string \| null`	Optional
`customDomain.dnsTargetHostName`	`string \| null`	Optional
`customDomain.afdCustomDomainName`	`string \| null`	Optional
`customDomain.afdCustomDomainId`	`string \| null`	Optional
`customDomain.lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`customDomain.lastError`	`string \| null`	Optional
`customDomain.dnsRecords`	`McpServerCustomDomainDnsRecordResponse[] \| null`	Optional
`customDomain.dnsRecords[].type`	`string \| null`	Optional
`customDomain.dnsRecords[].name`	`string \| null`	Optional
`customDomain.dnsRecords[].value`	`string \| null`	Optional
`targets`	`McpServerDeploymentTargetResponse[] \| null`	Optional
`targets[].id`	`string \| null`	Optional
`targets[].deploymentId`	`string \| null`	Optional
`targets[].region`	`string \| null`	Optional
`targets[].containerAppName`	`string \| null`	Optional
`targets[].containerAppFqdn`	`string \| null`	Optional
`targets[].publicOriginFqdn`	`string \| null`	Optional
`targets[].imageReference`	`string \| null`	Optional
`targets[].currentRevisionName`	`string \| null`	Optional
`targets[].previousRevisionName`	`string \| null`	Optional
`targets[].cpu`	`string \| null`	Optional
`targets[].memory`	`string \| null`	Optional
`targets[].minReplicas`	`integer(int32)`	Optional
`targets[].maxReplicas`	`integer(int32)`	Optional
`targets[].targetStatus`	`string \| null`	Optional
`targets[].afdOriginName`	`string \| null`	Optional
`targets[].routingEnabled`	`boolean`	Optional
`targets[].lastHealthStatusCode`	`integer(int32) \| null`	Optional
`targets[].lastHealthCheckedAt`	`string(date-time) \| null`	Optional
`targets[].lastError`	`string \| null`	Optional

{
  "id": "id_123",
  "mcpServerId": "mcp_5Qp8wYz",
  "organizationId": "org_7Hf3kQ2",
  "environment": "prod",
  "region": "westus3",
  "serverSlug": "support-api",
  "publicBaseUrl": "https://api.example.com",
  "containerAppName": "Support API",
  "internalBaseUrl": "https://api.example.com",
  "imageReference": "string",
  "currentRevisionName": "Support API",
  "previousRevisionName": "Support API",
  "deploymentStatus": "active",
  "cpu": "string",
  "memory": "string",
  "minReplicas": 1,
  "maxReplicas": 1,
  "lastDeployStartedAt": "2026-05-29T18:20:11Z",
  "lastDeployCompletedAt": "2026-05-29T18:20:11Z",
  "operationId": "id_123",
  "lastHealthStatusCode": 1,
  "lastHealthCheckedAt": "2026-05-29T18:20:11Z",
  "lastError": "string",
  "deploymentConfigId": "id_123",
  "deploymentKind": "string",
  "afdCustomDomainName": "Support API",
  "afdRouteName": "Support API",
  "afdOriginGroupName": "https://api.example.com",
  "preferredPublicBaseUrl": "https://api.example.com",
  "preferredMcpUrl": "https://api.example.com",
  "customDomain": {
    "id": "id_123",
    "organizationId": "org_7Hf3kQ2",
    "mcpServerId": "mcp_5Qp8wYz",
    "deploymentConfigId": "id_123",
    "environment": "prod",
    "hostName": "app.example.com",
    "status": "active",
    "mcpUrl": "https://api.example.com",
    "canonicalMcpUrl": "https://api.example.com",
    "verificationToken": "redacted",
    "dnsTargetHostName": "app.example.com",
    "afdCustomDomainName": "Support API",
    "afdCustomDomainId": "id_123",
    "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
    "lastError": "string",
    "dnsRecords": [
      {
        "type": "string",
        "name": "Support API",
        "value": "string"
      }
    ]
  },
  "targets": [
    {
      "id": "id_123",
      "deploymentId": "id_123",
      "region": "westus3",
      "containerAppName": "Support API",
      "containerAppFqdn": "string",
      "publicOriginFqdn": "https://api.example.com",
      "imageReference": "string",
      "currentRevisionName": "Support API",
      "previousRevisionName": "Support API",
      "cpu": "string",
      "memory": "string",
      "minReplicas": 1,
      "maxReplicas": 1,
      "targetStatus": "active",
      "afdOriginName": "https://api.example.com",
      "routingEnabled": true,
      "lastHealthStatusCode": 1,
      "lastHealthCheckedAt": "2026-05-29T18:20:11Z",
      "lastError": "string"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployments/{deploymentId}/targets/{targetId}/logsGet logs for one deployment target.Get logs for one deployment target.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`tail`	query	`integer(int32)`	Optional	`100`

Response body200McpServerDeploymentLogsResponse

Field	Type	Required
`mcpServerId`	`string \| null`	Optional
`deploymentId`	`string \| null`	Optional
`lines`	`string[] \| null`	Optional

{
  "mcpServerId": "mcp_5Qp8wYz",
  "deploymentId": "id_123",
  "lines": [
    "string"
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-operationsList publish and deployment operations.List publish and deployment operations.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200McpServerDeploymentOperationListResponse

Field	Type	Required
`operations`	`McpServerDeploymentOperationResponse[] \| null`	Optional
`operations[].id`	`string \| null`	Optional
`operations[].mcpServerId`	`string \| null`	Optional
`operations[].organizationId`	`string \| null`	Optional
`operations[].environment`	`string \| null`	Optional
`operations[].operationType`	`string \| null`	Optional
`operations[].region`	`string \| null`	Optional
`operations[].status`	`string \| null`	Optional
`operations[].idempotencyKey`	`string \| null`	Optional
`operations[].startedAt`	`string(date-time)`	Optional
`operations[].completedAt`	`string(date-time) \| null`	Optional
`operations[].lastError`	`string \| null`	Optional
`operations[].relatedDeploymentId`	`string \| null`	Optional
`operations[].relatedTargetId`	`string \| null`	Optional
`operations[].backgroundJobId`	`string \| null`	Optional

{
  "operations": [
    {
      "id": "id_123",
      "mcpServerId": "mcp_5Qp8wYz",
      "organizationId": "org_7Hf3kQ2",
      "environment": "prod",
      "operationType": "string",
      "region": "westus3",
      "status": "active",
      "idempotencyKey": "string",
      "startedAt": "2026-05-29T18:20:11Z",
      "completedAt": "2026-05-29T18:20:11Z",
      "lastError": "string",
      "relatedDeploymentId": "id_123",
      "relatedTargetId": "id_123",
      "backgroundJobId": "id_123"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-operations/{operationId}Get one operation's status.Get one operation's status.

Request bodynone

No request body.

Response body200McpServerDeploymentOperationResponse

Field	Type	Required
`id`	`string \| null`	Optional
`mcpServerId`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`operationType`	`string \| null`	Optional
`region`	`string \| null`	Optional
`status`	`string \| null`	Optional
`idempotencyKey`	`string \| null`	Optional
`startedAt`	`string(date-time)`	Optional
`completedAt`	`string(date-time) \| null`	Optional
`lastError`	`string \| null`	Optional
`relatedDeploymentId`	`string \| null`	Optional
`relatedTargetId`	`string \| null`	Optional
`backgroundJobId`	`string \| null`	Optional

{
  "id": "id_123",
  "mcpServerId": "mcp_5Qp8wYz",
  "organizationId": "org_7Hf3kQ2",
  "environment": "prod",
  "operationType": "string",
  "region": "westus3",
  "status": "active",
  "idempotencyKey": "string",
  "startedAt": "2026-05-29T18:20:11Z",
  "completedAt": "2026-05-29T18:20:11Z",
  "lastError": "string",
  "relatedDeploymentId": "id_123",
  "relatedTargetId": "id_123",
  "backgroundJobId": "id_123"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/runtime-targets/{region}/logs/streamStream runtime logs for one region.Stream runtime logs for one region.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/hosting-checksRun DNS, TLS, routing, runtime, and MCP checks.Run DNS, TLS, routing, runtime, and MCP checks.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200DeploymentDoctorResponse

Field	Type	Required
`serverId`	`string \| null`	Optional
`publicUrl`	`string \| null`	Optional
`checks`	`DeploymentDoctorCheckResponse[] \| null`	Optional
`checks[].key`	`string \| null`	Optional
`checks[].label`	`string \| null`	Optional
`checks[].status`	`string \| null`	Optional
`checks[].message`	`string \| null`	Optional
`checks[].details`	`string \| null`	Optional

{
  "serverId": "mcp_5Qp8wYz",
  "publicUrl": "https://api.example.com",
  "checks": [
    {
      "key": "string",
      "label": "string",
      "status": "active",
      "message": "string",
      "details": "string"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/mcp-smoke/tools-listList tools over MCP against the live runtime.List tools over MCP against the live runtime.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200McpSmokeToolsListResponse

Field	Type	Required
`serverId`	`string \| null`	Optional
`url`	`string \| null`	Optional
`success`	`boolean`	Optional
`statusCode`	`integer(int32) \| null`	Optional
`sessionId`	`string \| null`	Optional
`error`	`string \| null`	Optional
`response`	`unknown \| null`	Optional
`elapsedMs`	`integer(int64)`	Optional

{
  "serverId": "mcp_5Qp8wYz",
  "url": "https://api.example.com",
  "success": true,
  "statusCode": 1,
  "sessionId": "id_123",
  "error": "string",
  "response": {},
  "elapsedMs": 1
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/mcp-smoke/tools/{toolName}/callInvoke a tool over MCP against the live runtime.Invoke a tool over MCP against the live runtime.

Request bodyMcpSmokeToolCallRequest · application/json

Field	Type	Required
`arguments`	`unknown \| null`	Optional

{
  "arguments": {}
}

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200McpSmokeToolCallResponse

Field	Type	Required
`serverId`	`string \| null`	Optional
`toolName`	`string \| null`	Optional
`url`	`string \| null`	Optional
`success`	`boolean`	Optional
`error`	`string \| null`	Optional
`response`	`unknown \| null`	Optional
`elapsedMs`	`integer(int64)`	Optional

{
  "serverId": "mcp_5Qp8wYz",
  "toolName": "Support API",
  "url": "https://api.example.com",
  "success": true,
  "error": "string",
  "response": {},
  "elapsedMs": 1
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Custom domains#

Attach a customer-owned hostname to a hosted server. See custom domains for the staged DNS workflow.

MethodEndpointDescriptionCopy

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domainGet custom-domain status.Get custom-domain status.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200McpServerCustomDomainResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`mcpServerId`	`string \| null`	Optional
`deploymentConfigId`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`hostName`	`string \| null`	Optional
`status`	`string \| null`	Optional
`mcpUrl`	`string \| null`	Optional
`canonicalMcpUrl`	`string \| null`	Optional
`verificationToken`	`string \| null`	Optional
`dnsTargetHostName`	`string \| null`	Optional
`afdCustomDomainName`	`string \| null`	Optional
`afdCustomDomainId`	`string \| null`	Optional
`lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`lastError`	`string \| null`	Optional
`dnsRecords`	`McpServerCustomDomainDnsRecordResponse[] \| null`	Optional
`dnsRecords[].type`	`string \| null`	Optional
`dnsRecords[].name`	`string \| null`	Optional
`dnsRecords[].value`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "mcpServerId": "mcp_5Qp8wYz",
  "deploymentConfigId": "id_123",
  "environment": "prod",
  "hostName": "app.example.com",
  "status": "active",
  "mcpUrl": "https://api.example.com",
  "canonicalMcpUrl": "https://api.example.com",
  "verificationToken": "redacted",
  "dnsTargetHostName": "app.example.com",
  "afdCustomDomainName": "Support API",
  "afdCustomDomainId": "id_123",
  "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
  "lastError": "string",
  "dnsRecords": [
    {
      "type": "string",
      "name": "Support API",
      "value": "string"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domain/validateStart validation and return the ownership TXT record.Start validation and return the ownership TXT record.

Request bodyUpsertMcpServerCustomDomainRequest · application/json

Field	Type	Required
`hostName`	`string`	Required
`environment`	`string \| null`	Optional

{
  "hostName": "app.example.com",
  "environment": "prod"
}

Response body200McpServerCustomDomainResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`mcpServerId`	`string \| null`	Optional
`deploymentConfigId`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`hostName`	`string \| null`	Optional
`status`	`string \| null`	Optional
`mcpUrl`	`string \| null`	Optional
`canonicalMcpUrl`	`string \| null`	Optional
`verificationToken`	`string \| null`	Optional
`dnsTargetHostName`	`string \| null`	Optional
`afdCustomDomainName`	`string \| null`	Optional
`afdCustomDomainId`	`string \| null`	Optional
`lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`lastError`	`string \| null`	Optional
`dnsRecords`	`McpServerCustomDomainDnsRecordResponse[] \| null`	Optional
`dnsRecords[].type`	`string \| null`	Optional
`dnsRecords[].name`	`string \| null`	Optional
`dnsRecords[].value`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "mcpServerId": "mcp_5Qp8wYz",
  "deploymentConfigId": "id_123",
  "environment": "prod",
  "hostName": "app.example.com",
  "status": "active",
  "mcpUrl": "https://api.example.com",
  "canonicalMcpUrl": "https://api.example.com",
  "verificationToken": "redacted",
  "dnsTargetHostName": "app.example.com",
  "afdCustomDomainName": "Support API",
  "afdCustomDomainId": "id_123",
  "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
  "lastError": "string",
  "dnsRecords": [
    {
      "type": "string",
      "name": "Support API",
      "value": "string"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domain/confirm-ownershipConfirm ownership after the TXT record resolves.Confirm ownership after the TXT record resolves.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200McpServerCustomDomainResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`mcpServerId`	`string \| null`	Optional
`deploymentConfigId`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`hostName`	`string \| null`	Optional
`status`	`string \| null`	Optional
`mcpUrl`	`string \| null`	Optional
`canonicalMcpUrl`	`string \| null`	Optional
`verificationToken`	`string \| null`	Optional
`dnsTargetHostName`	`string \| null`	Optional
`afdCustomDomainName`	`string \| null`	Optional
`afdCustomDomainId`	`string \| null`	Optional
`lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`lastError`	`string \| null`	Optional
`dnsRecords`	`McpServerCustomDomainDnsRecordResponse[] \| null`	Optional
`dnsRecords[].type`	`string \| null`	Optional
`dnsRecords[].name`	`string \| null`	Optional
`dnsRecords[].value`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "mcpServerId": "mcp_5Qp8wYz",
  "deploymentConfigId": "id_123",
  "environment": "prod",
  "hostName": "app.example.com",
  "status": "active",
  "mcpUrl": "https://api.example.com",
  "canonicalMcpUrl": "https://api.example.com",
  "verificationToken": "redacted",
  "dnsTargetHostName": "app.example.com",
  "afdCustomDomainName": "Support API",
  "afdCustomDomainId": "id_123",
  "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
  "lastError": "string",
  "dnsRecords": [
    {
      "type": "string",
      "name": "Support API",
      "value": "string"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domain/finalizeFinalize routing once CNAME and TXT records propagate.Finalize routing once CNAME and TXT records propagate.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body200McpServerCustomDomainResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`mcpServerId`	`string \| null`	Optional
`deploymentConfigId`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`hostName`	`string \| null`	Optional
`status`	`string \| null`	Optional
`mcpUrl`	`string \| null`	Optional
`canonicalMcpUrl`	`string \| null`	Optional
`verificationToken`	`string \| null`	Optional
`dnsTargetHostName`	`string \| null`	Optional
`afdCustomDomainName`	`string \| null`	Optional
`afdCustomDomainId`	`string \| null`	Optional
`lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`lastError`	`string \| null`	Optional
`dnsRecords`	`McpServerCustomDomainDnsRecordResponse[] \| null`	Optional
`dnsRecords[].type`	`string \| null`	Optional
`dnsRecords[].name`	`string \| null`	Optional
`dnsRecords[].value`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "mcpServerId": "mcp_5Qp8wYz",
  "deploymentConfigId": "id_123",
  "environment": "prod",
  "hostName": "app.example.com",
  "status": "active",
  "mcpUrl": "https://api.example.com",
  "canonicalMcpUrl": "https://api.example.com",
  "verificationToken": "redacted",
  "dnsTargetHostName": "app.example.com",
  "afdCustomDomainName": "Support API",
  "afdCustomDomainId": "id_123",
  "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
  "lastError": "string",
  "dnsRecords": [
    {
      "type": "string",
      "name": "Support API",
      "value": "string"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}/mcp-servers/{serverId}/custom-domainRemove the custom domain.Remove the custom domain.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Gateway attachment#

MethodEndpointDescriptionCopy

GET/api/v1/organizations/{orgId}/mcp-servers/{serverId}/gatewayGet the server's gateway attachment.Get the server's gateway attachment.

Request bodynone

No request body.

Response body200McpServerGatewayResponse

Field	Type	Required
`gatewayId`	`string \| null`	Optional
`gatewayName`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`publicId`	`string \| null`	Optional
`publicGatewayUrl`	`string \| null`	Optional
`protectedResourceMetadataUrl`	`string \| null`	Optional
`pathProtectedResourceMetadataUrl`	`string \| null`	Optional
`hostedAuthorizationServerUrl`	`string \| null`	Optional
`hostedAuthorizationServerMetadataUrl`	`string \| null`	Optional
`authorizationEndpoint`	`string \| null`	Optional
`tokenEndpoint`	`string \| null`	Optional
`registrationEndpoint`	`string \| null`	Optional
`hostedResource`	`string \| null`	Optional
`authorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`gatewayDefaultResource`	`string \| null`	Optional
`gatewayDefaultScopes`	`string[] \| null`	Optional
`resource`	`string \| null`	Optional
`scopes`	`string[] \| null`	Optional
`usesGatewayDefaultResource`	`boolean`	Optional
`usesGatewayDefaultScopes`	`boolean`	Optional
`resourceOverride`	`string \| null`	Optional
`scopesOverride`	`string[] \| null`	Optional
`workerBaseUrl`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional

{
  "gatewayId": "gw_4Jk9nQa",
  "gatewayName": "Support API",
  "provider": "openai",
  "publicId": "id_123",
  "publicGatewayUrl": "https://api.example.com",
  "protectedResourceMetadataUrl": "https://api.example.com",
  "pathProtectedResourceMetadataUrl": "https://api.example.com",
  "hostedAuthorizationServerUrl": "https://api.example.com",
  "hostedAuthorizationServerMetadataUrl": "https://api.example.com",
  "authorizationEndpoint": "string",
  "tokenEndpoint": "redacted",
  "registrationEndpoint": "string",
  "hostedResource": "string",
  "authorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "clientId": "id_123",
  "gatewayDefaultResource": "string",
  "gatewayDefaultScopes": [
    "openid"
  ],
  "resource": "string",
  "scopes": [
    "openid"
  ],
  "usesGatewayDefaultResource": true,
  "usesGatewayDefaultScopes": true,
  "resourceOverride": "string",
  "scopesOverride": [
    "openid"
  ],
  "workerBaseUrl": "https://api.example.com",
  "runtimeType": "string"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PUT/api/v1/organizations/{orgId}/mcp-servers/{serverId}/gatewayAttach a gateway to this server.Attach a gateway to this server.

Request bodyAttachGatewayRequest · application/json

Field	Type	Required
`gatewayId`	`string`	Required
`publicId`	`string \| null`	Optional
`resourceOverride`	`string \| null`	Optional
`scopesOverride`	`string[] \| null`	Optional

{
  "gatewayId": "gw_4Jk9nQa",
  "publicId": "id_123",
  "resourceOverride": "string",
  "scopesOverride": [
    "openid"
  ]
}

Response body200McpServerGatewayResponse

Field	Type	Required
`gatewayId`	`string \| null`	Optional
`gatewayName`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`publicId`	`string \| null`	Optional
`publicGatewayUrl`	`string \| null`	Optional
`protectedResourceMetadataUrl`	`string \| null`	Optional
`pathProtectedResourceMetadataUrl`	`string \| null`	Optional
`hostedAuthorizationServerUrl`	`string \| null`	Optional
`hostedAuthorizationServerMetadataUrl`	`string \| null`	Optional
`authorizationEndpoint`	`string \| null`	Optional
`tokenEndpoint`	`string \| null`	Optional
`registrationEndpoint`	`string \| null`	Optional
`hostedResource`	`string \| null`	Optional
`authorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`gatewayDefaultResource`	`string \| null`	Optional
`gatewayDefaultScopes`	`string[] \| null`	Optional
`resource`	`string \| null`	Optional
`scopes`	`string[] \| null`	Optional
`usesGatewayDefaultResource`	`boolean`	Optional
`usesGatewayDefaultScopes`	`boolean`	Optional
`resourceOverride`	`string \| null`	Optional
`scopesOverride`	`string[] \| null`	Optional
`workerBaseUrl`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional

{
  "gatewayId": "gw_4Jk9nQa",
  "gatewayName": "Support API",
  "provider": "openai",
  "publicId": "id_123",
  "publicGatewayUrl": "https://api.example.com",
  "protectedResourceMetadataUrl": "https://api.example.com",
  "pathProtectedResourceMetadataUrl": "https://api.example.com",
  "hostedAuthorizationServerUrl": "https://api.example.com",
  "hostedAuthorizationServerMetadataUrl": "https://api.example.com",
  "authorizationEndpoint": "string",
  "tokenEndpoint": "redacted",
  "registrationEndpoint": "string",
  "hostedResource": "string",
  "authorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "clientId": "id_123",
  "gatewayDefaultResource": "string",
  "gatewayDefaultScopes": [
    "openid"
  ],
  "resource": "string",
  "scopes": [
    "openid"
  ],
  "usesGatewayDefaultResource": true,
  "usesGatewayDefaultScopes": true,
  "resourceOverride": "string",
  "scopesOverride": [
    "openid"
  ],
  "workerBaseUrl": "https://api.example.com",
  "runtimeType": "string"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}/mcp-servers/{serverId}/gatewayDetach the gateway.Detach the gateway.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Gateways#

Reusable OAuth and discovery profiles that front one or more hosted servers.

MethodEndpointDescriptionCopy

GET/api/v1/organizations/{orgId}/gatewaysList gateways.List gateways.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].organizationId`	`string \| null`	Optional
`[].name`	`string \| null`	Optional
`[].description`	`string \| null`	Optional
`[].provider`	`string \| null`	Optional
`[].authorizationServerUrl`	`string \| null`	Optional
`[].authorizationServerMetadataUrl`	`string \| null`	Optional
`[].clientId`	`string \| null`	Optional
`[].resource`	`string \| null`	Optional
`[].scopes`	`string[] \| null`	Optional
`[].status`	`string \| null`	Optional
`[].linkedServerCount`	`integer(int32)`	Optional
`[].grantCount`	`integer(int32)`	Optional
`[].recentRequestCount`	`integer(int32)`	Optional
`[].createdOn`	`string(date-time)`	Optional

[
  {
    "id": "id_123",
    "organizationId": "org_7Hf3kQ2",
    "name": "Support API",
    "description": "Routes support ticket operations to MCP clients.",
    "provider": "openai",
    "authorizationServerUrl": "https://api.example.com",
    "authorizationServerMetadataUrl": "https://api.example.com",
    "clientId": "id_123",
    "resource": "string",
    "scopes": [
      "openid"
    ],
    "status": "active",
    "linkedServerCount": 1,
    "grantCount": 1,
    "recentRequestCount": 2500,
    "createdOn": "2026-05-29T18:20:11Z"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/gatewaysCreate a gateway.Create a gateway.

Request bodyCreateGatewayRequest · application/json

Field	Type	Required
`name`	`string`	Required
`description`	`string \| null`	Optional
`provider`	`string`	Required
`authorizationServerUrl`	`string`	Required
`authorizationServerMetadataUrl`	`string \| null`	Optional
`clientId`	`string`	Required
`resource`	`string`	Required
`scopes`	`string[]`	Required
`identity`	`GatewayIdentitySettingsRequest`	Optional
`identity.mode`	`string`	Required
`identity.endpoint`	`string \| null`	Optional
`identity.subjectClaim`	`string \| null`	Optional
`identity.emailClaim`	`string \| null`	Optional
`identity.organizationClaim`	`string \| null`	Optional
`identity.displayNameClaim`	`string \| null`	Optional

{
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "provider": "openai",
  "authorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "clientId": "id_123",
  "resource": "string",
  "scopes": [
    "openid"
  ],
  "identity": {
    "mode": "string",
    "endpoint": "string",
    "subjectClaim": "string",
    "emailClaim": "teammate@example.com",
    "organizationClaim": "string",
    "displayNameClaim": "Support API"
  }
}

Response body201GatewayDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`authorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`resource`	`string \| null`	Optional
`scopes`	`string[] \| null`	Optional
`identity`	`GatewayIdentitySettingsRequest`	Optional
`identity.mode`	`string`	Required
`identity.endpoint`	`string \| null`	Optional
`identity.subjectClaim`	`string \| null`	Optional
`identity.emailClaim`	`string \| null`	Optional
`identity.organizationClaim`	`string \| null`	Optional
`identity.displayNameClaim`	`string \| null`	Optional
`status`	`string \| null`	Optional
`linkedServerCount`	`integer(int32)`	Optional
`grantCount`	`integer(int32)`	Optional
`recentRequestCount`	`integer(int32)`	Optional
`createdOn`	`string(date-time)`	Optional
`lastHealthCheckAtUtc`	`string(date-time) \| null`	Optional
`lastHealthMessage`	`string \| null`	Optional
`linkedServers`	`GatewayLinkedServerResponse[] \| null`	Optional
`linkedServers[].attachmentId`	`string \| null`	Optional
`linkedServers[].publicId`	`string \| null`	Optional
`linkedServers[].serverId`	`string \| null`	Optional
`linkedServers[].serverName`	`string \| null`	Optional
`linkedServers[].serverSlug`	`string \| null`	Optional
`linkedServers[].runtimeType`	`string \| null`	Optional
`linkedServers[].runtimeUrl`	`string \| null`	Optional
`linkedServers[].publicGatewayUrl`	`string \| null`	Optional
`linkedServers[].gatewayDefaultResource`	`string \| null`	Optional
`linkedServers[].gatewayDefaultScopes`	`string[] \| null`	Optional
`linkedServers[].resource`	`string \| null`	Optional
`linkedServers[].scopes`	`string[] \| null`	Optional
`linkedServers[].usesGatewayDefaultResource`	`boolean`	Optional
`linkedServers[].usesGatewayDefaultScopes`	`boolean`	Optional
`linkedServers[].resourceOverride`	`string \| null`	Optional
`linkedServers[].scopesOverride`	`string[] \| null`	Optional
`linkedServers[].createdOn`	`string(date-time)`	Optional
`grants`	`GatewayGrantResponse[] \| null`	Optional
`grants[].attachmentPublicId`	`string \| null`	Optional
`grants[].grantId`	`string \| null`	Optional
`grants[].subjectId`	`string \| null`	Optional
`grants[].email`	`string \| null`	Optional
`grants[].organizationId`	`string \| null`	Optional
`grants[].displayName`	`string \| null`	Optional
`grants[].resource`	`string \| null`	Optional
`grants[].scopes`	`string[] \| null`	Optional
`grants[].updatedAtUtc`	`string(date-time)`	Optional
`logs`	`GatewayRequestLogResponse[] \| null`	Optional
`logs[].id`	`string \| null`	Optional
`logs[].attachmentPublicId`	`string \| null`	Optional
`logs[].serverId`	`string \| null`	Optional
`logs[].serverName`	`string \| null`	Optional
`logs[].toolName`	`string \| null`	Optional
`logs[].toolLabel`	`string \| null`	Optional
`logs[].durationMs`	`integer(int32)`	Optional
`logs[].success`	`boolean`	Optional
`logs[].errorMessage`	`string \| null`	Optional
`logs[].calledAt`	`string(date-time)`	Optional
`logs[].serviceAccountName`	`string \| null`	Optional
`logs[].externalUserId`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "provider": "openai",
  "authorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "clientId": "id_123",
  "resource": "string",
  "scopes": [
    "openid"
  ],
  "identity": {
    "mode": "string",
    "endpoint": "string",
    "subjectClaim": "string",
    "emailClaim": "teammate@example.com",
    "organizationClaim": "string",
    "displayNameClaim": "Support API"
  },
  "status": "active",
  "linkedServerCount": 1,
  "grantCount": 1,
  "recentRequestCount": 2500,
  "createdOn": "2026-05-29T18:20:11Z",
  "lastHealthCheckAtUtc": "2026-05-29T18:20:11Z",
  "lastHealthMessage": "string",
  "linkedServers": [
    {
      "attachmentId": "id_123",
      "publicId": "id_123",
      "serverId": "mcp_5Qp8wYz",
      "serverName": "Support API",
      "serverSlug": "support-api",
      "runtimeType": "string",
      "runtimeUrl": "https://api.example.com",
      "publicGatewayUrl": "https://api.example.com",
      "gatewayDefaultResource": "string",
      "gatewayDefaultScopes": [
        "openid"
      ],
      "resource": "string",
      "scopes": [
        "openid"
      ],
      "usesGatewayDefaultResource": true,
      "usesGatewayDefaultScopes": true,
      "resourceOverride": "string",
      "scopesOverride": [
        "openid"
      ],
      "createdOn": "2026-05-29T18:20:11Z"
    }
  ],
  "grants": [
    {
      "attachmentPublicId": "id_123",
      "grantId": "id_123",
      "subjectId": "id_123",
      "email": "teammate@example.com",
      "organizationId": "org_7Hf3kQ2",
      "displayName": "Support API",
      "resource": "string",
      "scopes": [
        "openid"
      ],
      "updatedAtUtc": "2026-05-29T18:20:11Z"
    }
  ],
  "logs": [
    {
      "id": "id_123",
      "attachmentPublicId": "id_123",
      "serverId": "mcp_5Qp8wYz",
      "serverName": "Support API",
      "toolName": "Support API",
      "toolLabel": "string",
      "durationMs": 1,
      "success": true,
      "errorMessage": "string",
      "calledAt": "2026-05-29T18:20:11Z",
      "serviceAccountName": "Support API",
      "externalUserId": "id_123"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/gateways/{gatewayId}Get a gateway.Get a gateway.

Request bodynone

No request body.

Response body200GatewayDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`authorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`resource`	`string \| null`	Optional
`scopes`	`string[] \| null`	Optional
`identity`	`GatewayIdentitySettingsRequest`	Optional
`identity.mode`	`string`	Required
`identity.endpoint`	`string \| null`	Optional
`identity.subjectClaim`	`string \| null`	Optional
`identity.emailClaim`	`string \| null`	Optional
`identity.organizationClaim`	`string \| null`	Optional
`identity.displayNameClaim`	`string \| null`	Optional
`status`	`string \| null`	Optional
`linkedServerCount`	`integer(int32)`	Optional
`grantCount`	`integer(int32)`	Optional
`recentRequestCount`	`integer(int32)`	Optional
`createdOn`	`string(date-time)`	Optional
`lastHealthCheckAtUtc`	`string(date-time) \| null`	Optional
`lastHealthMessage`	`string \| null`	Optional
`linkedServers`	`GatewayLinkedServerResponse[] \| null`	Optional
`linkedServers[].attachmentId`	`string \| null`	Optional
`linkedServers[].publicId`	`string \| null`	Optional
`linkedServers[].serverId`	`string \| null`	Optional
`linkedServers[].serverName`	`string \| null`	Optional
`linkedServers[].serverSlug`	`string \| null`	Optional
`linkedServers[].runtimeType`	`string \| null`	Optional
`linkedServers[].runtimeUrl`	`string \| null`	Optional
`linkedServers[].publicGatewayUrl`	`string \| null`	Optional
`linkedServers[].gatewayDefaultResource`	`string \| null`	Optional
`linkedServers[].gatewayDefaultScopes`	`string[] \| null`	Optional
`linkedServers[].resource`	`string \| null`	Optional
`linkedServers[].scopes`	`string[] \| null`	Optional
`linkedServers[].usesGatewayDefaultResource`	`boolean`	Optional
`linkedServers[].usesGatewayDefaultScopes`	`boolean`	Optional
`linkedServers[].resourceOverride`	`string \| null`	Optional
`linkedServers[].scopesOverride`	`string[] \| null`	Optional
`linkedServers[].createdOn`	`string(date-time)`	Optional
`grants`	`GatewayGrantResponse[] \| null`	Optional
`grants[].attachmentPublicId`	`string \| null`	Optional
`grants[].grantId`	`string \| null`	Optional
`grants[].subjectId`	`string \| null`	Optional
`grants[].email`	`string \| null`	Optional
`grants[].organizationId`	`string \| null`	Optional
`grants[].displayName`	`string \| null`	Optional
`grants[].resource`	`string \| null`	Optional
`grants[].scopes`	`string[] \| null`	Optional
`grants[].updatedAtUtc`	`string(date-time)`	Optional
`logs`	`GatewayRequestLogResponse[] \| null`	Optional
`logs[].id`	`string \| null`	Optional
`logs[].attachmentPublicId`	`string \| null`	Optional
`logs[].serverId`	`string \| null`	Optional
`logs[].serverName`	`string \| null`	Optional
`logs[].toolName`	`string \| null`	Optional
`logs[].toolLabel`	`string \| null`	Optional
`logs[].durationMs`	`integer(int32)`	Optional
`logs[].success`	`boolean`	Optional
`logs[].errorMessage`	`string \| null`	Optional
`logs[].calledAt`	`string(date-time)`	Optional
`logs[].serviceAccountName`	`string \| null`	Optional
`logs[].externalUserId`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "provider": "openai",
  "authorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "clientId": "id_123",
  "resource": "string",
  "scopes": [
    "openid"
  ],
  "identity": {
    "mode": "string",
    "endpoint": "string",
    "subjectClaim": "string",
    "emailClaim": "teammate@example.com",
    "organizationClaim": "string",
    "displayNameClaim": "Support API"
  },
  "status": "active",
  "linkedServerCount": 1,
  "grantCount": 1,
  "recentRequestCount": 2500,
  "createdOn": "2026-05-29T18:20:11Z",
  "lastHealthCheckAtUtc": "2026-05-29T18:20:11Z",
  "lastHealthMessage": "string",
  "linkedServers": [
    {
      "attachmentId": "id_123",
      "publicId": "id_123",
      "serverId": "mcp_5Qp8wYz",
      "serverName": "Support API",
      "serverSlug": "support-api",
      "runtimeType": "string",
      "runtimeUrl": "https://api.example.com",
      "publicGatewayUrl": "https://api.example.com",
      "gatewayDefaultResource": "string",
      "gatewayDefaultScopes": [
        "openid"
      ],
      "resource": "string",
      "scopes": [
        "openid"
      ],
      "usesGatewayDefaultResource": true,
      "usesGatewayDefaultScopes": true,
      "resourceOverride": "string",
      "scopesOverride": [
        "openid"
      ],
      "createdOn": "2026-05-29T18:20:11Z"
    }
  ],
  "grants": [
    {
      "attachmentPublicId": "id_123",
      "grantId": "id_123",
      "subjectId": "id_123",
      "email": "teammate@example.com",
      "organizationId": "org_7Hf3kQ2",
      "displayName": "Support API",
      "resource": "string",
      "scopes": [
        "openid"
      ],
      "updatedAtUtc": "2026-05-29T18:20:11Z"
    }
  ],
  "logs": [
    {
      "id": "id_123",
      "attachmentPublicId": "id_123",
      "serverId": "mcp_5Qp8wYz",
      "serverName": "Support API",
      "toolName": "Support API",
      "toolLabel": "string",
      "durationMs": 1,
      "success": true,
      "errorMessage": "string",
      "calledAt": "2026-05-29T18:20:11Z",
      "serviceAccountName": "Support API",
      "externalUserId": "id_123"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PUT/api/v1/organizations/{orgId}/gateways/{gatewayId}Update a gateway.Update a gateway.

Request bodyUpdateGatewayRequest · application/json

Field	Type	Required
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`authorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`resource`	`string \| null`	Optional
`scopes`	`string[] \| null`	Optional
`identity`	`GatewayIdentitySettingsRequest`	Optional
`identity.mode`	`string`	Required
`identity.endpoint`	`string \| null`	Optional
`identity.subjectClaim`	`string \| null`	Optional
`identity.emailClaim`	`string \| null`	Optional
`identity.organizationClaim`	`string \| null`	Optional
`identity.displayNameClaim`	`string \| null`	Optional
`status`	`string \| null`	Optional

{
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "provider": "openai",
  "authorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "clientId": "id_123",
  "resource": "string",
  "scopes": [
    "openid"
  ],
  "identity": {
    "mode": "string",
    "endpoint": "string",
    "subjectClaim": "string",
    "emailClaim": "teammate@example.com",
    "organizationClaim": "string",
    "displayNameClaim": "Support API"
  },
  "status": "active"
}

Response body200GatewayDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`authorizationServerUrl`	`string \| null`	Optional
`authorizationServerMetadataUrl`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`resource`	`string \| null`	Optional
`scopes`	`string[] \| null`	Optional
`identity`	`GatewayIdentitySettingsRequest`	Optional
`identity.mode`	`string`	Required
`identity.endpoint`	`string \| null`	Optional
`identity.subjectClaim`	`string \| null`	Optional
`identity.emailClaim`	`string \| null`	Optional
`identity.organizationClaim`	`string \| null`	Optional
`identity.displayNameClaim`	`string \| null`	Optional
`status`	`string \| null`	Optional
`linkedServerCount`	`integer(int32)`	Optional
`grantCount`	`integer(int32)`	Optional
`recentRequestCount`	`integer(int32)`	Optional
`createdOn`	`string(date-time)`	Optional
`lastHealthCheckAtUtc`	`string(date-time) \| null`	Optional
`lastHealthMessage`	`string \| null`	Optional
`linkedServers`	`GatewayLinkedServerResponse[] \| null`	Optional
`linkedServers[].attachmentId`	`string \| null`	Optional
`linkedServers[].publicId`	`string \| null`	Optional
`linkedServers[].serverId`	`string \| null`	Optional
`linkedServers[].serverName`	`string \| null`	Optional
`linkedServers[].serverSlug`	`string \| null`	Optional
`linkedServers[].runtimeType`	`string \| null`	Optional
`linkedServers[].runtimeUrl`	`string \| null`	Optional
`linkedServers[].publicGatewayUrl`	`string \| null`	Optional
`linkedServers[].gatewayDefaultResource`	`string \| null`	Optional
`linkedServers[].gatewayDefaultScopes`	`string[] \| null`	Optional
`linkedServers[].resource`	`string \| null`	Optional
`linkedServers[].scopes`	`string[] \| null`	Optional
`linkedServers[].usesGatewayDefaultResource`	`boolean`	Optional
`linkedServers[].usesGatewayDefaultScopes`	`boolean`	Optional
`linkedServers[].resourceOverride`	`string \| null`	Optional
`linkedServers[].scopesOverride`	`string[] \| null`	Optional
`linkedServers[].createdOn`	`string(date-time)`	Optional
`grants`	`GatewayGrantResponse[] \| null`	Optional
`grants[].attachmentPublicId`	`string \| null`	Optional
`grants[].grantId`	`string \| null`	Optional
`grants[].subjectId`	`string \| null`	Optional
`grants[].email`	`string \| null`	Optional
`grants[].organizationId`	`string \| null`	Optional
`grants[].displayName`	`string \| null`	Optional
`grants[].resource`	`string \| null`	Optional
`grants[].scopes`	`string[] \| null`	Optional
`grants[].updatedAtUtc`	`string(date-time)`	Optional
`logs`	`GatewayRequestLogResponse[] \| null`	Optional
`logs[].id`	`string \| null`	Optional
`logs[].attachmentPublicId`	`string \| null`	Optional
`logs[].serverId`	`string \| null`	Optional
`logs[].serverName`	`string \| null`	Optional
`logs[].toolName`	`string \| null`	Optional
`logs[].toolLabel`	`string \| null`	Optional
`logs[].durationMs`	`integer(int32)`	Optional
`logs[].success`	`boolean`	Optional
`logs[].errorMessage`	`string \| null`	Optional
`logs[].calledAt`	`string(date-time)`	Optional
`logs[].serviceAccountName`	`string \| null`	Optional
`logs[].externalUserId`	`string \| null`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "provider": "openai",
  "authorizationServerUrl": "https://api.example.com",
  "authorizationServerMetadataUrl": "https://api.example.com",
  "clientId": "id_123",
  "resource": "string",
  "scopes": [
    "openid"
  ],
  "identity": {
    "mode": "string",
    "endpoint": "string",
    "subjectClaim": "string",
    "emailClaim": "teammate@example.com",
    "organizationClaim": "string",
    "displayNameClaim": "Support API"
  },
  "status": "active",
  "linkedServerCount": 1,
  "grantCount": 1,
  "recentRequestCount": 2500,
  "createdOn": "2026-05-29T18:20:11Z",
  "lastHealthCheckAtUtc": "2026-05-29T18:20:11Z",
  "lastHealthMessage": "string",
  "linkedServers": [
    {
      "attachmentId": "id_123",
      "publicId": "id_123",
      "serverId": "mcp_5Qp8wYz",
      "serverName": "Support API",
      "serverSlug": "support-api",
      "runtimeType": "string",
      "runtimeUrl": "https://api.example.com",
      "publicGatewayUrl": "https://api.example.com",
      "gatewayDefaultResource": "string",
      "gatewayDefaultScopes": [
        "openid"
      ],
      "resource": "string",
      "scopes": [
        "openid"
      ],
      "usesGatewayDefaultResource": true,
      "usesGatewayDefaultScopes": true,
      "resourceOverride": "string",
      "scopesOverride": [
        "openid"
      ],
      "createdOn": "2026-05-29T18:20:11Z"
    }
  ],
  "grants": [
    {
      "attachmentPublicId": "id_123",
      "grantId": "id_123",
      "subjectId": "id_123",
      "email": "teammate@example.com",
      "organizationId": "org_7Hf3kQ2",
      "displayName": "Support API",
      "resource": "string",
      "scopes": [
        "openid"
      ],
      "updatedAtUtc": "2026-05-29T18:20:11Z"
    }
  ],
  "logs": [
    {
      "id": "id_123",
      "attachmentPublicId": "id_123",
      "serverId": "mcp_5Qp8wYz",
      "serverName": "Support API",
      "toolName": "Support API",
      "toolLabel": "string",
      "durationMs": 1,
      "success": true,
      "errorMessage": "string",
      "calledAt": "2026-05-29T18:20:11Z",
      "serviceAccountName": "Support API",
      "externalUserId": "id_123"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}/gateways/{gatewayId}Delete a gateway.Delete a gateway.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/gateways/{gatewayId}/serversList servers attached to a gateway.List servers attached to a gateway.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].attachmentId`	`string \| null`	Optional
`[].publicId`	`string \| null`	Optional
`[].serverId`	`string \| null`	Optional
`[].serverName`	`string \| null`	Optional
`[].serverSlug`	`string \| null`	Optional
`[].runtimeType`	`string \| null`	Optional
`[].runtimeUrl`	`string \| null`	Optional
`[].publicGatewayUrl`	`string \| null`	Optional
`[].gatewayDefaultResource`	`string \| null`	Optional
`[].gatewayDefaultScopes`	`string[] \| null`	Optional
`[].resource`	`string \| null`	Optional
`[].scopes`	`string[] \| null`	Optional
`[].usesGatewayDefaultResource`	`boolean`	Optional
`[].usesGatewayDefaultScopes`	`boolean`	Optional
`[].resourceOverride`	`string \| null`	Optional
`[].scopesOverride`	`string[] \| null`	Optional
`[].createdOn`	`string(date-time)`	Optional

[
  {
    "attachmentId": "id_123",
    "publicId": "id_123",
    "serverId": "mcp_5Qp8wYz",
    "serverName": "Support API",
    "serverSlug": "support-api",
    "runtimeType": "string",
    "runtimeUrl": "https://api.example.com",
    "publicGatewayUrl": "https://api.example.com",
    "gatewayDefaultResource": "string",
    "gatewayDefaultScopes": [
      "openid"
    ],
    "resource": "string",
    "scopes": [
      "openid"
    ],
    "usesGatewayDefaultResource": true,
    "usesGatewayDefaultScopes": true,
    "resourceOverride": "string",
    "scopesOverride": [
      "openid"
    ],
    "createdOn": "2026-05-29T18:20:11Z"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/gateways/{gatewayId}/grantsList OAuth grants issued through a gateway.List OAuth grants issued through a gateway.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].attachmentPublicId`	`string \| null`	Optional
`[].grantId`	`string \| null`	Optional
`[].subjectId`	`string \| null`	Optional
`[].email`	`string \| null`	Optional
`[].organizationId`	`string \| null`	Optional
`[].displayName`	`string \| null`	Optional
`[].resource`	`string \| null`	Optional
`[].scopes`	`string[] \| null`	Optional
`[].updatedAtUtc`	`string(date-time)`	Optional

[
  {
    "attachmentPublicId": "id_123",
    "grantId": "id_123",
    "subjectId": "id_123",
    "email": "teammate@example.com",
    "organizationId": "org_7Hf3kQ2",
    "displayName": "Support API",
    "resource": "string",
    "scopes": [
      "openid"
    ],
    "updatedAtUtc": "2026-05-29T18:20:11Z"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/gateways/{gatewayId}/logsGet gateway request logs.Get gateway request logs.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`take`	query	`integer(int32)`	Optional	`100`

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].attachmentPublicId`	`string \| null`	Optional
`[].serverId`	`string \| null`	Optional
`[].serverName`	`string \| null`	Optional
`[].toolName`	`string \| null`	Optional
`[].toolLabel`	`string \| null`	Optional
`[].durationMs`	`integer(int32)`	Optional
`[].success`	`boolean`	Optional
`[].errorMessage`	`string \| null`	Optional
`[].calledAt`	`string(date-time)`	Optional
`[].serviceAccountName`	`string \| null`	Optional
`[].externalUserId`	`string \| null`	Optional

[
  {
    "id": "id_123",
    "attachmentPublicId": "id_123",
    "serverId": "mcp_5Qp8wYz",
    "serverName": "Support API",
    "toolName": "Support API",
    "toolLabel": "string",
    "durationMs": 1,
    "success": true,
    "errorMessage": "string",
    "calledAt": "2026-05-29T18:20:11Z",
    "serviceAccountName": "Support API",
    "externalUserId": "id_123"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Agents#

Create agents, inspect usage and conversations, and manage embed keys, verified domains, and budgets.

Lifecycle and usage#

MethodEndpointDescriptionCopy

GET/api/v1/organizations/{orgId}/agent-model-optionsList available agent models.List available agent models.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].provider`	`string \| null`	Optional
`[].deploymentName`	`string \| null`	Optional
`[].displayName`	`string \| null`	Optional
`[].isDefault`	`boolean`	Optional
`[].billingUnit`	`string \| null`	Optional
`[].capabilities`	`AgentModelCapabilities`	Optional
`[].capabilities.text`	`boolean`	Optional
`[].capabilities.realtimeAudioInput`	`boolean`	Optional
`[].capabilities.realtimeAudioOutput`	`boolean`	Optional
`[].capabilities.toolCalls`	`boolean`	Optional
`[].capabilities.transcription`	`boolean`	Optional
`[].capabilities.translation`	`boolean`	Optional
`[].pricing`	`AgentModelPricing`	Optional
`[].pricing.inputTextPerMillionUsd`	`number(double)`	Optional
`[].pricing.cachedInputPerMillionUsd`	`number(double)`	Optional
`[].pricing.outputTextPerMillionUsd`	`number(double)`	Optional
`[].pricing.audioInputPerMillionUsd`	`number(double)`	Optional
`[].pricing.audioOutputPerMillionUsd`	`number(double)`	Optional
`[].pricing.audioInputPerMinuteUsd`	`number(double)`	Optional
`[].pricing.audioOutputPerMinuteUsd`	`number(double)`	Optional
`[].supportsReasoning`	`boolean`	Optional
`[].supportedReasoningEfforts`	`string[] \| null`	Optional
`[].defaultReasoningEffort`	`string \| null`	Optional

[
  {
    "id": "id_123",
    "provider": "openai",
    "deploymentName": "Support API",
    "displayName": "Support API",
    "isDefault": true,
    "billingUnit": "string",
    "capabilities": {
      "text": true,
      "realtimeAudioInput": true,
      "realtimeAudioOutput": true,
      "toolCalls": true,
      "transcription": true,
      "translation": true
    },
    "pricing": {
      "inputTextPerMillionUsd": 100,
      "cachedInputPerMillionUsd": 100,
      "outputTextPerMillionUsd": 100,
      "audioInputPerMillionUsd": 100,
      "audioOutputPerMillionUsd": 100,
      "audioInputPerMinuteUsd": 100,
      "audioOutputPerMinuteUsd": 100
    },
    "supportsReasoning": true,
    "supportedReasoningEfforts": [
      "medium"
    ],
    "defaultReasoningEffort": "medium"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agentsList agents.List agents.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].organizationId`	`string \| null`	Optional
`[].name`	`string \| null`	Optional
`[].model`	`string \| null`	Optional
`[].provider`	`string \| null`	Optional
`[].reasoningEffort`	`string \| null`	Optional
`[].isActive`	`boolean`	Optional
`[].mcpServerCount`	`integer(int32)`	Optional
`[].conversationCount`	`integer(int32)`	Optional
`[].budget`	`AgentBudgetSummaryResponse`	Optional
`[].budget.monthlyBudgetUsd`	`number(double)`	Optional
`[].budget.defaultUserMonthlyBudgetUsd`	`number(double) \| null`	Optional
`[].budget.anonymousMonthlyBudgetUsd`	`number(double) \| null`	Optional
`[].budget.currency`	`string \| null`	Optional
`[].budget.allocationMode`	`string \| null`	Optional
`[].budget.resetDayOfMonthUtc`	`integer(int32)`	Optional
`[].budget.currentMonthSpendUsd`	`number(double)`	Optional
`[].budget.remainingBudgetUsd`	`number(double)`	Optional
`[].budget.trackedUserCount`	`integer(int32)`	Optional
`[].budget.assignedUserCount`	`integer(int32)`	Optional
`[].budget.assignedBudgetUsd`	`number(double)`	Optional
`[].budget.enabled`	`boolean`	Optional
`[].createdOn`	`string(date-time)`	Optional

[
  {
    "id": "id_123",
    "organizationId": "org_7Hf3kQ2",
    "name": "Support API",
    "model": "gpt-4.1-mini",
    "provider": "openai",
    "reasoningEffort": "medium",
    "isActive": true,
    "mcpServerCount": 1,
    "conversationCount": 1,
    "budget": {
      "monthlyBudgetUsd": 100,
      "defaultUserMonthlyBudgetUsd": 100,
      "anonymousMonthlyBudgetUsd": 100,
      "currency": "USD",
      "allocationMode": "string",
      "resetDayOfMonthUtc": 1,
      "currentMonthSpendUsd": 100,
      "remainingBudgetUsd": 100,
      "trackedUserCount": 1,
      "assignedUserCount": 1,
      "assignedBudgetUsd": 100,
      "enabled": true
    },
    "createdOn": "2026-05-29T18:20:11Z"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/agentsCreate an agent.Create an agent.

Request bodyCreateAgentRequest · application/json

Field	Type	Required
`name`	`string`	Required
`mcpServerIds`	`string[]`	Required
`systemPrompt`	`string \| null`	Optional
`model`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`reasoningEffort`	`string \| null`	Optional
`allowedOrigins`	`string \| null`	Optional
`maxTokens`	`integer(int32)`	Optional
`temperature`	`number(float)`	Optional
`budget`	`AgentBudgetConfigRequest`	Optional
`budget.monthlyBudgetUsd`	`number(double)`	Required
`budget.defaultUserMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.anonymousMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.currency`	`string \| null`	Optional
`budget.allocationMode`	`string \| null`	Optional
`budget.resetDayOfMonthUtc`	`integer(int32)`	Optional
`budget.userAllocations`	`AgentUserBudgetAllocationRequest[] \| null`	Optional
`budget.userAllocations[].externalUserId`	`string`	Required
`budget.userAllocations[].monthlyBudgetUsd`	`number(double)`	Required
`budget.enabled`	`boolean`	Optional
`mcpServerAttachments`	`AgentMcpServerAttachment[] \| null`	Optional
`mcpServerAttachments[].mcpServerId`	`string`	Required
`mcpServerAttachments[].enabledToolKeys`	`string[] \| null`	Optional

{
  "name": "Support API",
  "mcpServerIds": [
    "string"
  ],
  "systemPrompt": "Answer with concise, operational guidance.",
  "model": "gpt-4.1-mini",
  "provider": "openai",
  "reasoningEffort": "medium",
  "allowedOrigins": "https://api.example.com",
  "maxTokens": 1,
  "temperature": 0.2,
  "budget": {
    "monthlyBudgetUsd": 100,
    "defaultUserMonthlyBudgetUsd": 100,
    "anonymousMonthlyBudgetUsd": 100,
    "currency": "USD",
    "allocationMode": "string",
    "resetDayOfMonthUtc": 1,
    "userAllocations": [
      {
        "externalUserId": "id_123",
        "monthlyBudgetUsd": 100
      }
    ],
    "enabled": true
  },
  "mcpServerAttachments": [
    {
      "mcpServerId": "mcp_5Qp8wYz",
      "enabledToolKeys": [
        "string"
      ]
    }
  ]
}

Response body201AgentDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`systemPrompt`	`string \| null`	Optional
`model`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`reasoningEffort`	`string \| null`	Optional
`allowedOrigins`	`string \| null`	Optional
`maxTokens`	`integer(int32)`	Optional
`temperature`	`number(float)`	Optional
`isActive`	`boolean`	Optional
`widgetConfig`	`AgentWidgetConfig`	Optional
`widgetConfig.theme`	`string \| null`	Optional
`widgetConfig.position`	`string \| null`	Optional
`widgetConfig.title`	`string \| null`	Optional
`widgetConfig.placeholder`	`string \| null`	Optional
`widgetConfig.welcomeMessage`	`string \| null`	Optional
`conversationCount`	`integer(int32)`	Optional
`externalUserCount`	`integer(int32)`	Optional
`budget`	`AgentBudgetSummaryResponse`	Optional
`budget.monthlyBudgetUsd`	`number(double)`	Optional
`budget.defaultUserMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.anonymousMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.currency`	`string \| null`	Optional
`budget.allocationMode`	`string \| null`	Optional
`budget.resetDayOfMonthUtc`	`integer(int32)`	Optional
`budget.currentMonthSpendUsd`	`number(double)`	Optional
`budget.remainingBudgetUsd`	`number(double)`	Optional
`budget.trackedUserCount`	`integer(int32)`	Optional
`budget.assignedUserCount`	`integer(int32)`	Optional
`budget.assignedBudgetUsd`	`number(double)`	Optional
`budget.enabled`	`boolean`	Optional
`mcpServers`	`AgentMcpServerInfo[] \| null`	Optional
`mcpServers[].mcpServerId`	`string \| null`	Optional
`mcpServers[].mcpServerName`	`string \| null`	Optional
`mcpServers[].mcpServerUrl`	`string \| null`	Optional
`mcpServers[].tools`	`AgentToolSchema[] \| null`	Optional
`mcpServers[].serverKind`	`string \| null`	Optional
`mcpServers[].hasGateway`	`boolean`	Optional
`mcpServers[].catalogStatus`	`string \| null`	Optional
`mcpServers[].catalogError`	`string \| null`	Optional
`mcpServers[].expectedToolKeys`	`string[] \| null`	Optional
`mcpServers[].actualToolKeys`	`string[] \| null`	Optional
`mcpServers[].missingToolKeys`	`string[] \| null`	Optional
`mcpServers[].unexpectedToolKeys`	`string[] \| null`	Optional
`createdOn`	`string(date-time)`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "name": "Support API",
  "systemPrompt": "Answer with concise, operational guidance.",
  "model": "gpt-4.1-mini",
  "provider": "openai",
  "reasoningEffort": "medium",
  "allowedOrigins": "https://api.example.com",
  "maxTokens": 1,
  "temperature": 0.2,
  "isActive": true,
  "widgetConfig": {
    "theme": "string",
    "position": "string",
    "title": "string",
    "placeholder": "string",
    "welcomeMessage": "string"
  },
  "conversationCount": 1,
  "externalUserCount": 1,
  "budget": {
    "monthlyBudgetUsd": 100,
    "defaultUserMonthlyBudgetUsd": 100,
    "anonymousMonthlyBudgetUsd": 100,
    "currency": "USD",
    "allocationMode": "string",
    "resetDayOfMonthUtc": 1,
    "currentMonthSpendUsd": 100,
    "remainingBudgetUsd": 100,
    "trackedUserCount": 1,
    "assignedUserCount": 1,
    "assignedBudgetUsd": 100,
    "enabled": true
  },
  "mcpServers": [
    {
      "mcpServerId": "mcp_5Qp8wYz",
      "mcpServerName": "Support API",
      "mcpServerUrl": "https://api.example.com",
      "tools": [
        {}
      ],
      "serverKind": "string",
      "hasGateway": true,
      "catalogStatus": "active",
      "catalogError": "string",
      "expectedToolKeys": [
        "string"
      ],
      "actualToolKeys": [
        "string"
      ],
      "missingToolKeys": [
        "string"
      ],
      "unexpectedToolKeys": [
        "string"
      ]
    }
  ],
  "createdOn": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agents/{agentId}Get an agent.Get an agent.

Request bodynone

No request body.

Response body200AgentDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`systemPrompt`	`string \| null`	Optional
`model`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`reasoningEffort`	`string \| null`	Optional
`allowedOrigins`	`string \| null`	Optional
`maxTokens`	`integer(int32)`	Optional
`temperature`	`number(float)`	Optional
`isActive`	`boolean`	Optional
`widgetConfig`	`AgentWidgetConfig`	Optional
`widgetConfig.theme`	`string \| null`	Optional
`widgetConfig.position`	`string \| null`	Optional
`widgetConfig.title`	`string \| null`	Optional
`widgetConfig.placeholder`	`string \| null`	Optional
`widgetConfig.welcomeMessage`	`string \| null`	Optional
`conversationCount`	`integer(int32)`	Optional
`externalUserCount`	`integer(int32)`	Optional
`budget`	`AgentBudgetSummaryResponse`	Optional
`budget.monthlyBudgetUsd`	`number(double)`	Optional
`budget.defaultUserMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.anonymousMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.currency`	`string \| null`	Optional
`budget.allocationMode`	`string \| null`	Optional
`budget.resetDayOfMonthUtc`	`integer(int32)`	Optional
`budget.currentMonthSpendUsd`	`number(double)`	Optional
`budget.remainingBudgetUsd`	`number(double)`	Optional
`budget.trackedUserCount`	`integer(int32)`	Optional
`budget.assignedUserCount`	`integer(int32)`	Optional
`budget.assignedBudgetUsd`	`number(double)`	Optional
`budget.enabled`	`boolean`	Optional
`mcpServers`	`AgentMcpServerInfo[] \| null`	Optional
`mcpServers[].mcpServerId`	`string \| null`	Optional
`mcpServers[].mcpServerName`	`string \| null`	Optional
`mcpServers[].mcpServerUrl`	`string \| null`	Optional
`mcpServers[].tools`	`AgentToolSchema[] \| null`	Optional
`mcpServers[].serverKind`	`string \| null`	Optional
`mcpServers[].hasGateway`	`boolean`	Optional
`mcpServers[].catalogStatus`	`string \| null`	Optional
`mcpServers[].catalogError`	`string \| null`	Optional
`mcpServers[].expectedToolKeys`	`string[] \| null`	Optional
`mcpServers[].actualToolKeys`	`string[] \| null`	Optional
`mcpServers[].missingToolKeys`	`string[] \| null`	Optional
`mcpServers[].unexpectedToolKeys`	`string[] \| null`	Optional
`createdOn`	`string(date-time)`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "name": "Support API",
  "systemPrompt": "Answer with concise, operational guidance.",
  "model": "gpt-4.1-mini",
  "provider": "openai",
  "reasoningEffort": "medium",
  "allowedOrigins": "https://api.example.com",
  "maxTokens": 1,
  "temperature": 0.2,
  "isActive": true,
  "widgetConfig": {
    "theme": "string",
    "position": "string",
    "title": "string",
    "placeholder": "string",
    "welcomeMessage": "string"
  },
  "conversationCount": 1,
  "externalUserCount": 1,
  "budget": {
    "monthlyBudgetUsd": 100,
    "defaultUserMonthlyBudgetUsd": 100,
    "anonymousMonthlyBudgetUsd": 100,
    "currency": "USD",
    "allocationMode": "string",
    "resetDayOfMonthUtc": 1,
    "currentMonthSpendUsd": 100,
    "remainingBudgetUsd": 100,
    "trackedUserCount": 1,
    "assignedUserCount": 1,
    "assignedBudgetUsd": 100,
    "enabled": true
  },
  "mcpServers": [
    {
      "mcpServerId": "mcp_5Qp8wYz",
      "mcpServerName": "Support API",
      "mcpServerUrl": "https://api.example.com",
      "tools": [
        {}
      ],
      "serverKind": "string",
      "hasGateway": true,
      "catalogStatus": "active",
      "catalogError": "string",
      "expectedToolKeys": [
        "string"
      ],
      "actualToolKeys": [
        "string"
      ],
      "missingToolKeys": [
        "string"
      ],
      "unexpectedToolKeys": [
        "string"
      ]
    }
  ],
  "createdOn": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PATCH/api/v1/organizations/{orgId}/agents/{agentId}Update an agent.Update an agent.

Request bodyUpdateAgentRequest · application/json

Field	Type	Required
`name`	`string \| null`	Optional
`systemPrompt`	`string \| null`	Optional
`model`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`reasoningEffort`	`string \| null`	Optional
`mcpServerIds`	`string[] \| null`	Optional
`allowedOrigins`	`string \| null`	Optional
`maxTokens`	`integer(int32) \| null`	Optional
`temperature`	`number(float) \| null`	Optional
`isActive`	`boolean \| null`	Optional
`widgetConfig`	`AgentWidgetConfig`	Optional
`widgetConfig.theme`	`string \| null`	Optional
`widgetConfig.position`	`string \| null`	Optional
`widgetConfig.title`	`string \| null`	Optional
`widgetConfig.placeholder`	`string \| null`	Optional
`widgetConfig.welcomeMessage`	`string \| null`	Optional
`budget`	`AgentBudgetConfigRequest`	Optional
`budget.monthlyBudgetUsd`	`number(double)`	Required
`budget.defaultUserMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.anonymousMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.currency`	`string \| null`	Optional
`budget.allocationMode`	`string \| null`	Optional
`budget.resetDayOfMonthUtc`	`integer(int32)`	Optional
`budget.userAllocations`	`AgentUserBudgetAllocationRequest[] \| null`	Optional
`budget.userAllocations[].externalUserId`	`string`	Required
`budget.userAllocations[].monthlyBudgetUsd`	`number(double)`	Required
`budget.enabled`	`boolean`	Optional
`mcpServerAttachments`	`AgentMcpServerAttachment[] \| null`	Optional
`mcpServerAttachments[].mcpServerId`	`string`	Required
`mcpServerAttachments[].enabledToolKeys`	`string[] \| null`	Optional

{
  "name": "Support API",
  "systemPrompt": "Answer with concise, operational guidance.",
  "model": "gpt-4.1-mini",
  "provider": "openai",
  "reasoningEffort": "medium",
  "mcpServerIds": [
    "string"
  ],
  "allowedOrigins": "https://api.example.com",
  "maxTokens": 1,
  "temperature": 0.2,
  "isActive": true,
  "widgetConfig": {
    "theme": "string",
    "position": "string",
    "title": "string",
    "placeholder": "string",
    "welcomeMessage": "string"
  },
  "budget": {
    "monthlyBudgetUsd": 100,
    "defaultUserMonthlyBudgetUsd": 100,
    "anonymousMonthlyBudgetUsd": 100,
    "currency": "USD",
    "allocationMode": "string",
    "resetDayOfMonthUtc": 1,
    "userAllocations": [
      {
        "externalUserId": "id_123",
        "monthlyBudgetUsd": 100
      }
    ],
    "enabled": true
  },
  "mcpServerAttachments": [
    {
      "mcpServerId": "mcp_5Qp8wYz",
      "enabledToolKeys": [
        "string"
      ]
    }
  ]
}

Response body200AgentDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional
`name`	`string \| null`	Optional
`systemPrompt`	`string \| null`	Optional
`model`	`string \| null`	Optional
`provider`	`string \| null`	Optional
`reasoningEffort`	`string \| null`	Optional
`allowedOrigins`	`string \| null`	Optional
`maxTokens`	`integer(int32)`	Optional
`temperature`	`number(float)`	Optional
`isActive`	`boolean`	Optional
`widgetConfig`	`AgentWidgetConfig`	Optional
`widgetConfig.theme`	`string \| null`	Optional
`widgetConfig.position`	`string \| null`	Optional
`widgetConfig.title`	`string \| null`	Optional
`widgetConfig.placeholder`	`string \| null`	Optional
`widgetConfig.welcomeMessage`	`string \| null`	Optional
`conversationCount`	`integer(int32)`	Optional
`externalUserCount`	`integer(int32)`	Optional
`budget`	`AgentBudgetSummaryResponse`	Optional
`budget.monthlyBudgetUsd`	`number(double)`	Optional
`budget.defaultUserMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.anonymousMonthlyBudgetUsd`	`number(double) \| null`	Optional
`budget.currency`	`string \| null`	Optional
`budget.allocationMode`	`string \| null`	Optional
`budget.resetDayOfMonthUtc`	`integer(int32)`	Optional
`budget.currentMonthSpendUsd`	`number(double)`	Optional
`budget.remainingBudgetUsd`	`number(double)`	Optional
`budget.trackedUserCount`	`integer(int32)`	Optional
`budget.assignedUserCount`	`integer(int32)`	Optional
`budget.assignedBudgetUsd`	`number(double)`	Optional
`budget.enabled`	`boolean`	Optional
`mcpServers`	`AgentMcpServerInfo[] \| null`	Optional
`mcpServers[].mcpServerId`	`string \| null`	Optional
`mcpServers[].mcpServerName`	`string \| null`	Optional
`mcpServers[].mcpServerUrl`	`string \| null`	Optional
`mcpServers[].tools`	`AgentToolSchema[] \| null`	Optional
`mcpServers[].serverKind`	`string \| null`	Optional
`mcpServers[].hasGateway`	`boolean`	Optional
`mcpServers[].catalogStatus`	`string \| null`	Optional
`mcpServers[].catalogError`	`string \| null`	Optional
`mcpServers[].expectedToolKeys`	`string[] \| null`	Optional
`mcpServers[].actualToolKeys`	`string[] \| null`	Optional
`mcpServers[].missingToolKeys`	`string[] \| null`	Optional
`mcpServers[].unexpectedToolKeys`	`string[] \| null`	Optional
`createdOn`	`string(date-time)`	Optional

{
  "id": "id_123",
  "organizationId": "org_7Hf3kQ2",
  "name": "Support API",
  "systemPrompt": "Answer with concise, operational guidance.",
  "model": "gpt-4.1-mini",
  "provider": "openai",
  "reasoningEffort": "medium",
  "allowedOrigins": "https://api.example.com",
  "maxTokens": 1,
  "temperature": 0.2,
  "isActive": true,
  "widgetConfig": {
    "theme": "string",
    "position": "string",
    "title": "string",
    "placeholder": "string",
    "welcomeMessage": "string"
  },
  "conversationCount": 1,
  "externalUserCount": 1,
  "budget": {
    "monthlyBudgetUsd": 100,
    "defaultUserMonthlyBudgetUsd": 100,
    "anonymousMonthlyBudgetUsd": 100,
    "currency": "USD",
    "allocationMode": "string",
    "resetDayOfMonthUtc": 1,
    "currentMonthSpendUsd": 100,
    "remainingBudgetUsd": 100,
    "trackedUserCount": 1,
    "assignedUserCount": 1,
    "assignedBudgetUsd": 100,
    "enabled": true
  },
  "mcpServers": [
    {
      "mcpServerId": "mcp_5Qp8wYz",
      "mcpServerName": "Support API",
      "mcpServerUrl": "https://api.example.com",
      "tools": [
        {}
      ],
      "serverKind": "string",
      "hasGateway": true,
      "catalogStatus": "active",
      "catalogError": "string",
      "expectedToolKeys": [
        "string"
      ],
      "actualToolKeys": [
        "string"
      ],
      "missingToolKeys": [
        "string"
      ],
      "unexpectedToolKeys": [
        "string"
      ]
    }
  ],
  "createdOn": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}/agents/{agentId}Delete an agent.Delete an agent.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agents/{agentId}/usageGet usage and cost for an agent.Get usage and cost for an agent.

Request bodynone

No request body.

Response body200AgentBudgetUsageResponse

Field	Type	Required
`summary`	`AgentBudgetSummaryResponse`	Optional
`summary.monthlyBudgetUsd`	`number(double)`	Optional
`summary.defaultUserMonthlyBudgetUsd`	`number(double) \| null`	Optional
`summary.anonymousMonthlyBudgetUsd`	`number(double) \| null`	Optional
`summary.currency`	`string \| null`	Optional
`summary.allocationMode`	`string \| null`	Optional
`summary.resetDayOfMonthUtc`	`integer(int32)`	Optional
`summary.currentMonthSpendUsd`	`number(double)`	Optional
`summary.remainingBudgetUsd`	`number(double)`	Optional
`summary.trackedUserCount`	`integer(int32)`	Optional
`summary.assignedUserCount`	`integer(int32)`	Optional
`summary.assignedBudgetUsd`	`number(double)`	Optional
`summary.enabled`	`boolean`	Optional
`users`	`AgentTrackedUserUsageResponse[] \| null`	Optional
`users[].externalUserId`	`string \| null`	Optional
`users[].displayName`	`string \| null`	Optional
`users[].email`	`string \| null`	Optional
`users[].avatarUrl`	`string \| null`	Optional
`users[].lastSeenAt`	`string(date-time) \| null`	Optional
`users[].assignedBudgetUsd`	`number(double) \| null`	Optional
`users[].effectiveBudgetUsd`	`number(double) \| null`	Optional
`users[].budgetSource`	`string \| null`	Optional
`users[].isAnonymous`	`boolean`	Optional
`users[].currentMonthSpendUsd`	`number(double)`	Optional
`users[].remainingBudgetUsd`	`number(double)`	Optional
`users[].status`	`string \| null`	Optional
`users[].conversationCount`	`integer(int32)`	Optional
`recentLlmCalls`	`AgentLlmCallResponse[] \| null`	Optional
`recentLlmCalls[].id`	`string \| null`	Optional
`recentLlmCalls[].conversationId`	`string \| null`	Optional
`recentLlmCalls[].externalUserId`	`string \| null`	Optional
`recentLlmCalls[].externalUserDisplayName`	`string \| null`	Optional
`recentLlmCalls[].provider`	`string \| null`	Optional
`recentLlmCalls[].usageKind`	`string \| null`	Optional
`recentLlmCalls[].model`	`string \| null`	Optional
`recentLlmCalls[].inputTokens`	`integer(int32)`	Optional
`recentLlmCalls[].outputTokens`	`integer(int32)`	Optional
`recentLlmCalls[].cachedInputTokens`	`integer(int32)`	Optional
`recentLlmCalls[].inputAudioTokens`	`integer(int32)`	Optional
`recentLlmCalls[].outputAudioTokens`	`integer(int32)`	Optional
`recentLlmCalls[].inputAudioDurationMs`	`integer(int32)`	Optional
`recentLlmCalls[].totalTokens`	`integer(int32)`	Optional
`recentLlmCalls[].toolCallCount`	`integer(int32)`	Optional
`recentLlmCalls[].durationMs`	`integer(int32)`	Optional
`recentLlmCalls[].estimatedCostUsd`	`number(double)`	Optional
`recentLlmCalls[].success`	`boolean`	Optional
`recentLlmCalls[].errorMessage`	`string \| null`	Optional
`recentLlmCalls[].realtimeSessionId`	`string \| null`	Optional
`recentLlmCalls[].calledAt`	`string(date-time)`	Optional
`usersPage`	`AgentTrackedUserUsageResponseAgentPagedListResponse`	Optional
`usersPage.data`	`AgentTrackedUserUsageResponse[] \| null`	Optional
`usersPage.data[].externalUserId`	`string \| null`	Optional
`usersPage.data[].displayName`	`string \| null`	Optional
`usersPage.data[].email`	`string \| null`	Optional
`usersPage.data[].avatarUrl`	`string \| null`	Optional
`usersPage.data[].lastSeenAt`	`string(date-time) \| null`	Optional
`usersPage.data[].assignedBudgetUsd`	`number(double) \| null`	Optional
`usersPage.data[].effectiveBudgetUsd`	`number(double) \| null`	Optional
`usersPage.data[].budgetSource`	`string \| null`	Optional
`usersPage.data[].isAnonymous`	`boolean`	Optional
`usersPage.data[].currentMonthSpendUsd`	`number(double)`	Optional
`usersPage.data[].remainingBudgetUsd`	`number(double)`	Optional
`usersPage.data[].status`	`string \| null`	Optional
`usersPage.data[].conversationCount`	`integer(int32)`	Optional
`usersPage.pageSize`	`integer(int32)`	Optional
`usersPage.nextCursor`	`string \| null`	Optional
`usersPage.hasNextPage`	`boolean`	Optional
`recentLlmCallsPage`	`AgentLlmCallResponseAgentPagedListResponse`	Optional
`recentLlmCallsPage.data`	`AgentLlmCallResponse[] \| null`	Optional
`recentLlmCallsPage.data[].id`	`string \| null`	Optional
`recentLlmCallsPage.data[].conversationId`	`string \| null`	Optional
`recentLlmCallsPage.data[].externalUserId`	`string \| null`	Optional
`recentLlmCallsPage.data[].externalUserDisplayName`	`string \| null`	Optional
`recentLlmCallsPage.data[].provider`	`string \| null`	Optional
`recentLlmCallsPage.data[].usageKind`	`string \| null`	Optional
`recentLlmCallsPage.data[].model`	`string \| null`	Optional
`recentLlmCallsPage.data[].inputTokens`	`integer(int32)`	Optional
`recentLlmCallsPage.data[].outputTokens`	`integer(int32)`	Optional
`recentLlmCallsPage.data[].cachedInputTokens`	`integer(int32)`	Optional
`recentLlmCallsPage.data[].inputAudioTokens`	`integer(int32)`	Optional
`recentLlmCallsPage.data[].outputAudioTokens`	`integer(int32)`	Optional
`recentLlmCallsPage.data[].inputAudioDurationMs`	`integer(int32)`	Optional
`recentLlmCallsPage.data[].totalTokens`	`integer(int32)`	Optional
`recentLlmCallsPage.data[].toolCallCount`	`integer(int32)`	Optional
`recentLlmCallsPage.data[].durationMs`	`integer(int32)`	Optional
`recentLlmCallsPage.data[].estimatedCostUsd`	`number(double)`	Optional
`recentLlmCallsPage.data[].success`	`boolean`	Optional
`recentLlmCallsPage.data[].errorMessage`	`string \| null`	Optional
`recentLlmCallsPage.data[].realtimeSessionId`	`string \| null`	Optional
`recentLlmCallsPage.data[].calledAt`	`string(date-time)`	Optional
`recentLlmCallsPage.pageSize`	`integer(int32)`	Optional
`recentLlmCallsPage.nextCursor`	`string \| null`	Optional
`recentLlmCallsPage.hasNextPage`	`boolean`	Optional

{
  "summary": {
    "monthlyBudgetUsd": 100,
    "defaultUserMonthlyBudgetUsd": 100,
    "anonymousMonthlyBudgetUsd": 100,
    "currency": "USD",
    "allocationMode": "string",
    "resetDayOfMonthUtc": 1,
    "currentMonthSpendUsd": 100,
    "remainingBudgetUsd": 100,
    "trackedUserCount": 1,
    "assignedUserCount": 1,
    "assignedBudgetUsd": 100,
    "enabled": true
  },
  "users": [
    {
      "externalUserId": "id_123",
      "displayName": "Support API",
      "email": "teammate@example.com",
      "avatarUrl": "https://api.example.com",
      "lastSeenAt": "2026-05-29T18:20:11Z",
      "assignedBudgetUsd": 100,
      "effectiveBudgetUsd": 100,
      "budgetSource": "string",
      "isAnonymous": true,
      "currentMonthSpendUsd": 100,
      "remainingBudgetUsd": 100,
      "status": "active",
      "conversationCount": 1
    }
  ],
  "recentLlmCalls": [
    {
      "id": "id_123",
      "conversationId": "id_123",
      "externalUserId": "id_123",
      "externalUserDisplayName": "Support API",
      "provider": "openai",
      "usageKind": "string",
      "model": "gpt-4.1-mini",
      "inputTokens": 1,
      "outputTokens": 1,
      "cachedInputTokens": 1,
      "inputAudioTokens": 1,
      "outputAudioTokens": 1,
      "inputAudioDurationMs": 1,
      "totalTokens": 1,
      "toolCallCount": 1,
      "durationMs": 1,
      "estimatedCostUsd": 100,
      "success": true,
      "errorMessage": "string",
      "realtimeSessionId": "id_123",
      "calledAt": "2026-05-29T18:20:11Z"
    }
  ],
  "usersPage": {
    "data": [
      {
        "externalUserId": "id_123",
        "displayName": "Support API",
        "email": "teammate@example.com",
        "avatarUrl": "https://api.example.com",
        "lastSeenAt": "2026-05-29T18:20:11Z",
        "assignedBudgetUsd": 100,
        "effectiveBudgetUsd": 100,
        "budgetSource": "string",
        "isAnonymous": true,
        "currentMonthSpendUsd": 100,
        "remainingBudgetUsd": 100,
        "status": "active",
        "conversationCount": 1
      }
    ],
    "pageSize": 1,
    "nextCursor": "string",
    "hasNextPage": true
  },
  "recentLlmCallsPage": {
    "data": [
      {
        "id": "id_123",
        "conversationId": "id_123",
        "externalUserId": "id_123",
        "externalUserDisplayName": "Support API",
        "provider": "openai",
        "usageKind": "string",
        "model": "gpt-4.1-mini",
        "inputTokens": 1,
        "outputTokens": 1,
        "cachedInputTokens": 1,
        "inputAudioTokens": 1,
        "outputAudioTokens": 1,
        "inputAudioDurationMs": 1,
        "totalTokens": 1,
        "toolCallCount": 1,
        "durationMs": 1,
        "estimatedCostUsd": 100,
        "success": true,
        "errorMessage": "string",
        "realtimeSessionId": "id_123",
        "calledAt": "2026-05-29T18:20:11Z"
      }
    ],
    "pageSize": 1,
    "nextCursor": "string",
    "hasNextPage": true
  }
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agents/{agentId}/usage/usersGet per-user usage.Get per-user usage.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`cursor`	query	`string`	Optional	`-`
`pageSize`	query	`integer(int32)`	Optional	`20`

Response body200AgentTrackedUserUsageResponseAgentPagedListResponse

Field	Type	Required
`data`	`AgentTrackedUserUsageResponse[] \| null`	Optional
`data[].externalUserId`	`string \| null`	Optional
`data[].displayName`	`string \| null`	Optional
`data[].email`	`string \| null`	Optional
`data[].avatarUrl`	`string \| null`	Optional
`data[].lastSeenAt`	`string(date-time) \| null`	Optional
`data[].assignedBudgetUsd`	`number(double) \| null`	Optional
`data[].effectiveBudgetUsd`	`number(double) \| null`	Optional
`data[].budgetSource`	`string \| null`	Optional
`data[].isAnonymous`	`boolean`	Optional
`data[].currentMonthSpendUsd`	`number(double)`	Optional
`data[].remainingBudgetUsd`	`number(double)`	Optional
`data[].status`	`string \| null`	Optional
`data[].conversationCount`	`integer(int32)`	Optional
`pageSize`	`integer(int32)`	Optional
`nextCursor`	`string \| null`	Optional
`hasNextPage`	`boolean`	Optional

{
  "data": [
    {
      "externalUserId": "id_123",
      "displayName": "Support API",
      "email": "teammate@example.com",
      "avatarUrl": "https://api.example.com",
      "lastSeenAt": "2026-05-29T18:20:11Z",
      "assignedBudgetUsd": 100,
      "effectiveBudgetUsd": 100,
      "budgetSource": "string",
      "isAnonymous": true,
      "currentMonthSpendUsd": 100,
      "remainingBudgetUsd": 100,
      "status": "active",
      "conversationCount": 1
    }
  ],
  "pageSize": 1,
  "nextCursor": "string",
  "hasNextPage": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agents/{agentId}/usage/llm-callsGet LLM call logs.Get LLM call logs.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`cursor`	query	`string`	Optional	`-`
`pageSize`	query	`integer(int32)`	Optional	`20`

Response body200AgentLlmCallResponseAgentPagedListResponse

Field	Type	Required
`data`	`AgentLlmCallResponse[] \| null`	Optional
`data[].id`	`string \| null`	Optional
`data[].conversationId`	`string \| null`	Optional
`data[].externalUserId`	`string \| null`	Optional
`data[].externalUserDisplayName`	`string \| null`	Optional
`data[].provider`	`string \| null`	Optional
`data[].usageKind`	`string \| null`	Optional
`data[].model`	`string \| null`	Optional
`data[].inputTokens`	`integer(int32)`	Optional
`data[].outputTokens`	`integer(int32)`	Optional
`data[].cachedInputTokens`	`integer(int32)`	Optional
`data[].inputAudioTokens`	`integer(int32)`	Optional
`data[].outputAudioTokens`	`integer(int32)`	Optional
`data[].inputAudioDurationMs`	`integer(int32)`	Optional
`data[].totalTokens`	`integer(int32)`	Optional
`data[].toolCallCount`	`integer(int32)`	Optional
`data[].durationMs`	`integer(int32)`	Optional
`data[].estimatedCostUsd`	`number(double)`	Optional
`data[].success`	`boolean`	Optional
`data[].errorMessage`	`string \| null`	Optional
`data[].realtimeSessionId`	`string \| null`	Optional
`data[].calledAt`	`string(date-time)`	Optional
`pageSize`	`integer(int32)`	Optional
`nextCursor`	`string \| null`	Optional
`hasNextPage`	`boolean`	Optional

{
  "data": [
    {
      "id": "id_123",
      "conversationId": "id_123",
      "externalUserId": "id_123",
      "externalUserDisplayName": "Support API",
      "provider": "openai",
      "usageKind": "string",
      "model": "gpt-4.1-mini",
      "inputTokens": 1,
      "outputTokens": 1,
      "cachedInputTokens": 1,
      "inputAudioTokens": 1,
      "outputAudioTokens": 1,
      "inputAudioDurationMs": 1,
      "totalTokens": 1,
      "toolCallCount": 1,
      "durationMs": 1,
      "estimatedCostUsd": 100,
      "success": true,
      "errorMessage": "string",
      "realtimeSessionId": "id_123",
      "calledAt": "2026-05-29T18:20:11Z"
    }
  ],
  "pageSize": 1,
  "nextCursor": "string",
  "hasNextPage": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/embed-usageGet embedded-agent usage across the organization.Get embedded-agent usage across the organization.

Request bodynone

No request body.

Response body200EmbedUsageOverviewResponse

Field	Type	Required
`summary`	`EmbedUsageSummaryResponse`	Optional
`summary.monthlyBudgetUsd`	`number(double)`	Optional
`summary.currentMonthSpendUsd`	`number(double)`	Optional
`summary.remainingBudgetUsd`	`number(double)`	Optional
`summary.agentCount`	`integer(int32)`	Optional
`summary.activeUserCount`	`integer(int32)`	Optional
`summary.llmCallCount`	`integer(int32)`	Optional
`summary.totalInputTokens`	`integer(int32)`	Optional
`summary.totalOutputTokens`	`integer(int32)`	Optional
`summary.totalToolCalls`	`integer(int32)`	Optional
`agents`	`EmbedAgentUsageRowResponse[] \| null`	Optional
`agents[].agentId`	`string \| null`	Optional
`agents[].agentName`	`string \| null`	Optional
`agents[].monthlyBudgetUsd`	`number(double)`	Optional
`agents[].currentMonthSpendUsd`	`number(double)`	Optional
`agents[].remainingBudgetUsd`	`number(double)`	Optional
`agents[].trackedUserCount`	`integer(int32)`	Optional
`agents[].llmCallCount`	`integer(int32)`	Optional
`agents[].highestPressureUserId`	`string \| null`	Optional
`agents[].highestPressureUserDisplayName`	`string \| null`	Optional
`recentLlmCalls`	`AgentLlmCallResponse[] \| null`	Optional
`recentLlmCalls[].id`	`string \| null`	Optional
`recentLlmCalls[].conversationId`	`string \| null`	Optional
`recentLlmCalls[].externalUserId`	`string \| null`	Optional
`recentLlmCalls[].externalUserDisplayName`	`string \| null`	Optional
`recentLlmCalls[].provider`	`string \| null`	Optional
`recentLlmCalls[].usageKind`	`string \| null`	Optional
`recentLlmCalls[].model`	`string \| null`	Optional
`recentLlmCalls[].inputTokens`	`integer(int32)`	Optional
`recentLlmCalls[].outputTokens`	`integer(int32)`	Optional
`recentLlmCalls[].cachedInputTokens`	`integer(int32)`	Optional
`recentLlmCalls[].inputAudioTokens`	`integer(int32)`	Optional
`recentLlmCalls[].outputAudioTokens`	`integer(int32)`	Optional
`recentLlmCalls[].inputAudioDurationMs`	`integer(int32)`	Optional
`recentLlmCalls[].totalTokens`	`integer(int32)`	Optional
`recentLlmCalls[].toolCallCount`	`integer(int32)`	Optional
`recentLlmCalls[].durationMs`	`integer(int32)`	Optional
`recentLlmCalls[].estimatedCostUsd`	`number(double)`	Optional
`recentLlmCalls[].success`	`boolean`	Optional
`recentLlmCalls[].errorMessage`	`string \| null`	Optional
`recentLlmCalls[].realtimeSessionId`	`string \| null`	Optional
`recentLlmCalls[].calledAt`	`string(date-time)`	Optional

{
  "summary": {
    "monthlyBudgetUsd": 100,
    "currentMonthSpendUsd": 100,
    "remainingBudgetUsd": 100,
    "agentCount": 1,
    "activeUserCount": 1,
    "llmCallCount": 1,
    "totalInputTokens": 1,
    "totalOutputTokens": 1,
    "totalToolCalls": 1
  },
  "agents": [
    {
      "agentId": "agt_8Xv4nLm",
      "agentName": "Support API",
      "monthlyBudgetUsd": 100,
      "currentMonthSpendUsd": 100,
      "remainingBudgetUsd": 100,
      "trackedUserCount": 1,
      "llmCallCount": 1,
      "highestPressureUserId": "id_123",
      "highestPressureUserDisplayName": "Support API"
    }
  ],
  "recentLlmCalls": [
    {
      "id": "id_123",
      "conversationId": "id_123",
      "externalUserId": "id_123",
      "externalUserDisplayName": "Support API",
      "provider": "openai",
      "usageKind": "string",
      "model": "gpt-4.1-mini",
      "inputTokens": 1,
      "outputTokens": 1,
      "cachedInputTokens": 1,
      "inputAudioTokens": 1,
      "outputAudioTokens": 1,
      "inputAudioDurationMs": 1,
      "totalTokens": 1,
      "toolCallCount": 1,
      "durationMs": 1,
      "estimatedCostUsd": 100,
      "success": true,
      "errorMessage": "string",
      "realtimeSessionId": "id_123",
      "calledAt": "2026-05-29T18:20:11Z"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agents/{agentId}/conversationsList an agent's conversations.List an agent's conversations.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`cursor`	query	`string`	Optional	`-`
`pageSize`	query	`integer(int32)`	Optional	`20`
`externalUserId`	query	`string`	Optional	`-`

Response body200AgentConversationPageResponse

Field	Type	Required
`summary`	`AgentConversationListSummaryResponse`	Optional
`summary.totalConversations`	`integer(int32)`	Optional
`summary.trackedUsers`	`integer(int32)`	Optional
`summary.feedbackCount`	`integer(int32)`	Optional
`summary.negativeFeedbackCount`	`integer(int32)`	Optional
`summary.runtimeIssueCount`	`integer(int32)`	Optional
`data`	`AgentConversationSummaryResponse[] \| null`	Optional
`data[].id`	`string \| null`	Optional
`data[].agentId`	`string \| null`	Optional
`data[].agentName`	`string \| null`	Optional
`data[].externalUserId`	`string \| null`	Optional
`data[].totalTokensUsed`	`integer(int32)`	Optional
`data[].totalToolCalls`	`integer(int32)`	Optional
`data[].messageCount`	`integer(int32)`	Optional
`data[].errorCount`	`integer(int32)`	Optional
`data[].feedbackCount`	`integer(int32)`	Optional
`data[].negativeFeedbackCount`	`integer(int32)`	Optional
`data[].lastFeedbackAt`	`string(date-time) \| null`	Optional
`data[].lastMessageAt`	`string(date-time) \| null`	Optional
`data[].createdAt`	`string(date-time)`	Optional
`pageSize`	`integer(int32)`	Optional
`nextCursor`	`string \| null`	Optional
`hasNextPage`	`boolean`	Optional

{
  "summary": {
    "totalConversations": 1,
    "trackedUsers": 1,
    "feedbackCount": 1,
    "negativeFeedbackCount": 1,
    "runtimeIssueCount": 1
  },
  "data": [
    {
      "id": "id_123",
      "agentId": "agt_8Xv4nLm",
      "agentName": "Support API",
      "externalUserId": "id_123",
      "totalTokensUsed": 1,
      "totalToolCalls": 1,
      "messageCount": 1,
      "errorCount": 1,
      "feedbackCount": 1,
      "negativeFeedbackCount": 1,
      "lastFeedbackAt": "2026-05-29T18:20:11Z",
      "lastMessageAt": "2026-05-29T18:20:11Z",
      "createdAt": "2026-05-29T18:20:11Z"
    }
  ],
  "pageSize": 1,
  "nextCursor": "string",
  "hasNextPage": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agents/{agentId}/conversations/{conversationId}Get a conversation.Get a conversation.

Request bodynone

No request body.

Response body200AgentConversationDetailResponse

Field	Type	Required
`id`	`string \| null`	Optional
`agentId`	`string \| null`	Optional
`agentName`	`string \| null`	Optional
`externalUserId`	`string \| null`	Optional
`totalTokensUsed`	`integer(int32)`	Optional
`totalToolCalls`	`integer(int32)`	Optional
`messageCount`	`integer(int32)`	Optional
`errorCount`	`integer(int32)`	Optional
`feedbackCount`	`integer(int32)`	Optional
`negativeFeedbackCount`	`integer(int32)`	Optional
`lastFeedbackAt`	`string(date-time) \| null`	Optional
`lastMessageAt`	`string(date-time) \| null`	Optional
`createdAt`	`string(date-time)`	Optional
`messagesPage`	`ConversationMessagesPageResponse`	Optional
`messagesPage.conversationId`	`string \| null`	Optional
`messagesPage.messages`	`ConversationMessageReplayResponse[] \| null`	Optional
`messagesPage.messages[].id`	`string \| null`	Optional
`messagesPage.messages[].sequenceNumber`	`integer(int32)`	Optional
`messagesPage.messages[].role`	`string \| null`	Optional
`messagesPage.messages[].content`	`string \| null`	Optional
`messagesPage.messages[].createdAt`	`string(date-time)`	Optional
`messagesPage.messages[].toolName`	`string \| null`	Optional
`messagesPage.messages[].toolLabel`	`string \| null`	Optional
`messagesPage.messages[].toolCallId`	`string \| null`	Optional
`messagesPage.messages[].toolCallStatus`	`string \| null`	Optional
`messagesPage.messages[].toolCallDurationMs`	`integer(int32) \| null`	Optional
`messagesPage.messages[].toolArgumentsJson`	`string \| null`	Optional
`messagesPage.messages[].toolResultJson`	`string \| null`	Optional
`messagesPage.messages[].toolError`	`string \| null`	Optional
`messagesPage.messages[].errorCode`	`string \| null`	Optional
`messagesPage.messages[].metadataJson`	`string \| null`	Optional
`messagesPage.pageSize`	`integer(int32)`	Optional
`messagesPage.nextCursor`	`string \| null`	Optional
`messagesPage.hasNextPage`	`boolean`	Optional
`feedback`	`ConversationFeedbackResponse[] \| null`	Optional
`feedback[].id`	`string \| null`	Optional
`feedback[].conversationId`	`string \| null`	Optional
`feedback[].sentiment`	`string \| null`	Optional
`feedback[].comment`	`string \| null`	Optional
`feedback[].source`	`string \| null`	Optional
`feedback[].toolCallId`	`string \| null`	Optional
`feedback[].conversationMessageId`	`string \| null`	Optional
`feedback[].metadataJson`	`string \| null`	Optional
`feedback[].createdAt`	`string(date-time)`	Optional
`usageLogs`	`ConversationUsageLogResponse[] \| null`	Optional
`usageLogs[].id`	`string \| null`	Optional
`usageLogs[].provider`	`string \| null`	Optional
`usageLogs[].usageKind`	`string \| null`	Optional
`usageLogs[].model`	`string \| null`	Optional
`usageLogs[].inputTokens`	`integer(int32)`	Optional
`usageLogs[].outputTokens`	`integer(int32)`	Optional
`usageLogs[].cachedInputTokens`	`integer(int32)`	Optional
`usageLogs[].inputAudioTokens`	`integer(int32)`	Optional
`usageLogs[].outputAudioTokens`	`integer(int32)`	Optional
`usageLogs[].inputAudioDurationMs`	`integer(int32)`	Optional
`usageLogs[].toolCallCount`	`integer(int32)`	Optional
`usageLogs[].durationMs`	`integer(int32)`	Optional
`usageLogs[].success`	`boolean`	Optional
`usageLogs[].errorMessage`	`string \| null`	Optional
`usageLogs[].realtimeSessionId`	`string \| null`	Optional
`usageLogs[].calledAt`	`string(date-time)`	Optional

{
  "id": "id_123",
  "agentId": "agt_8Xv4nLm",
  "agentName": "Support API",
  "externalUserId": "id_123",
  "totalTokensUsed": 1,
  "totalToolCalls": 1,
  "messageCount": 1,
  "errorCount": 1,
  "feedbackCount": 1,
  "negativeFeedbackCount": 1,
  "lastFeedbackAt": "2026-05-29T18:20:11Z",
  "lastMessageAt": "2026-05-29T18:20:11Z",
  "createdAt": "2026-05-29T18:20:11Z",
  "messagesPage": {
    "conversationId": "id_123",
    "messages": [
      {
        "id": "id_123",
        "sequenceNumber": 1,
        "role": "developer",
        "content": "string",
        "createdAt": "2026-05-29T18:20:11Z",
        "toolName": "Support API",
        "toolLabel": "string",
        "toolCallId": "id_123",
        "toolCallStatus": "active",
        "toolCallDurationMs": 1,
        "toolArgumentsJson": "string",
        "toolResultJson": "string",
        "toolError": "string",
        "errorCode": "string",
        "metadataJson": "string"
      }
    ],
    "pageSize": 1,
    "nextCursor": "string",
    "hasNextPage": true
  },
  "feedback": [
    {
      "id": "id_123",
      "conversationId": "id_123",
      "sentiment": "string",
      "comment": "string",
      "source": "string",
      "toolCallId": "id_123",
      "conversationMessageId": "id_123",
      "metadataJson": "string",
      "createdAt": "2026-05-29T18:20:11Z"
    }
  ],
  "usageLogs": [
    {
      "id": "id_123",
      "provider": "openai",
      "usageKind": "string",
      "model": "gpt-4.1-mini",
      "inputTokens": 1,
      "outputTokens": 1,
      "cachedInputTokens": 1,
      "inputAudioTokens": 1,
      "outputAudioTokens": 1,
      "inputAudioDurationMs": 1,
      "toolCallCount": 1,
      "durationMs": 1,
      "success": true,
      "errorMessage": "string",
      "realtimeSessionId": "id_123",
      "calledAt": "2026-05-29T18:20:11Z"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agents/{agentId}/conversations/{conversationId}/messagesGet a conversation's messages.Get a conversation's messages.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`cursor`	query	`string`	Optional	`-`
`pageSize`	query	`integer(int32)`	Optional	`100`

Response body200ConversationMessagesPageResponse

Field	Type	Required
`conversationId`	`string \| null`	Optional
`messages`	`ConversationMessageReplayResponse[] \| null`	Optional
`messages[].id`	`string \| null`	Optional
`messages[].sequenceNumber`	`integer(int32)`	Optional
`messages[].role`	`string \| null`	Optional
`messages[].content`	`string \| null`	Optional
`messages[].createdAt`	`string(date-time)`	Optional
`messages[].toolName`	`string \| null`	Optional
`messages[].toolLabel`	`string \| null`	Optional
`messages[].toolCallId`	`string \| null`	Optional
`messages[].toolCallStatus`	`string \| null`	Optional
`messages[].toolCallDurationMs`	`integer(int32) \| null`	Optional
`messages[].toolArgumentsJson`	`string \| null`	Optional
`messages[].toolResultJson`	`string \| null`	Optional
`messages[].toolError`	`string \| null`	Optional
`messages[].errorCode`	`string \| null`	Optional
`messages[].metadataJson`	`string \| null`	Optional
`pageSize`	`integer(int32)`	Optional
`nextCursor`	`string \| null`	Optional
`hasNextPage`	`boolean`	Optional

{
  "conversationId": "id_123",
  "messages": [
    {
      "id": "id_123",
      "sequenceNumber": 1,
      "role": "developer",
      "content": "string",
      "createdAt": "2026-05-29T18:20:11Z",
      "toolName": "Support API",
      "toolLabel": "string",
      "toolCallId": "id_123",
      "toolCallStatus": "active",
      "toolCallDurationMs": 1,
      "toolArgumentsJson": "string",
      "toolResultJson": "string",
      "toolError": "string",
      "errorCode": "string",
      "metadataJson": "string"
    }
  ],
  "pageSize": 1,
  "nextCursor": "string",
  "hasNextPage": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Budgets#

Cap spend at the agent level and per embedded user.

MethodEndpointDescriptionCopy

PATCH/api/v1/organizations/{orgId}/agents/{agentId}/budgetSet the agent's default budget policy.Set the agent's default budget policy.

Request bodyAgentBudgetPolicyUpdateRequest · application/json

Field	Type	Required
`monthlyBudgetUsd`	`number(double)`	Required
`defaultUserBudgetUsd`	`number(double) \| null`	Optional
`defaultUserMonthlyBudgetUsd`	`number(double) \| null`	Optional
`anonymousMonthlyBudgetUsd`	`number(double) \| null`	Optional
`currency`	`string \| null`	Optional
`enabled`	`boolean`	Optional

{
  "monthlyBudgetUsd": 100,
  "defaultUserBudgetUsd": 100,
  "defaultUserMonthlyBudgetUsd": 100,
  "anonymousMonthlyBudgetUsd": 100,
  "currency": "USD",
  "enabled": true
}

Response body200AgentBudgetSummaryResponse

Field	Type	Required
`monthlyBudgetUsd`	`number(double)`	Optional
`defaultUserMonthlyBudgetUsd`	`number(double) \| null`	Optional
`anonymousMonthlyBudgetUsd`	`number(double) \| null`	Optional
`currency`	`string \| null`	Optional
`allocationMode`	`string \| null`	Optional
`resetDayOfMonthUtc`	`integer(int32)`	Optional
`currentMonthSpendUsd`	`number(double)`	Optional
`remainingBudgetUsd`	`number(double)`	Optional
`trackedUserCount`	`integer(int32)`	Optional
`assignedUserCount`	`integer(int32)`	Optional
`assignedBudgetUsd`	`number(double)`	Optional
`enabled`	`boolean`	Optional

{
  "monthlyBudgetUsd": 100,
  "defaultUserMonthlyBudgetUsd": 100,
  "anonymousMonthlyBudgetUsd": 100,
  "currency": "USD",
  "allocationMode": "string",
  "resetDayOfMonthUtc": 1,
  "currentMonthSpendUsd": 100,
  "remainingBudgetUsd": 100,
  "trackedUserCount": 1,
  "assignedUserCount": 1,
  "assignedBudgetUsd": 100,
  "enabled": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PUT/api/v1/organizations/{orgId}/agents/{agentId}/external-users/{externalUserId}/budgetSet one embedded user's monthly cap.Set one embedded user's monthly cap.

Request bodyAgentExternalUserBudgetUpsertRequest · application/json

Field	Type	Required
`monthlyBudgetUsd`	`number(double)`	Required

{
  "monthlyBudgetUsd": 100
}

Response body200AgentExternalUserBudgetResponse

Field	Type	Required
`externalUserId`	`string \| null`	Optional
`displayName`	`string \| null`	Optional
`email`	`string \| null`	Optional
`assignedBudgetUsd`	`number(double) \| null`	Optional
`effectiveBudgetUsd`	`number(double) \| null`	Optional
`budgetSource`	`string \| null`	Optional
`currentMonthSpendUsd`	`number(double)`	Optional
`remainingBudgetUsd`	`number(double)`	Optional
`status`	`string \| null`	Optional
`windowStartUtc`	`string(date-time)`	Optional
`windowEndUtc`	`string(date-time)`	Optional

{
  "externalUserId": "id_123",
  "displayName": "Support API",
  "email": "teammate@example.com",
  "assignedBudgetUsd": 100,
  "effectiveBudgetUsd": 100,
  "budgetSource": "string",
  "currentMonthSpendUsd": 100,
  "remainingBudgetUsd": 100,
  "status": "active",
  "windowStartUtc": "2026-05-29T18:20:11Z",
  "windowEndUtc": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agents/{agentId}/external-users/{externalUserId}/budgetGet one embedded user's budget.Get one embedded user's budget.

Request bodynone

No request body.

Response body200AgentExternalUserBudgetResponse

Field	Type	Required
`externalUserId`	`string \| null`	Optional
`displayName`	`string \| null`	Optional
`email`	`string \| null`	Optional
`assignedBudgetUsd`	`number(double) \| null`	Optional
`effectiveBudgetUsd`	`number(double) \| null`	Optional
`budgetSource`	`string \| null`	Optional
`currentMonthSpendUsd`	`number(double)`	Optional
`remainingBudgetUsd`	`number(double)`	Optional
`status`	`string \| null`	Optional
`windowStartUtc`	`string(date-time)`	Optional
`windowEndUtc`	`string(date-time)`	Optional

{
  "externalUserId": "id_123",
  "displayName": "Support API",
  "email": "teammate@example.com",
  "assignedBudgetUsd": 100,
  "effectiveBudgetUsd": 100,
  "budgetSource": "string",
  "currentMonthSpendUsd": 100,
  "remainingBudgetUsd": 100,
  "status": "active",
  "windowStartUtc": "2026-05-29T18:20:11Z",
  "windowEndUtc": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}/agents/{agentId}/external-users/{externalUserId}/budgetRemove an embedded user's budget override.Remove an embedded user's budget override.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Embed keys and verified domains#

MethodEndpointDescriptionCopy

GET/api/v1/organizations/{orgId}/agents/{agentId}/embed-keysList embed keys.List embed keys.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].agentId`	`string \| null`	Optional
`[].displayName`	`string \| null`	Optional
`[].description`	`string \| null`	Optional
`[].clientId`	`string \| null`	Optional
`[].fullKey`	`string \| null`	Optional
`[].status`	`string \| null`	Optional
`[].allowedOrigins`	`string \| null`	Optional
`[].allowAnonymous`	`boolean`	Optional
`[].lastUsedAt`	`string(date-time) \| null`	Optional
`[].revokedAt`	`string(date-time) \| null`	Optional
`[].createdOn`	`string(date-time)`	Optional

[
  {
    "id": "id_123",
    "agentId": "agt_8Xv4nLm",
    "displayName": "Support API",
    "description": "Routes support ticket operations to MCP clients.",
    "clientId": "id_123",
    "fullKey": "string",
    "status": "active",
    "allowedOrigins": "https://api.example.com",
    "allowAnonymous": true,
    "lastUsedAt": "2026-05-29T18:20:11Z",
    "revokedAt": "2026-05-29T18:20:11Z",
    "createdOn": "2026-05-29T18:20:11Z"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/agents/{agentId}/embed-keysCreate an embed key. The public key is returned once.Create an embed key. The public key is returned once.

Request bodyCreateAgentEmbedKeyRequest · application/json

Field	Type	Required
`displayName`	`string`	Required
`description`	`string \| null`	Optional
`allowedOrigins`	`string \| null`	Optional
`allowAnonymous`	`boolean`	Optional

{
  "displayName": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "allowedOrigins": "https://api.example.com",
  "allowAnonymous": true
}

Response body201CreateAgentEmbedKeyResponse

Field	Type	Required
`key`	`AgentEmbedKeyResponse`	Optional
`key.id`	`string \| null`	Optional
`key.agentId`	`string \| null`	Optional
`key.displayName`	`string \| null`	Optional
`key.description`	`string \| null`	Optional
`key.clientId`	`string \| null`	Optional
`key.fullKey`	`string \| null`	Optional
`key.status`	`string \| null`	Optional
`key.allowedOrigins`	`string \| null`	Optional
`key.allowAnonymous`	`boolean`	Optional
`key.lastUsedAt`	`string(date-time) \| null`	Optional
`key.revokedAt`	`string(date-time) \| null`	Optional
`key.createdOn`	`string(date-time)`	Optional

{
  "key": {
    "id": "id_123",
    "agentId": "agt_8Xv4nLm",
    "displayName": "Support API",
    "description": "Routes support ticket operations to MCP clients.",
    "clientId": "id_123",
    "fullKey": "string",
    "status": "active",
    "allowedOrigins": "https://api.example.com",
    "allowAnonymous": true,
    "lastUsedAt": "2026-05-29T18:20:11Z",
    "revokedAt": "2026-05-29T18:20:11Z",
    "createdOn": "2026-05-29T18:20:11Z"
  }
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

DELETE/api/v1/organizations/{orgId}/agents/{agentId}/embed-keys/{keyId}Revoke an embed key.Revoke an embed key.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/agents/{agentId}/verified-domainsList verified embed domains.List verified embed domains.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].hostName`	`string \| null`	Optional
`[].status`	`string \| null`	Optional
`[].ownershipRecord`	`AgentVerifiedDomainDnsRecordResponse`	Optional
`[].ownershipRecord.type`	`string \| null`	Optional
`[].ownershipRecord.name`	`string \| null`	Optional
`[].ownershipRecord.value`	`string \| null`	Optional
`[].lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`[].lastError`	`string \| null`	Optional
`[].createdOn`	`string(date-time)`	Optional

[
  {
    "id": "id_123",
    "hostName": "app.example.com",
    "status": "active",
    "ownershipRecord": {
      "type": "string",
      "name": "Support API",
      "value": "string"
    },
    "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
    "lastError": "string",
    "createdOn": "2026-05-29T18:20:11Z"
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/agents/{agentId}/verified-domainsAdd a domain to verify for embedding.Add a domain to verify for embedding.

Request bodyUpsertAgentVerifiedDomainRequest · application/json

Field	Type	Required
`hostName`	`string`	Required

{
  "hostName": "app.example.com"
}

Response body200AgentVerifiedDomainResponse

Field	Type	Required
`id`	`string \| null`	Optional
`hostName`	`string \| null`	Optional
`status`	`string \| null`	Optional
`ownershipRecord`	`AgentVerifiedDomainDnsRecordResponse`	Optional
`ownershipRecord.type`	`string \| null`	Optional
`ownershipRecord.name`	`string \| null`	Optional
`ownershipRecord.value`	`string \| null`	Optional
`lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`lastError`	`string \| null`	Optional
`createdOn`	`string(date-time)`	Optional

{
  "id": "id_123",
  "hostName": "app.example.com",
  "status": "active",
  "ownershipRecord": {
    "type": "string",
    "name": "Support API",
    "value": "string"
  },
  "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
  "lastError": "string",
  "createdOn": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/agents/{agentId}/verified-domains/{domainId}/confirmConfirm a domain after the DNS record resolves.Confirm a domain after the DNS record resolves.

Request bodynone

No request body.

Response body200AgentVerifiedDomainResponse

Field	Type	Required
`id`	`string \| null`	Optional
`hostName`	`string \| null`	Optional
`status`	`string \| null`	Optional
`ownershipRecord`	`AgentVerifiedDomainDnsRecordResponse`	Optional
`ownershipRecord.type`	`string \| null`	Optional
`ownershipRecord.name`	`string \| null`	Optional
`ownershipRecord.value`	`string \| null`	Optional
`lastCheckedAtUtc`	`string(date-time) \| null`	Optional
`lastError`	`string \| null`	Optional
`createdOn`	`string(date-time)`	Optional

{
  "id": "id_123",
  "hostName": "app.example.com",
  "status": "active",
  "ownershipRecord": {
    "type": "string",
    "name": "Support API",
    "value": "string"
  },
  "lastCheckedAtUtc": "2026-05-29T18:20:11Z",
  "lastError": "string",
  "createdOn": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Billing, credits, and hosting#

AI credit balances, hosted runtime plans, tool-call credit packs, Stripe checkout, and billing portal access.

MethodEndpointDescriptionCopy

GET/api/v1/organizations/{orgId}/ai-credits/summaryGet the AI-credit balance.Get the AI-credit balance.

Request bodynone

No request body.

Response body200AiCreditSummary

Field	Type	Required
`organizationId`	`string \| null`	Optional
`balanceUsd`	`number(double)`	Optional
`currentMonthSpendUsd`	`number(double)`	Optional
`creditsExhausted`	`boolean`	Optional
`topUpOptionsUsd`	`number(double)[] \| null`	Optional
`recentEntries`	`AiCreditLedgerEntrySummary[] \| null`	Optional
`recentEntries[].id`	`string \| null`	Optional
`recentEntries[].amountUsd`	`number(double)`	Optional
`recentEntries[].balanceAfterUsd`	`number(double) \| null`	Optional
`recentEntries[].entryKind`	`string \| null`	Optional
`recentEntries[].description`	`string \| null`	Optional
`recentEntries[].createdOn`	`string(date-time)`	Optional
`recentEntries[].expiresAt`	`string(date-time) \| null`	Optional

{
  "organizationId": "org_7Hf3kQ2",
  "balanceUsd": 100,
  "currentMonthSpendUsd": 100,
  "creditsExhausted": true,
  "topUpOptionsUsd": [
    100
  ],
  "recentEntries": [
    {
      "id": "id_123",
      "amountUsd": 100,
      "balanceAfterUsd": 100,
      "entryKind": "string",
      "description": "Routes support ticket operations to MCP clients.",
      "createdOn": "2026-05-29T18:20:11Z",
      "expiresAt": "2026-05-29T18:20:11Z"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/ai-credits/ledgerGet the AI-credit ledger.Get the AI-credit ledger.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`category`	query	`string`	Optional	`purchases`
`cursor`	query	`string`	Optional	`-`
`pageSize`	query	`integer(int32)`	Optional	`20`
`prioritizeEntryId`	query	`string`	Optional	`-`

Response body200AiCreditLedgerPageResponse

Field	Type	Required
`data`	`AiCreditLedgerEntrySummary[] \| null`	Optional
`data[].id`	`string \| null`	Optional
`data[].amountUsd`	`number(double)`	Optional
`data[].balanceAfterUsd`	`number(double) \| null`	Optional
`data[].entryKind`	`string \| null`	Optional
`data[].description`	`string \| null`	Optional
`data[].createdOn`	`string(date-time)`	Optional
`data[].expiresAt`	`string(date-time) \| null`	Optional
`pageSize`	`integer(int32)`	Optional
`nextCursor`	`string \| null`	Optional
`hasNextPage`	`boolean`	Optional

{
  "data": [
    {
      "id": "id_123",
      "amountUsd": 100,
      "balanceAfterUsd": 100,
      "entryKind": "string",
      "description": "Routes support ticket operations to MCP clients.",
      "createdOn": "2026-05-29T18:20:11Z",
      "expiresAt": "2026-05-29T18:20:11Z"
    }
  ],
  "pageSize": 1,
  "nextCursor": "string",
  "hasNextPage": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/ai-credits/checkout-session/{sessionId}/ledger-entry-idGet the ledger entry linked to an AI-credit checkout.Get the ledger entry linked to an AI-credit checkout.

Request bodynone

No request body.

Response body200LedgerEntryIdResponse

Field	Type	Required
`id`	`string`	Required

{
  "id": "id_123"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/ai-credits/checkout-sessionStart an AI-credit checkout.Start an AI-credit checkout.

Request bodyAiCreditCheckoutSessionRequest · application/json

Field	Type	Required
`amountUsd`	`number(double)`	Required

{
  "amountUsd": 100
}

Response body200AiCreditCheckoutSessionResult

Field	Type	Required
`provider`	`string \| null`	Optional
`sessionId`	`string \| null`	Optional
`url`	`string \| null`	Optional
`amountUsd`	`number(double)`	Optional
`expiresAt`	`string(date-time) \| null`	Optional

{
  "provider": "openai",
  "sessionId": "id_123",
  "url": "https://api.example.com",
  "amountUsd": 100,
  "expiresAt": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/ai-credits/checkout-session/{sessionId}/syncReconcile an AI-credit checkout session.Reconcile an AI-credit checkout session.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-hosting/usageGet hosted-runtime usage and plan limits.Get hosted-runtime usage and plan limits.

Request bodynone

No request body.

Response body200McpHostingUsageSummary

Field	Type	Required
`organizationId`	`string \| null`	Optional
`planKey`	`string \| null`	Optional
`planName`	`string \| null`	Optional
`planOrStatus`	`string \| null`	Optional
`subscriptionStatus`	`string \| null`	Optional
`billingCollectionMethod`	`string \| null`	Optional
`deploymentMode`	`string \| null`	Optional
`contractLabel`	`string \| null`	Optional
`invoiceAmountCents`	`integer(int32) \| null`	Optional
`invoiceTermMonths`	`integer(int32) \| null`	Optional
`invoiceLineItemDescription`	`string \| null`	Optional
`invoiceNetTermsDays`	`integer(int32) \| null`	Optional
`invoiceMonthsRemaining`	`integer(int32) \| null`	Optional
`cancelAtPeriodEnd`	`boolean`	Optional
`currentPeriodEnd`	`string(date-time) \| null`	Optional
`pendingPlanKey`	`string \| null`	Optional
`pendingPlanName`	`string \| null`	Optional
`pendingPlanEffectiveAt`	`string(date-time) \| null`	Optional
`isTrial`	`boolean`	Optional
`trialEndsAt`	`string(date-time) \| null`	Optional
`trialDaysLeft`	`integer(int32)`	Optional
`billingPeriodStart`	`string(date-time)`	Optional
`billingPeriodEnd`	`string(date-time)`	Optional
`monthlyPlatformFeeCents`	`integer(int32)`	Optional
`hostedServersCurrent`	`integer(int32)`	Optional
`hostedServersLimit`	`integer(int32)`	Optional
`hostedServersUnlimited`	`boolean`	Optional
`toolCallsThisMonth`	`integer(int64)`	Optional
`includedToolCalls`	`integer(int64)`	Optional
`includedToolCallsRemaining`	`integer(int64)`	Optional
`purchasedToolCallCreditsBalance`	`integer(int64)`	Optional
`purchasedToolCallCreditsUsedThisMonth`	`integer(int64)`	Optional
`toolCallCreditUnitSize`	`integer(int32)`	Optional
`toolCallCreditUnitCents`	`integer(int32)`	Optional
`toolCallCreditPackOptions`	`McpToolCallCreditPackOption[] \| null`	Optional
`toolCallCreditPackOptions[].calls`	`integer(int64)`	Optional
`toolCallCreditPackOptions[].priceCents`	`integer(int32)`	Optional
`maxToolCallDurationSeconds`	`integer(int32)`	Optional
`maxRequestBodyBytes`	`integer(int64)`	Optional
`maxResponseBodyBytes`	`integer(int64)`	Optional
`regionsPerServerLimit`	`integer(int32)`	Optional
`scaleToZeroDefault`	`boolean`	Optional
`isSuspended`	`boolean`	Optional

{
  "organizationId": "org_7Hf3kQ2",
  "planKey": "string",
  "planName": "Support API",
  "planOrStatus": "active",
  "subscriptionStatus": "active",
  "billingCollectionMethod": "POST",
  "deploymentMode": "string",
  "contractLabel": "string",
  "invoiceAmountCents": 2500,
  "invoiceTermMonths": 1,
  "invoiceLineItemDescription": "Routes support ticket operations to MCP clients.",
  "invoiceNetTermsDays": 1,
  "invoiceMonthsRemaining": 1,
  "cancelAtPeriodEnd": true,
  "currentPeriodEnd": "2026-05-29T18:20:11Z",
  "pendingPlanKey": "string",
  "pendingPlanName": "Support API",
  "pendingPlanEffectiveAt": "2026-05-29T18:20:11Z",
  "isTrial": true,
  "trialEndsAt": "2026-05-29T18:20:11Z",
  "trialDaysLeft": 1,
  "billingPeriodStart": "2026-05-29T18:20:11Z",
  "billingPeriodEnd": "2026-05-29T18:20:11Z",
  "monthlyPlatformFeeCents": 2500,
  "hostedServersCurrent": 1,
  "hostedServersLimit": 1,
  "hostedServersUnlimited": true,
  "toolCallsThisMonth": 1,
  "includedToolCalls": 1,
  "includedToolCallsRemaining": 1,
  "purchasedToolCallCreditsBalance": 1,
  "purchasedToolCallCreditsUsedThisMonth": 1,
  "toolCallCreditUnitSize": 1,
  "toolCallCreditUnitCents": 2500,
  "toolCallCreditPackOptions": [
    {
      "calls": 1,
      "priceCents": 2500
    }
  ],
  "maxToolCallDurationSeconds": 1,
  "maxRequestBodyBytes": 1048576,
  "maxResponseBodyBytes": 1048576,
  "regionsPerServerLimit": 1,
  "scaleToZeroDefault": true,
  "isSuspended": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-hosting/tool-call-credits/ledgerGet the tool-call credit ledger.Get the tool-call credit ledger.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`category`	query	`string`	Optional	`purchases`
`cursor`	query	`string`	Optional	`-`
`pageSize`	query	`integer(int32)`	Optional	`20`
`prioritizeEntryId`	query	`string`	Optional	`-`

Response body200McpToolCallCreditLedgerPageResponse

Field	Type	Required
`data`	`McpToolCallCreditLedgerEntrySummary[] \| null`	Optional
`data[].id`	`string \| null`	Optional
`data[].amountCalls`	`integer(int64)`	Optional
`data[].balanceAfterCalls`	`integer(int64) \| null`	Optional
`data[].entryKind`	`string \| null`	Optional
`data[].description`	`string \| null`	Optional
`data[].createdOn`	`string(date-time)`	Optional
`pageSize`	`integer(int32)`	Optional
`nextCursor`	`string \| null`	Optional
`hasNextPage`	`boolean`	Optional

{
  "data": [
    {
      "id": "id_123",
      "amountCalls": 1,
      "balanceAfterCalls": 1,
      "entryKind": "string",
      "description": "Routes support ticket operations to MCP clients.",
      "createdOn": "2026-05-29T18:20:11Z"
    }
  ],
  "pageSize": 1,
  "nextCursor": "string",
  "hasNextPage": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/mcp-hosting/tool-call-credits/checkout-session/{sessionId}/ledger-entry-idGet the ledger entry linked to a tool-call credit checkout.Get the ledger entry linked to a tool-call credit checkout.

Request bodynone

No request body.

Response body200LedgerEntryIdResponse

Field	Type	Required
`id`	`string`	Required

{
  "id": "id_123"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-hosting/billing/checkout-sessionStart a hosting plan checkout.Start a hosting plan checkout.

Request bodyMcpHostingCheckoutSessionRequest · application/json

Field	Type	Required
`planKey`	`string`	Required

{
  "planKey": "string"
}

Response body200McpHostingCheckoutSessionResult

Field	Type	Required
`provider`	`string \| null`	Optional
`sessionId`	`string \| null`	Optional
`url`	`string \| null`	Optional
`expiresAt`	`string(date-time) \| null`	Optional

{
  "provider": "openai",
  "sessionId": "id_123",
  "url": "https://api.example.com",
  "expiresAt": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-hosting/billing/checkout-session/{sessionId}/syncReconcile a hosting checkout session.Reconcile a hosting checkout session.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-hosting/billing/subscription/syncReconcile the current hosting subscription.Reconcile the current hosting subscription.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-hosting/tool-call-credits/checkout-sessionStart a tool-call credit checkout.Start a tool-call credit checkout.

Request bodyMcpToolCallCreditCheckoutSessionRequest · application/json

Field	Type	Required
`calls`	`integer(int64)`	Required

{
  "calls": 1
}

Response body200McpToolCallCreditCheckoutSessionResult

Field	Type	Required
`provider`	`string \| null`	Optional
`sessionId`	`string \| null`	Optional
`url`	`string \| null`	Optional
`calls`	`integer(int64)`	Optional
`amountCents`	`integer(int32)`	Optional
`expiresAt`	`string(date-time) \| null`	Optional

{
  "provider": "openai",
  "sessionId": "id_123",
  "url": "https://api.example.com",
  "calls": 1,
  "amountCents": 2500,
  "expiresAt": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/mcp-hosting/tool-call-credits/checkout-session/{sessionId}/syncReconcile a tool-call credit checkout session.Reconcile a tool-call credit checkout session.

Request bodynone

No request body.

Response body204

No JSON response body.

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/organizations/{orgId}/billing/portal-sessionOpen the billing portal.Open the billing portal.

Request bodynone

No request body.

Response body200McpBillingPortalSessionResult

Field	Type	Required
`provider`	`string \| null`	Optional
`sessionId`	`string \| null`	Optional
`url`	`string \| null`	Optional
`expiresAt`	`string(date-time) \| null`	Optional

{
  "provider": "openai",
  "sessionId": "id_123",
  "url": "https://api.example.com",
  "expiresAt": "2026-05-29T18:20:11Z"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Host environments#

Inspect hosted runtime environment, region, and routing metadata.

MethodEndpointDescriptionCopy

GET/api/v1/organizations/{orgId}/host/environmentGet the default Host environment.Get the default Host environment.

Request bodynone

No request body.

Response body200HostEnvironmentResponse

Field	Type	Required
`environment`	`string`	Required

{
  "environment": "prod"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/host/environments/{environment}/regionsList Host regions for an environment.List Host regions for an environment.

Request bodynone

No request body.

Response body200

Field	Type	Required
`[].id`	`string \| null`	Optional
`[].environment`	`string \| null`	Optional
`[].region`	`string \| null`	Optional
`[].displayName`	`string \| null`	Optional
`[].azureLocation`	`string \| null`	Optional
`[].routingMode`	`string \| null`	Optional
`[].isEnabled`	`boolean`	Optional
`[].isDefault`	`boolean`	Optional
`[].sortOrder`	`integer(int32)`	Optional

[
  {
    "id": "id_123",
    "environment": "prod",
    "region": "westus3",
    "displayName": "Support API",
    "azureLocation": "string",
    "routingMode": "string",
    "isEnabled": true,
    "isDefault": true,
    "sortOrder": 1
  }
]

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/organizations/{orgId}/host/environments/{environment}/routingGet Host routing configuration for an environment.Get Host routing configuration for an environment.

Request bodynone

No request body.

Response body200HostRoutingResponse

Field	Type	Required
`environment`	`string \| null`	Optional
`routingMode`	`string \| null`	Optional
`domainRoot`	`string \| null`	Optional
`usesFrontDoor`	`boolean`	Optional
`frontDoorProfileName`	`string \| null`	Optional
`frontDoorEndpointName`	`string \| null`	Optional

{
  "environment": "prod",
  "routingMode": "string",
  "domainRoot": "string",
  "usesFrontDoor": true,
  "frontDoorProfileName": "Support API",
  "frontDoorEndpointName": "Support API"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Public guides and status#

Read-only public metadata for MCP install guides, app guides, and status surfaces.

MethodEndpointDescriptionCopy

GET/api/v1/mcp-server-guides/{serverSlug}Get a public install guide for a server slug.Get a public install guide for a server slug.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional	`-`
`includeDoctor`	query	`boolean`	Optional	`true`

Response body200McpInstallGuideResponse

Field	Type	Required
`serverSlug`	`string \| null`	Optional
`publicSlug`	`string \| null`	Optional
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`organizationName`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`status`	`string \| null`	Optional
`kind`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`guideUrl`	`string \| null`	Optional
`mcpUrl`	`string \| null`	Optional
`reservedMcpUrl`	`string \| null`	Optional
`installGuideEnabled`	`boolean`	Optional
`organizationPublicGuidesEnabled`	`boolean`	Optional
`auth`	`McpInstallGuideAuthResponse`	Optional
`auth.type`	`string \| null`	Optional
`auth.hasGateway`	`boolean`	Optional
`auth.summary`	`string \| null`	Optional
`auth.protectedResourceMetadataUrl`	`string \| null`	Optional
`auth.authorizationServerUrl`	`string \| null`	Optional
`auth.authorizationServerMetadataUrl`	`string \| null`	Optional
`auth.authorizationEndpoint`	`string \| null`	Optional
`auth.tokenEndpoint`	`string \| null`	Optional
`auth.registrationEndpoint`	`string \| null`	Optional
`auth.resource`	`string \| null`	Optional
`auth.scopes`	`string[] \| null`	Optional
`tools`	`McpInstallGuideToolSummaryResponse`	Optional
`tools.totalCount`	`integer(int32)`	Optional
`tools.enabledCount`	`integer(int32)`	Optional
`tools.featuredTools`	`McpInstallGuideToolResponse[] \| null`	Optional
`tools.featuredTools[].id`	`string \| null`	Optional
`tools.featuredTools[].displayName`	`string \| null`	Optional
`tools.featuredTools[].description`	`string \| null`	Optional
`tools.featuredTools[].httpMethod`	`string \| null`	Optional
`tools.featuredTools[].httpPath`	`string \| null`	Optional
`tools.featuredTools[].isEnabled`	`boolean`	Optional
`readiness`	`McpInstallGuideReadinessResponse`	Optional
`readiness.deploymentStatus`	`string \| null`	Optional
`readiness.catalogStatus`	`string \| null`	Optional
`readiness.catalogCheckedAt`	`string(date-time) \| null`	Optional
`readiness.catalogError`	`string \| null`	Optional
`readiness.healthyRegionCount`	`integer(int32)`	Optional
`readiness.configuredRegionCount`	`integer(int32)`	Optional
`readiness.doctor`	`DeploymentDoctorResponse`	Optional
`readiness.doctor.serverId`	`string \| null`	Optional
`readiness.doctor.publicUrl`	`string \| null`	Optional
`readiness.doctor.checks`	`DeploymentDoctorCheckResponse[] \| null`	Optional
`sourceType`	`string \| null`	Optional
`providerDisplayName`	`string \| null`	Optional
`shortDescription`	`string \| null`	Optional
`longDescription`	`string \| null`	Optional
`logoUrl`	`string \| null`	Optional
`logoAltText`	`string \| null`	Optional
`isListedInLibrary`	`boolean`	Optional
`isIndexable`	`boolean`	Optional
`canonicalUrl`	`string \| null`	Optional
`category`	`string \| null`	Optional
`tags`	`string[] \| null`	Optional
`supportedClients`	`string[] \| null`	Optional
`setupSteps`	`McpAppGuideSetupStepResponse[] \| null`	Optional
`setupSteps[].clientKey`	`string \| null`	Optional
`setupSteps[].clientName`	`string \| null`	Optional
`setupSteps[].stepNumber`	`integer(int32)`	Optional
`setupSteps[].text`	`string \| null`	Optional
`faq`	`McpAppGuideFaqResponse[] \| null`	Optional
`faq[].question`	`string \| null`	Optional
`faq[].answer`	`string \| null`	Optional
`docsUrl`	`string \| null`	Optional
`authType`	`string \| null`	Optional
`authSummary`	`string \| null`	Optional
`seoTitle`	`string \| null`	Optional
`seoDescription`	`string \| null`	Optional

{
  "serverSlug": "support-api",
  "publicSlug": "support-api",
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "organizationName": "Support API",
  "environment": "prod",
  "status": "active",
  "kind": "string",
  "runtimeType": "string",
  "guideUrl": "https://api.example.com",
  "mcpUrl": "https://api.example.com",
  "reservedMcpUrl": "https://api.example.com",
  "installGuideEnabled": true,
  "organizationPublicGuidesEnabled": true,
  "auth": {
    "type": "string",
    "hasGateway": true,
    "summary": "string",
    "protectedResourceMetadataUrl": "https://api.example.com",
    "authorizationServerUrl": "https://api.example.com",
    "authorizationServerMetadataUrl": "https://api.example.com",
    "authorizationEndpoint": "string",
    "tokenEndpoint": "redacted",
    "registrationEndpoint": "string",
    "resource": "string",
    "scopes": [
      "openid"
    ]
  },
  "tools": {
    "totalCount": 1,
    "enabledCount": 1,
    "featuredTools": [
      {
        "id": "id_123",
        "displayName": "Support API",
        "description": "Routes support ticket operations to MCP clients.",
        "httpMethod": "POST",
        "httpPath": "/tickets/{id}/notes",
        "isEnabled": true
      }
    ]
  },
  "readiness": {
    "deploymentStatus": "active",
    "catalogStatus": "active",
    "catalogCheckedAt": "2026-05-29T18:20:11Z",
    "catalogError": "string",
    "healthyRegionCount": 1,
    "configuredRegionCount": 1,
    "doctor": {
      "serverId": "mcp_5Qp8wYz",
      "publicUrl": "https://api.example.com",
      "checks": [
        {}
      ]
    }
  },
  "sourceType": "string",
  "providerDisplayName": "Support API",
  "shortDescription": "Routes support ticket operations to MCP clients.",
  "longDescription": "Routes support ticket operations to MCP clients.",
  "logoUrl": "https://api.example.com",
  "logoAltText": "string",
  "isListedInLibrary": true,
  "isIndexable": true,
  "canonicalUrl": "https://api.example.com",
  "category": "string",
  "tags": [
    "string"
  ],
  "supportedClients": [
    "string"
  ],
  "setupSteps": [
    {
      "clientKey": "string",
      "clientName": "Support API",
      "stepNumber": 1,
      "text": "string"
    }
  ],
  "faq": [
    {
      "question": "string",
      "answer": "string"
    }
  ],
  "docsUrl": "https://api.example.com",
  "authType": "string",
  "authSummary": "string",
  "seoTitle": "string",
  "seoDescription": "Routes support ticket operations to MCP clients."
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/mcp-app-guidesList published MCP app guides.List published MCP app guides.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`q`	query	`string`	Optional	`-`
`category`	query	`string`	Optional	`-`
`client`	query	`string`	Optional	`-`
`authType`	query	`string`	Optional	`-`
`source`	query	`string`	Optional	`-`
`sort`	query	`string`	Optional	`-`
`page`	query	`integer(int32)`	Optional	`1`
`pageSize`	query	`integer(int32)`	Optional	`24`

Response body200McpAppGuideListResponse

Field	Type	Required
`items`	`McpAppGuideCardResponse[] \| null`	Optional
`items[].slug`	`string \| null`	Optional
`items[].title`	`string \| null`	Optional
`items[].providerDisplayName`	`string \| null`	Optional
`items[].shortDescription`	`string \| null`	Optional
`items[].logoUrl`	`string \| null`	Optional
`items[].logoAltText`	`string \| null`	Optional
`items[].sourceType`	`string \| null`	Optional
`items[].category`	`string \| null`	Optional
`items[].tags`	`string[] \| null`	Optional
`items[].supportedClients`	`string[] \| null`	Optional
`items[].authType`	`string \| null`	Optional
`items[].docsUrl`	`string \| null`	Optional
`items[].sortWeight`	`integer(int32)`	Optional
`items[].publishedAt`	`string(date-time) \| null`	Optional
`page`	`integer(int32)`	Optional
`pageSize`	`integer(int32)`	Optional
`totalCount`	`integer(int32)`	Optional
`categories`	`string[] \| null`	Optional
`supportedClients`	`string[] \| null`	Optional
`authTypes`	`string[] \| null`	Optional

{
  "items": [
    {
      "slug": "support-api",
      "title": "string",
      "providerDisplayName": "Support API",
      "shortDescription": "Routes support ticket operations to MCP clients.",
      "logoUrl": "https://api.example.com",
      "logoAltText": "string",
      "sourceType": "string",
      "category": "string",
      "tags": [
        "string"
      ],
      "supportedClients": [
        "string"
      ],
      "authType": "string",
      "docsUrl": "https://api.example.com",
      "sortWeight": 1,
      "publishedAt": "2026-05-29T18:20:11Z"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "categories": [
    "string"
  ],
  "supportedClients": [
    "string"
  ],
  "authTypes": [
    "string"
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/mcp-app-guides/{slug}Get one published MCP app guide.Get one published MCP app guide.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`environment`	query	`string`	Optional	`-`
`includeDoctor`	query	`boolean`	Optional	`true`

Response body200McpInstallGuideResponse

Field	Type	Required
`serverSlug`	`string \| null`	Optional
`publicSlug`	`string \| null`	Optional
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`organizationName`	`string \| null`	Optional
`environment`	`string \| null`	Optional
`status`	`string \| null`	Optional
`kind`	`string \| null`	Optional
`runtimeType`	`string \| null`	Optional
`guideUrl`	`string \| null`	Optional
`mcpUrl`	`string \| null`	Optional
`reservedMcpUrl`	`string \| null`	Optional
`installGuideEnabled`	`boolean`	Optional
`organizationPublicGuidesEnabled`	`boolean`	Optional
`auth`	`McpInstallGuideAuthResponse`	Optional
`auth.type`	`string \| null`	Optional
`auth.hasGateway`	`boolean`	Optional
`auth.summary`	`string \| null`	Optional
`auth.protectedResourceMetadataUrl`	`string \| null`	Optional
`auth.authorizationServerUrl`	`string \| null`	Optional
`auth.authorizationServerMetadataUrl`	`string \| null`	Optional
`auth.authorizationEndpoint`	`string \| null`	Optional
`auth.tokenEndpoint`	`string \| null`	Optional
`auth.registrationEndpoint`	`string \| null`	Optional
`auth.resource`	`string \| null`	Optional
`auth.scopes`	`string[] \| null`	Optional
`tools`	`McpInstallGuideToolSummaryResponse`	Optional
`tools.totalCount`	`integer(int32)`	Optional
`tools.enabledCount`	`integer(int32)`	Optional
`tools.featuredTools`	`McpInstallGuideToolResponse[] \| null`	Optional
`tools.featuredTools[].id`	`string \| null`	Optional
`tools.featuredTools[].displayName`	`string \| null`	Optional
`tools.featuredTools[].description`	`string \| null`	Optional
`tools.featuredTools[].httpMethod`	`string \| null`	Optional
`tools.featuredTools[].httpPath`	`string \| null`	Optional
`tools.featuredTools[].isEnabled`	`boolean`	Optional
`readiness`	`McpInstallGuideReadinessResponse`	Optional
`readiness.deploymentStatus`	`string \| null`	Optional
`readiness.catalogStatus`	`string \| null`	Optional
`readiness.catalogCheckedAt`	`string(date-time) \| null`	Optional
`readiness.catalogError`	`string \| null`	Optional
`readiness.healthyRegionCount`	`integer(int32)`	Optional
`readiness.configuredRegionCount`	`integer(int32)`	Optional
`readiness.doctor`	`DeploymentDoctorResponse`	Optional
`readiness.doctor.serverId`	`string \| null`	Optional
`readiness.doctor.publicUrl`	`string \| null`	Optional
`readiness.doctor.checks`	`DeploymentDoctorCheckResponse[] \| null`	Optional
`sourceType`	`string \| null`	Optional
`providerDisplayName`	`string \| null`	Optional
`shortDescription`	`string \| null`	Optional
`longDescription`	`string \| null`	Optional
`logoUrl`	`string \| null`	Optional
`logoAltText`	`string \| null`	Optional
`isListedInLibrary`	`boolean`	Optional
`isIndexable`	`boolean`	Optional
`canonicalUrl`	`string \| null`	Optional
`category`	`string \| null`	Optional
`tags`	`string[] \| null`	Optional
`supportedClients`	`string[] \| null`	Optional
`setupSteps`	`McpAppGuideSetupStepResponse[] \| null`	Optional
`setupSteps[].clientKey`	`string \| null`	Optional
`setupSteps[].clientName`	`string \| null`	Optional
`setupSteps[].stepNumber`	`integer(int32)`	Optional
`setupSteps[].text`	`string \| null`	Optional
`faq`	`McpAppGuideFaqResponse[] \| null`	Optional
`faq[].question`	`string \| null`	Optional
`faq[].answer`	`string \| null`	Optional
`docsUrl`	`string \| null`	Optional
`authType`	`string \| null`	Optional
`authSummary`	`string \| null`	Optional
`seoTitle`	`string \| null`	Optional
`seoDescription`	`string \| null`	Optional

{
  "serverSlug": "support-api",
  "publicSlug": "support-api",
  "name": "Support API",
  "description": "Routes support ticket operations to MCP clients.",
  "organizationName": "Support API",
  "environment": "prod",
  "status": "active",
  "kind": "string",
  "runtimeType": "string",
  "guideUrl": "https://api.example.com",
  "mcpUrl": "https://api.example.com",
  "reservedMcpUrl": "https://api.example.com",
  "installGuideEnabled": true,
  "organizationPublicGuidesEnabled": true,
  "auth": {
    "type": "string",
    "hasGateway": true,
    "summary": "string",
    "protectedResourceMetadataUrl": "https://api.example.com",
    "authorizationServerUrl": "https://api.example.com",
    "authorizationServerMetadataUrl": "https://api.example.com",
    "authorizationEndpoint": "string",
    "tokenEndpoint": "redacted",
    "registrationEndpoint": "string",
    "resource": "string",
    "scopes": [
      "openid"
    ]
  },
  "tools": {
    "totalCount": 1,
    "enabledCount": 1,
    "featuredTools": [
      {
        "id": "id_123",
        "displayName": "Support API",
        "description": "Routes support ticket operations to MCP clients.",
        "httpMethod": "POST",
        "httpPath": "/tickets/{id}/notes",
        "isEnabled": true
      }
    ]
  },
  "readiness": {
    "deploymentStatus": "active",
    "catalogStatus": "active",
    "catalogCheckedAt": "2026-05-29T18:20:11Z",
    "catalogError": "string",
    "healthyRegionCount": 1,
    "configuredRegionCount": 1,
    "doctor": {
      "serverId": "mcp_5Qp8wYz",
      "publicUrl": "https://api.example.com",
      "checks": [
        {}
      ]
    }
  },
  "sourceType": "string",
  "providerDisplayName": "Support API",
  "shortDescription": "Routes support ticket operations to MCP clients.",
  "longDescription": "Routes support ticket operations to MCP clients.",
  "logoUrl": "https://api.example.com",
  "logoAltText": "string",
  "isListedInLibrary": true,
  "isIndexable": true,
  "canonicalUrl": "https://api.example.com",
  "category": "string",
  "tags": [
    "string"
  ],
  "supportedClients": [
    "string"
  ],
  "setupSteps": [
    {
      "clientKey": "string",
      "clientName": "Support API",
      "stepNumber": 1,
      "text": "string"
    }
  ],
  "faq": [
    {
      "question": "string",
      "answer": "string"
    }
  ],
  "docsUrl": "https://api.example.com",
  "authType": "string",
  "authSummary": "string",
  "seoTitle": "string",
  "seoDescription": "Routes support ticket operations to MCP clients."
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/status/publicGet public platform status.Get public platform status.

Request bodynone

No request body.

Response body200PublicStatusResponse

Field	Type	Required
`environment`	`string \| null`	Optional
`generatedAtUtc`	`string(date-time)`	Optional
`stale`	`boolean`	Optional
`overallStatus`	`string \| null`	Optional
`components`	`StatusComponentDto[] \| null`	Optional
`components[].id`	`string \| null`	Optional
`components[].name`	`string \| null`	Optional
`components[].group`	`string \| null`	Optional
`components[].status`	`string \| null`	Optional
`components[].summary`	`string \| null`	Optional
`components[].updatedAtUtc`	`string(date-time)`	Optional
`components[].responseTimeMs`	`integer(int32) \| null`	Optional
`regions`	`StatusRegionDto[] \| null`	Optional
`regions[].region`	`string \| null`	Optional
`regions[].displayName`	`string \| null`	Optional
`regions[].status`	`string \| null`	Optional
`regions[].summary`	`string \| null`	Optional
`regions[].healthPercentage`	`number(double) \| null`	Optional
`regions[].latencyMs`	`number(double) \| null`	Optional
`regions[].updatedAtUtc`	`string(date-time)`	Optional
`historyDays`	`StatusHistoryDayDto[] \| null`	Optional
`historyDays[].date`	`string(date)`	Optional
`historyDays[].status`	`string \| null`	Optional
`historyDays[].uptimePercentage`	`number(double) \| null`	Optional
`historyDays[].observed`	`boolean`	Optional
`incidents`	`StatusIncidentDto[] \| null`	Optional
`incidents[].id`	`string \| null`	Optional
`incidents[].title`	`string \| null`	Optional
`incidents[].status`	`string \| null`	Optional
`incidents[].impact`	`string \| null`	Optional
`incidents[].startedAtUtc`	`string(date-time)`	Optional
`incidents[].resolvedAtUtc`	`string(date-time) \| null`	Optional
`incidents[].updates`	`StatusIncidentUpdateDto[] \| null`	Optional

{
  "environment": "prod",
  "generatedAtUtc": "2026-05-29T18:20:11Z",
  "stale": true,
  "overallStatus": "active",
  "components": [
    {
      "id": "id_123",
      "name": "Support API",
      "group": "string",
      "status": "active",
      "summary": "string",
      "updatedAtUtc": "2026-05-29T18:20:11Z",
      "responseTimeMs": 1
    }
  ],
  "regions": [
    {
      "region": "westus3",
      "displayName": "Support API",
      "status": "active",
      "summary": "string",
      "healthPercentage": 2500,
      "latencyMs": 0.2,
      "updatedAtUtc": "2026-05-29T18:20:11Z"
    }
  ],
  "historyDays": [
    {
      "date": "2026-05-29",
      "status": "active",
      "uptimePercentage": 2500,
      "observed": true
    }
  ],
  "incidents": [
    {
      "id": "id_123",
      "title": "string",
      "status": "active",
      "impact": "string",
      "startedAtUtc": "2026-05-29T18:20:11Z",
      "resolvedAtUtc": "2026-05-29T18:20:11Z",
      "updates": [
        {}
      ]
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

Dashboard, CLI, and identity#

These sit above the organization root.

MethodEndpointDescriptionCopy

GET/api/v1/dashboard/statsGet dashboard summary stats.Get dashboard summary stats.

Request bodynone

No request body.

Response body200DashboardStatsResponse

Field	Type	Required
`mcpServerCount`	`integer(int32)`	Optional
`apiKeyCount`	`integer(int32)`	Optional
`totalInvocationsToday`	`integer(int32)`	Optional
`totalInvocationsThisWeek`	`integer(int32)`	Optional
`recentServers`	`RecentMcpServer[] \| null`	Optional
`recentServers[].id`	`string \| null`	Optional
`recentServers[].slug`	`string \| null`	Optional
`recentServers[].name`	`string \| null`	Optional
`recentServers[].status`	`string \| null`	Optional
`recentServers[].totalInvocations`	`integer(int32)`	Optional
`recentServers[].toolCount`	`integer(int32)`	Optional
`recentServers[].createdOn`	`string(date-time)`	Optional
`recentActivity`	`RecentActivity[] \| null`	Optional
`recentActivity[].id`	`string \| null`	Optional
`recentActivity[].toolName`	`string \| null`	Optional
`recentActivity[].mcpServerId`	`string \| null`	Optional
`recentActivity[].mcpServerName`	`string \| null`	Optional
`recentActivity[].success`	`boolean`	Optional
`recentActivity[].durationMs`	`integer(int32)`	Optional
`recentActivity[].calledAt`	`string(date-time)`	Optional

{
  "mcpServerCount": 1,
  "apiKeyCount": 1,
  "totalInvocationsToday": 1,
  "totalInvocationsThisWeek": 1,
  "recentServers": [
    {
      "id": "id_123",
      "slug": "support-api",
      "name": "Support API",
      "status": "active",
      "totalInvocations": 1,
      "toolCount": 1,
      "createdOn": "2026-05-29T18:20:11Z"
    }
  ],
  "recentActivity": [
    {
      "id": "id_123",
      "toolName": "Support API",
      "mcpServerId": "mcp_5Qp8wYz",
      "mcpServerName": "Support API",
      "success": true,
      "durationMs": 1,
      "calledAt": "2026-05-29T18:20:11Z"
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/dashboard/analyticsGet aggregated analytics.Get aggregated analytics.

Request bodynone

No request body.

Parametersquery

Name	In	Type	Required	Default
`days`	query	`integer(int32)`	Optional	`30`

Response body200DashboardAnalyticsResponse

Field	Type	Required
`dailyInvocations`	`DailyStats[] \| null`	Optional
`dailyInvocations[].date`	`string \| null`	Optional
`dailyInvocations[].count`	`integer(int32)`	Optional
`dailyInvocations[].successCount`	`integer(int32)`	Optional
`dailyInvocations[].failureCount`	`integer(int32)`	Optional
`dailyInvocations[].avgLatencyMs`	`number(double)`	Optional
`totalInvocations`	`integer(int32)`	Optional
`successCount`	`integer(int32)`	Optional
`failureCount`	`integer(int32)`	Optional
`avgLatencyMs`	`number(double)`	Optional
`topTools`	`ToolUsageStats[] \| null`	Optional
`topTools[].toolName`	`string \| null`	Optional
`topTools[].count`	`integer(int32)`	Optional
`topTools[].toolLabel`	`string \| null`	Optional
`serverSummaries`	`ServerSummary[] \| null`	Optional
`serverSummaries[].id`	`string \| null`	Optional
`serverSummaries[].name`	`string \| null`	Optional
`serverSummaries[].status`	`string \| null`	Optional
`serverSummaries[].totalInvocations`	`integer(int32)`	Optional
`serverSummaries[].errorRate`	`number(double)`	Optional
`serverSummaries[].last7DaysCounts`	`integer(int32)[] \| null`	Optional

{
  "dailyInvocations": [
    {
      "date": "string",
      "count": 1,
      "successCount": 1,
      "failureCount": 1,
      "avgLatencyMs": 0.2
    }
  ],
  "totalInvocations": 1,
  "successCount": 1,
  "failureCount": 1,
  "avgLatencyMs": 0.2,
  "topTools": [
    {
      "toolName": "Support API",
      "count": 1,
      "toolLabel": "string"
    }
  ],
  "serverSummaries": [
    {
      "id": "id_123",
      "name": "Support API",
      "status": "active",
      "totalInvocations": 1,
      "errorRate": 0.2,
      "last7DaysCounts": [
        1
      ]
    }
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/dashboard/onboardingGet dashboard onboarding state.Get dashboard onboarding state.

Request bodynone

No request body.

Response body200DashboardOnboardingResponse

Field	Type	Required
`organizationId`	`string \| null`	Optional
`organizationName`	`string \| null`	Optional
`organizationCreatedOn`	`string(date-time) \| null`	Optional
`lastOpenedAt`	`string(date-time) \| null`	Optional
`dismissedAt`	`string(date-time) \| null`	Optional
`completedAt`	`string(date-time) \| null`	Optional
`shouldShow`	`boolean`	Optional
`mcpServerCount`	`integer(int32)`	Optional
`gatewayCount`	`integer(int32)`	Optional
`agentCount`	`integer(int32)`	Optional
`apiKeyCount`	`integer(int32)`	Optional

{
  "organizationId": "org_7Hf3kQ2",
  "organizationName": "Support API",
  "organizationCreatedOn": "2026-05-29T18:20:11Z",
  "lastOpenedAt": "2026-05-29T18:20:11Z",
  "dismissedAt": "2026-05-29T18:20:11Z",
  "completedAt": "2026-05-29T18:20:11Z",
  "shouldShow": true,
  "mcpServerCount": 1,
  "gatewayCount": 1,
  "agentCount": 1,
  "apiKeyCount": 1
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

PATCH/api/v1/dashboard/onboardingUpdate dashboard onboarding state.Update dashboard onboarding state.

Request bodyDashboardOnboardingUpdateRequest · application/json

Field	Type	Required
`action`	`string`	Required

{
  "action": "string"
}

Response body200DashboardOnboardingResponse

Field	Type	Required
`organizationId`	`string \| null`	Optional
`organizationName`	`string \| null`	Optional
`organizationCreatedOn`	`string(date-time) \| null`	Optional
`lastOpenedAt`	`string(date-time) \| null`	Optional
`dismissedAt`	`string(date-time) \| null`	Optional
`completedAt`	`string(date-time) \| null`	Optional
`shouldShow`	`boolean`	Optional
`mcpServerCount`	`integer(int32)`	Optional
`gatewayCount`	`integer(int32)`	Optional
`agentCount`	`integer(int32)`	Optional
`apiKeyCount`	`integer(int32)`	Optional

{
  "organizationId": "org_7Hf3kQ2",
  "organizationName": "Support API",
  "organizationCreatedOn": "2026-05-29T18:20:11Z",
  "lastOpenedAt": "2026-05-29T18:20:11Z",
  "dismissedAt": "2026-05-29T18:20:11Z",
  "completedAt": "2026-05-29T18:20:11Z",
  "shouldShow": true,
  "mcpServerCount": 1,
  "gatewayCount": 1,
  "agentCount": 1,
  "apiKeyCount": 1
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/auth/meGet the current user.Get the current user.

Request bodynone

No request body.

Response body200UserInfo

Field	Type	Required
`id`	`string`	Required
`email`	`string`	Required
`firstName`	`string \| null`	Optional
`lastName`	`string \| null`	Optional
`role`	`string \| null`	Optional
`idVerified`	`boolean`	Required

{
  "id": "id_123",
  "email": "teammate@example.com",
  "firstName": "Support",
  "lastName": "API",
  "role": "developer",
  "idVerified": true
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/auth/request-password-resetRequest a password reset email.Request a password reset email.

Request bodyRequestPasswordResetRequest · application/json

Field	Type	Required
`email`	`string`	Required
`language`	`string \| null`	Optional

{
  "email": "teammate@example.com",
  "language": "string"
}

Response body200MessageResponse

Field	Type	Required
`message`	`string`	Required

{
  "message": "If an account exists, a password reset email has been sent."
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

POST/api/v1/auth/reset-passwordReset a password with a reset token.Reset a password with a reset token.

Request bodyResetPasswordRequest · application/json

Field	Type	Required
`token`	`string`	Required
`newPassword`	`string`	Required

{
  "token": "redacted",
  "newPassword": "string"
}

Response body200MessageResponse

Field	Type	Required
`message`	`string`	Required

{
  "message": "Password reset successfully."
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/cli/configGet CLI bootstrap config. No auth required.Get CLI bootstrap config. No auth required.

Request bodynone

No request body.

Response body200CliConfigResponse

Field	Type	Required
`apiUrl`	`string \| null`	Optional
`authIssuer`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`deviceAuthorizationEndpoint`	`string \| null`	Optional
`tokenEndpoint`	`string \| null`	Optional
`resource`	`string \| null`	Optional
`scopes`	`string[] \| null`	Optional
`supportedAuthModes`	`string[] \| null`	Optional

{
  "apiUrl": "https://api.example.com",
  "authIssuer": "string",
  "clientId": "id_123",
  "deviceAuthorizationEndpoint": "string",
  "tokenEndpoint": "redacted",
  "resource": "string",
  "scopes": [
    "openid"
  ],
  "supportedAuthModes": [
    "string"
  ]
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

GET/api/v1/cli/whoamiIdentify the caller behind a token or key.Identify the caller behind a token or key.

Request bodynone

No request body.

Response body200CliWhoAmIResponse

Field	Type	Required
`principalId`	`string \| null`	Optional
`authType`	`string \| null`	Optional
`subject`	`string \| null`	Optional
`email`	`string \| null`	Optional
`clientId`	`string \| null`	Optional
`serviceAccountId`	`string \| null`	Optional
`organizationId`	`string \| null`	Optional

{
  "principalId": "id_123",
  "authType": "string",
  "subject": "string",
  "email": "teammate@example.com",
  "clientId": "id_123",
  "serviceAccountId": "id_123",
  "organizationId": "org_7Hf3kQ2"
}

Common errors

400Invalid JSON, missing business-required fields, or an invalid state transition.

401Missing, expired, or invalid bearer token/API key.

403Authenticated principal does not have the required organization or resource grant.

404The organization or child resource id was not found for this caller.

409Duplicate names, already-linked resources, or conflicting lifecycle state.

429Mutation rate limit exceeded; retry after the current window.

These endpoints are intentionally out of scope for this public reference: system-admin (/api/v1/admin/*), Gateway OAuth and MCP proxy flow (/api/v1/gateway/{publicId}/* and /.well-known/*), embed-key chat/runtime endpoints (/api/v1/chat*, /api/v1/agent-runtime/*, and realtime transcription), telemetry ingestion, Stripe webhooks, and internal status incident management.