{
"openapi": "3.1.0",
"info": {
"title": "Melso API",
"version": "2026-10-12",
"description": "Customer integration contracts for Melso. Agents access is internal or by private invitation. Fiscal approval remains in the authenticated app.",
"contact": {
"name": "Melso",
"url": "https://melso.ai/en"
}
},
"servers": [
{
"url": "https://melso.ai",
"description": "Production API origin"
}
],
"tags": [
{
"name": "Areas",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nAreas operations available within the caller's documented permissions."
},
{
"name": "Artifacts",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nArtifacts operations available within the caller's documented permissions."
},
{
"name": "Authentication",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nAuthentication operations available within the caller's documented permissions."
},
{
"name": "Automations",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nAutomations operations available within the caller's documented permissions."
},
{
"name": "Companies",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nCompanies operations available within the caller's documented permissions."
},
{
"name": "Execution funding",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nExecution funding operations available within the caller's documented permissions."
},
{
"name": "Files",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nFiles operations available within the caller's documented permissions."
},
{
"name": "GitHub",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nGitHub operations available within the caller's documented permissions."
},
{
"name": "Interactions",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nInteractions operations available within the caller's documented permissions."
},
{
"name": "Knowledge",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nKnowledge operations available within the caller's documented permissions."
},
{
"name": "MCP",
"description": "MCP operations available within the caller's documented permissions."
},
{
"name": "Messages",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nMessages operations available within the caller's documented permissions."
},
{
"name": "OAuth",
"description": "OAuth operations available within the caller's documented permissions."
},
{
"name": "Private network",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nPrivate network operations available within the caller's documented permissions."
},
{
"name": "Runs",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nRuns operations available within the caller's documented permissions."
},
{
"name": "Skills",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nSkills operations available within the caller's documented permissions."
},
{
"name": "Tasks",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nTasks operations available within the caller's documented permissions."
},
{
"name": "Vault",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nVault operations available within the caller's documented permissions."
},
{
"name": "Webhooks",
"description": "Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).\n\nWebhooks operations available within the caller's documented permissions."
}
],
"paths": {
"/.well-known/oauth-authorization-server": {
"get": {
"operationId": "mCPOAuthAuthorizationServerMetadata",
"summary": "Mcpo auth authorization server metadata",
"description": "Public.\n\nRequest: No body.\n\nResponse: OAuth metadata including issuer, authorization/token/registration/revocation endpoints, grant types, PKCE methods and supported scope.\n\nStatus: 200; 503 OAuth URL not configured. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"200": {
"description": "OAuth metadata including issuer, authorization/token/registration/revocation endpoints, grant types, PKCE methods and supported scope.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authorization_endpoint": {},
"authorization_response_iss_parameter_supported": {
"type": "boolean"
},
"client_id_metadata_document_supported": {
"type": "boolean"
},
"code_challenge_methods_supported": {
"type": "array",
"items": {
"type": "string"
}
},
"grant_types_supported": {
"type": "array",
"items": {
"type": "string"
}
},
"issuer": {
"type": "string"
},
"registration_endpoint": {},
"response_types_supported": {
"type": "array",
"items": {
"type": "string"
}
},
"revocation_endpoint": {},
"scopes_supported": {
"type": "array",
"items": {
"type": "string"
}
},
"token_endpoint": {},
"token_endpoint_auth_methods_supported": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"authorization_endpoint",
"authorization_response_iss_parameter_supported",
"client_id_metadata_document_supported",
"code_challenge_methods_supported",
"grant_types_supported",
"issuer",
"registration_endpoint",
"response_types_supported",
"revocation_endpoint",
"scopes_supported",
"token_endpoint",
"token_endpoint_auth_methods_supported"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"/.well-known/oauth-protected-resource": {
"get": {
"operationId": "mCPOAuthProtectedResourceMetadata",
"summary": "Mcpo auth protected resource metadata",
"description": "Public.\n\nRequest: No body.\n\nResponse: `{resource:string,authorization_servers:string[],bearer_methods_supported:string[],scopes_supported:string[]}`.\n\nStatus: 200; 503 OAuth URL not configured. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"200": {
"description": "`{resource:string,authorization_servers:string[],bearer_methods_supported:string[],scopes_supported:string[]}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authorization_servers": {
"type": "array",
"items": {
"type": "string"
}
},
"bearer_methods_supported": {
"type": "array",
"items": {
"type": "string"
}
},
"resource": {
"type": "string"
},
"scopes_supported": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"authorization_servers",
"bearer_methods_supported",
"resource",
"scopes_supported"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"/.well-known/oauth-protected-resource/api/mcp": {
"get": {
"operationId": "mCPOAuthProtectedResourceMetadata2",
"summary": "Mcpo auth protected resource metadata",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authorization_servers": {
"type": "array",
"items": {
"type": "string"
}
},
"bearer_methods_supported": {
"type": "array",
"items": {
"type": "string"
}
},
"resource": {
"type": "string"
},
"scopes_supported": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"authorization_servers",
"bearer_methods_supported",
"resource",
"scopes_supported"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"/.well-known/oauth-protected-resource/mcp": {
"get": {
"operationId": "mCPOAuthProtectedResourceMetadata3",
"summary": "Mcpo auth protected resource metadata",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"authorization_servers": {
"type": "array",
"items": {
"type": "string"
}
},
"bearer_methods_supported": {
"type": "array",
"items": {
"type": "string"
}
},
"resource": {
"type": "string"
},
"scopes_supported": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"authorization_servers",
"bearer_methods_supported",
"resource",
"scopes_supported"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"/api/areas": {
"get": {
"operationId": "listAreas",
"summary": "List areas",
"description": "Workspace member with access to this resource.\n\nRequest: No body.\n\nResponse: `{areas:AreaResponse[],total:integer}`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{areas:AreaResponse[],total:integer}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"areas": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AreaResponse"
}
},
"total": {
"type": "integer"
}
},
"required": [
"areas",
"total"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createArea",
"summary": "Create area",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: `title:string`; optional `description:string|null`, `icon:string|null`, `instructions:string|null`, `resources:CreateAreaResourceRequest[]`, `idempotency_key:string`.\n\nResponse: AreaResponse plus `resources:AreaResourceResponse[]`.\n\nStatus: 201; 400 validation; 403 definition-write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "AreaResponse plus `resources:AreaResourceResponse[]`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"icon": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sandbox_size": {
"type": "string"
},
"resources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateAreaResourceRequestPayloadInput"
}
},
"sort_order": {
"type": "integer"
},
"instructions": {
"type": [
"string",
"null"
]
},
"default_harness": {
"type": "string"
},
"default_model": {
"type": "string"
},
"default_thinking_level": {
"type": "string"
},
"default_service_tier": {
"type": "string"
},
"idempotency_key": {
"type": "string",
"description": "Stable request key for a company definition edit."
}
},
"required": [
"title"
]
}
}
}
}
}
},
"/api/areas/search": {
"get": {
"operationId": "searchAreas",
"summary": "Search areas",
"description": "Workspace member with access to this resource.\n\nRequest: Query: `q:string`, optional `limit:integer`, `offset:integer`.\n\nResponse: `{areas:SearchAreaResponse[],total:integer}`.\n\nStatus: 200; 400 missing query; 503 search timeout. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Optional limit filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"description": "Optional offset filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"description": "Optional q filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{areas:SearchAreaResponse[],total:integer}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"areas": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchAreaResponse"
}
},
"total": {
"type": "integer"
}
},
"required": [
"areas",
"total"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/areas/{id}": {
"delete": {
"operationId": "deleteArea",
"summary": "Delete area",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: Path: Area ID; optional JSON `idempotency_key:string`.\n\nResponse: `{company_commit_sha:string}`.\n\nStatus: 200; 403 definition-write denied; 409 dependency/activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Definition deletion committed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"company_commit_sha": {
"type": "string"
}
},
"required": [
"company_commit_sha"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"operationId": "getArea",
"summary": "Get area",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Area UUID or slug.\n\nResponse: AreaResponse.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AreaResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "updateArea",
"summary": "Update area",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: Optional `title:string`, `description:string|null`, `icon:string|null`, `instructions:string|null`, `sort_order:integer`, `idempotency_key:string`.\n\nResponse: AreaResponse.\n\nStatus: 200; 400 validation; 403 definition-write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AreaResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"icon": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sandbox_size": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sort_order": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"instructions": {
"type": [
"string",
"null"
]
},
"idempotency_key": {
"type": "string",
"description": "Stable request key for a company definition edit."
}
}
}
}
}
}
}
},
"/api/areas/{id}/access": {
"get": {
"operationId": "getAreaAccess",
"summary": "Get area access",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Area ID.\n\nResponse: `{visibility:string,member_ids:UUID[]}`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{visibility:string,member_ids:UUID[]}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaAccessResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "replaceAreaAccess",
"summary": "Replace area access",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: `visibility:\"workspace\"|\"selected\"`, `member_ids:UUID[]`. Workspace visibility requires an empty member set.\n\nResponse: The accepted access object.\n\nStatus: 200; 400 invalid member/visibility. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaAccessResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaAccessRequestInput"
},
"example": {
"visibility": "workspace",
"member_ids": []
}
}
}
}
}
},
"/api/areas/{id}/connections": {
"get": {
"operationId": "listAreaConnections",
"summary": "List area connections",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Area ID.\n\nResponse: `{connections:AreaConnectionResponse[]}`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{connections:AreaConnectionResponse[]}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"available_accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConnectedAppConnectionResponse"
}
},
"company_commit_sha": {
"type": "string"
},
"connections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AreaConnectionResponse"
}
},
"selected_account_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"selected_mcp_server_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"available_accounts",
"company_commit_sha",
"connections",
"selected_account_ids",
"selected_mcp_server_ids"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"operationId": "setAreaConnection",
"summary": "Set area connection",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: `{connection_kind:string,connection_ref:string,owner_user_id:UUID,visibility:\"private\"|\"shared\",enabled:boolean}`. Changes only this connection; other grants remain unchanged. The account must be active when enabling it. Disabling an unavailable account is allowed.\n\nResponse: Connection list response.\n\nStatus: 200; 400 invalid connection; 403 machine credential, account ownership or MCP administration denied; 404 Area/server unavailable; 409 account unavailable or grant ownership changed. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"available_accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConnectedAppConnectionResponse"
}
},
"company_commit_sha": {
"type": "string"
},
"connections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AreaConnectionResponse"
}
},
"selected_account_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"selected_mcp_server_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"available_accounts",
"company_commit_sha",
"connections",
"selected_account_ids",
"selected_mcp_server_ids"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"connection_kind": {
"type": "string"
},
"connection_ref": {
"type": "string"
},
"owner_user_id": {
"type": "string"
},
"visibility": {
"type": "string"
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"required": [
"connection_kind",
"connection_ref",
"enabled"
]
}
}
}
}
},
"put": {
"operationId": "replaceAreaConnections",
"summary": "Replace area connections",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: `connections:[{connection_kind:string,connection_ref:string,owner_user_id:UUID,visibility:\"private\"|\"shared\",enabled?:boolean}]`. Replaces the caller's grants; omitted grants owned by other members remain unchanged. Personal accounts require their owner's consent. Workspace MCP grants require an owner/admin. Use PATCH for a single toggle or visibility change.\n\nResponse: Connection list response.\n\nStatus: 200; 400 invalid or duplicate connections; 403 machine credential, account ownership or MCP administration denied; 404 Area/server unavailable; 409 account unavailable or grant ownership changed. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"available_accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConnectedAppConnectionResponse"
}
},
"company_commit_sha": {
"type": "string"
},
"connections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AreaConnectionResponse"
}
},
"selected_account_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"selected_mcp_server_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"available_accounts",
"company_commit_sha",
"connections",
"selected_account_ids",
"selected_mcp_server_ids"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"connections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SetAreaConnectionRequestInput"
}
}
},
"required": [
"connections"
]
}
}
}
}
}
},
"/api/areas/{id}/defaults": {
"put": {
"operationId": "updateAreaDefaults",
"summary": "Update area defaults",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: Optional `default_harness:string|null`, `default_model:string|null`, `default_thinking_level:string|null`, `default_service_tier:string|null`; explicit null clears a default.\n\nResponse: AreaResponse.\n\nStatus: 200; 400 validation; 403 definition-write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AreaResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"default_harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"default_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"default_thinking_level": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"default_service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idempotency_key": {
"type": "string",
"description": "Stable request key for a company definition edit."
}
}
}
}
}
}
}
},
"/api/areas/{id}/instructions": {
"put": {
"operationId": "updateAreaInstructions",
"summary": "Update area instructions",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: `instructions:string`, up to 256 KB. An empty string clears them. Every Run in the Area receives them as its Area Context. They are stored with the workspace, not in the company definition.\n\nResponse: AreaResponse.\n\nStatus: 200; 400 validation; 413 too large. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AreaResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAreaInstructionsRequestInput"
},
"example": {
"instructions": "Track qualified demand weekly."
}
}
}
}
}
},
"/api/areas/{id}/resources": {
"get": {
"operationId": "listAreaResources",
"summary": "List area resources",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Area ID.\n\nResponse: `{resources:AreaResourceResponse[],total:integer}`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{resources:AreaResourceResponse[],total:integer}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AreaResourceResponse"
}
},
"total": {
"type": "integer"
}
},
"required": [
"resources",
"total"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createAreaResource",
"summary": "Create area resource",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: `resource_type:string`, `resource_ref:object`; optional `label:string|null`, `position:integer`. For `github_repo`, resource_ref uses `url:string`, optional `ref:string` and `default_branch_hint:string`.\n\nResponse: AreaResourceResponse.\n\nStatus: 201; 400 invalid reference; 403 definition-write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "AreaResourceResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaResourceResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource_type": {
"type": "string"
},
"resource_ref": {},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"position": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"idempotency_key": {
"type": "string",
"description": "Stable request key for a company definition edit."
}
}
}
}
}
}
}
},
"/api/areas/{id}/resources/{resourceId}": {
"delete": {
"operationId": "deleteAreaResource",
"summary": "Delete area resource",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: Path: Area and resource IDs; optional definition idempotency key.\n\nResponse: `{company_commit_sha:string}`.\n\nStatus: 200; 403 definition-write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "resourceId",
"in": "path",
"required": true,
"description": "resourceId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Definition deletion committed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"company_commit_sha": {
"type": "string"
}
},
"required": [
"company_commit_sha"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "updateAreaResource",
"summary": "Update area resource",
"description": "An Agents company and company definition write permission are required: owner/admin, or an admin company API key only on its [allowed Area routes](/api-reference/authentication#area-routes-by-key-scope). Other company types receive `403 agents_only`. Resource access also applies.\n\nRequest: Optional `resource_ref:object`, `label:string|null`, `position:integer`. Resource type cannot change.\n\nResponse: AreaResourceResponse.\n\nStatus: 200; 400 invalid reference; 403 definition-write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Areas"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "resourceId",
"in": "path",
"required": true,
"description": "resourceId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AreaResourceResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AreaResourceResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource_ref": {},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"position": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"idempotency_key": {
"type": "string",
"description": "Stable request key for a company definition edit."
}
}
}
}
}
}
}
},
"/api/artifacts/{operation}": {
"post": {
"operationId": "callArtifacts",
"summary": "Call artifacts",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Artifacts"
],
"parameters": [
{
"name": "operation",
"in": "path",
"required": true,
"description": "operation from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"description": "Operation-specific JSON from the Artifact service. The selected operation determines its shape."
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific arguments. Discover the corresponding Artifact MCP tool schema before calling."
}
}
}
}
}
},
"/api/attachments/{id}": {
"get": {
"operationId": "getAttachmentByID",
"summary": "Get attachment by id",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Files"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttachmentResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/attachments/{id}/content": {
"get": {
"operationId": "getAttachmentContent",
"summary": "Get attachment content",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Files"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Plain text preview.",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/attachments/{id}/download": {
"get": {
"operationId": "downloadAttachment",
"summary": "Download attachment",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Files"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Attachment bytes. Content-Type follows the stored file.",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automation-recipes": {
"get": {
"operationId": "listAutomationRecipes",
"summary": "List automation recipes",
"description": "Workspace member with access to this resource.\n\nRequest: Query `area_key?:\"company\"|\"product\"|\"gtm\"|\"support\"|\"legal\"|\"finance\"`.\n\nResponse: `{version:string,recipes:AreaRecipe[]}`.\n\nStatus: 200; 400 unknown area key. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "area_key",
"in": "query",
"description": "Optional area_key filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{version:string,recipes:AreaRecipe[]}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/areaRecipeCatalogResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automation-recipes/{recipeKey}/install": {
"post": {
"operationId": "installAutomationRecipe",
"summary": "Install automation recipe",
"description": "Workspace member with access to this resource.\n\nRequest: InstallAreaRecipeRequest below. `area_id:UUID`, `harness:string` select the destination. Optional title/prompt/schedule/model overrides and `idempotency_key:string`.\n\nResponse: InstallAreaRecipeResponse.\n\nStatus: 201 created; 200 existing; 400 invalid recipe/options; 403 company write denied; 409 saved but not activated. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "recipeKey",
"in": "path",
"required": true,
"description": "recipeKey from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "InstallAreaRecipeResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstallAreaRecipeResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstallAreaRecipeRequestInput"
}
}
}
}
}
},
"/api/automations": {
"get": {
"operationId": "listAutomations",
"summary": "List automations",
"description": "Workspace member with access to this resource.\n\nRequest: Optional query `status:string`.\n\nResponse: `{automations:AutomationResponse[],total:integer}` (returned count).\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "status",
"in": "query",
"description": "Optional status filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{automations:AutomationResponse[],total:integer}` (returned count).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"automations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationResponse"
}
},
"total": {
"type": "integer"
}
},
"required": [
"automations",
"total"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createAutomation",
"summary": "Create automation",
"description": "Definition edits require company write permission and the Automation creator/admin/collaborator management rules.\n\nRequest: `title:string`, `harness:string`; optional `description:string|null`, `area_id:UUID|null`, `model:string|null`, `thinking_level:string|null`, `service_tier:string|null`, `task_title_template:string|null`, `subscribers:[{user_type:\"member\",user_id:UUID}]`, `triggers:array` (trigger definitions, created together with the Automation), `idempotency_key:string`.\n\nResponse: AutomationResponse.\n\nStatus: 201; 400 validation; 403 write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomationResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"area_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"harness": {
"type": "string"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"thinking_level": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"task_title_template": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"subscribers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SubscriberInputInput"
}
},
"triggers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateAutomationTriggerRequestInput"
}
},
"enabled": {
"type": "boolean"
},
"idempotency_key": {
"type": "string",
"description": "Stable request key for a company definition edit."
}
},
"required": [
"title",
"harness"
]
}
}
}
}
}
},
"/api/automations/cron-preview": {
"get": {
"operationId": "cronPreview",
"summary": "Cron preview",
"description": "Workspace member with access to this resource.\n\nRequest: Query `expr:string` required (cron expression), `tz?:string` (default UTC).\n\nResponse: `{next_occurrences:timestamp[]}`; at most three UTC occurrences.\n\nStatus: 200; 400 invalid_cron/invalid_timezone. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "expr",
"in": "query",
"description": "Optional expr filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "tz",
"in": "query",
"description": "Optional tz filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{next_occurrences:timestamp[]}`; at most three UTC occurrences.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"next_occurrences": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"next_occurrences"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{id}": {
"delete": {
"operationId": "deleteAutomation",
"summary": "Delete automation",
"description": "Definition edits require company write permission and the Automation creator/admin/collaborator management rules.\n\nRequest: Path: Automation UUID; optional definition idempotency key.\n\nResponse: `{company_commit_sha:string}`.\n\nStatus: 200; 403 write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Definition deletion committed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"company_commit_sha": {
"type": "string"
}
},
"required": [
"company_commit_sha"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"operationId": "getAutomation",
"summary": "Get automation",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Automation UUID.\n\nResponse: `{automation:AutomationResponse,triggers:AutomationTriggerResponse[],collaborators:object[]}`; management flags are inside `automation`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{automation:AutomationResponse,triggers:AutomationTriggerResponse[],collaborators:object[]}`; management flags are inside `automation`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"automation": {
"$ref": "#/components/schemas/AutomationResponse"
},
"collaborators": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationCollaboratorEntry"
}
},
"triggers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationTriggerResponse"
}
}
},
"required": [
"automation",
"collaborators",
"triggers"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"operationId": "updateAutomation",
"summary": "Update automation",
"description": "Definition edits require company write permission and the Automation creator/admin/collaborator management rules.\n\nRequest: Optional creation fields; `status:string`; `subscribers` replaces its set when present.\n\nResponse: AutomationResponse, for definition edits and for `status` or `subscribers` changes alike.\n\nStatus: 200; 400 validation; 403 write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomationResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"area_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"thinking_level": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"task_title_template": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"subscribers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SubscriberInputInput"
}
},
"triggers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateAutomationTriggerRequestInput"
}
},
"enabled": {
"type": "boolean"
},
"idempotency_key": {
"type": "string",
"description": "Stable request key for a company definition edit."
}
}
}
}
}
}
}
},
"/api/automations/{id}/collaborators": {
"post": {
"operationId": "addAutomationCollaborator",
"summary": "Add automation collaborator",
"description": "Automation creator or workspace owner/admin.\n\nRequest: `user_id:UUID` in this workspace.\n\nResponse: `{collaborators:object[]}`.\n\nStatus: 201; 400 invalid member; 403 access management denied. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"collaborators": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationCollaboratorEntry"
}
}
},
"required": [
"collaborators"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomationCollaboratorRequestInput"
},
"example": {
"user_id": "00000000-0000-4000-8000-000000000001"
}
}
}
}
}
},
"/api/automations/{id}/collaborators/{userId}": {
"delete": {
"operationId": "removeAutomationCollaborator",
"summary": "Remove automation collaborator",
"description": "Automation creator or workspace owner/admin.\n\nRequest: Path: member UUID.\n\nResponse: `{collaborators:object[]}`.\n\nStatus: 200; 403 access management denied. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "userId",
"in": "path",
"required": true,
"description": "userId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"collaborators": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationCollaboratorEntry"
}
}
},
"required": [
"collaborators"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{id}/deliveries": {
"get": {
"operationId": "listAutomationDeliveries",
"summary": "List automation deliveries",
"description": "Workspace member with access to this resource.\n\nRequest: Query `limit?:integer`, `offset?:integer`. These are inbound webhook receipts.\n\nResponse: `{deliveries:WebhookDeliveryResponse[],total:integer}` (returned count).\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{deliveries:WebhookDeliveryResponse[],total:integer}` (returned count).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deliveries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookDeliveryResponse"
}
},
"total": {
"type": "integer"
}
},
"required": [
"deliveries",
"total"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{id}/deliveries/{deliveryId}": {
"get": {
"operationId": "getAutomationDelivery",
"summary": "Get automation delivery",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Automation and inbound delivery UUIDs.\n\nResponse: WebhookDeliveryResponse including stored request/response detail.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "deliveryId",
"in": "path",
"required": true,
"description": "deliveryId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "WebhookDeliveryResponse including stored request/response detail.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookDeliveryResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{id}/deliveries/{deliveryId}/replay": {
"post": {
"operationId": "replayAutomationDelivery",
"summary": "Replay automation delivery",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Automation and inbound delivery UUIDs.\n\nResponse: New WebhookDeliveryResponse.\n\nStatus: 201; 400 invalid source; 403 write denied; 409 replay conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "deliveryId",
"in": "path",
"required": true,
"description": "deliveryId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "New WebhookDeliveryResponse.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{id}/invocations": {
"get": {
"operationId": "listAutomationInvocations",
"summary": "List automation invocations",
"description": "Workspace member with access to this resource.\n\nRequest: Query `limit?:integer`, `offset?:integer`.\n\nResponse: `{invocations:AutomationInvocationResponse[],total:integer}` (returned count).\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{invocations:AutomationInvocationResponse[],total:integer}` (returned count).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"invocations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationInvocationResponse"
}
},
"total": {
"type": "integer"
}
},
"required": [
"invocations",
"total"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{id}/invocations/{invocationId}": {
"get": {
"operationId": "getAutomationInvocation",
"summary": "Get automation invocation",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Automation and invocation UUIDs.\n\nResponse: AutomationInvocationResponse.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "invocationId",
"in": "path",
"required": true,
"description": "invocationId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AutomationInvocationResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomationInvocationResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{id}/subscription": {
"put": {
"operationId": "setMyAutomationSubscription",
"summary": "Set my automation subscription",
"description": "Workspace member with access to this resource.\n\nRequest: `delivery:\"inbox\"|\"agent\"|\"none\"` selects this member’s delivery preference.\n\nResponse: `{automation_id:UUID,delivery:string|null}`.\n\nStatus: 200; 400 invalid preference; 403 membership required. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{automation_id:UUID,delivery:string|null}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/automationSubscriptionResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/automationSubscriptionBodyInput"
},
"example": {
"delivery": "inbox"
}
}
}
}
}
},
"/api/automations/{id}/trigger": {
"post": {
"operationId": "triggerAutomation",
"summary": "Trigger automation",
"description": "Workspace member with access to this resource.\n\nRequest: No body. Automation must be active.\n\nResponse: AutomationInvocationResponse.\n\nStatus: 200; 400 not active; 403 write denied. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AutomationInvocationResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomationInvocationResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{id}/triggers": {
"post": {
"operationId": "createAutomationTrigger",
"summary": "Create automation trigger",
"description": "Workspace member with access to this resource.\n\nRequest: `kind:\"schedule\"|\"webhook\"|\"integration\"`; optional `cron_expression:string`, `timezone:string`, `label:string`, `provider:\"generic\"|\"github\"`, `event_filters:[{event:string,actions?:string[]}]`. An integration trigger requires `integration_trigger:{toolkit_slug:string,connected_account_id:string,trigger_slug:string,trigger_config:object}`.\n\nResponse: AutomationTriggerResponse.\n\nStatus: 201; 400 invalid trigger; 403 write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomationTriggerResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"cron_expression": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"event_filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEventFilterInput"
}
},
"enabled": {
"type": "boolean"
},
"integration_trigger": {
"$ref": "#/components/schemas/IntegrationTriggerInput"
},
"idempotency_key": {
"type": "string",
"description": "Stable request key for a company definition edit."
}
}
}
}
}
}
}
},
"/api/automations/{id}/triggers/{triggerId}": {
"delete": {
"operationId": "deleteAutomationTrigger",
"summary": "Delete automation trigger",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Automation and trigger UUIDs; optional definition idempotency key.\n\nResponse: `{company_commit_sha:string}`.\n\nStatus: 200; 403 write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "triggerId",
"in": "path",
"required": true,
"description": "triggerId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Definition deletion committed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"company_commit_sha": {
"type": "string"
}
},
"required": [
"company_commit_sha"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"operationId": "updateAutomationTrigger",
"summary": "Update automation trigger",
"description": "Workspace member with access to this resource.\n\nRequest: Optional `enabled:boolean`, `cron_expression:string`, `timezone:string`, `label:string`, `event_filters:array` (empty clears filters), `integration_trigger:object` (replaces a connected-app event configuration).\n\nResponse: AutomationTriggerResponse.\n\nStatus: 200; 400 validation; 403 write denied; 409 activation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "triggerId",
"in": "path",
"required": true,
"description": "triggerId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomationTriggerResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"cron_expression": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"event_filters": {
"anyOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEventFilterInput"
}
},
{
"type": "null"
}
]
},
"integration_trigger": {
"$ref": "#/components/schemas/IntegrationTriggerInput"
},
"idempotency_key": {
"type": "string",
"description": "Stable request key for a company definition edit."
}
}
}
}
}
}
}
},
"/api/automations/{id}/triggers/{triggerId}/rotate-webhook-token": {
"post": {
"operationId": "rotateAutomationTriggerWebhookToken",
"summary": "Rotate automation trigger webhook token",
"description": "Workspace member with access to this resource.\n\nRequest: Path: webhook trigger UUID.\n\nResponse: AutomationTriggerResponse with new webhook URL/token.\n\nStatus: 200; 400 not webhook trigger; 403 write denied. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "triggerId",
"in": "path",
"required": true,
"description": "triggerId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AutomationTriggerResponse with new webhook URL/token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomationTriggerResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/automations/{id}/triggers/{triggerId}/signing-secret": {
"put": {
"operationId": "setAutomationTriggerSigningSecret",
"summary": "Set automation trigger signing secret",
"description": "Workspace member with access to this resource.\n\nRequest: `signing_secret:string`; at least 16 characters, or empty to clear inbound verification.\n\nResponse: AutomationTriggerResponse.\n\nStatus: 200; 400 invalid secret/type; 403 write denied. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "triggerId",
"in": "path",
"required": true,
"description": "triggerId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AutomationTriggerResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomationTriggerResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetSigningSecretRequestInput"
},
"example": {
"signing_secret": "replace-with-a-random-secret"
}
}
}
}
}
},
"/api/cloud/capabilities": {
"get": {
"operationId": "getCloudCapabilities",
"summary": "Get cloud capabilities",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/executionCapabilities"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/execution-credential-broker": {
"delete": {
"operationId": "deleteExecutionCredentialBroker",
"summary": "Delete execution credential broker",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"operationId": "getExecutionCredentialBroker",
"summary": "Get execution credential broker",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "setExecutionCredentialBroker",
"summary": "Set execution credential broker",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"endpoint": {
"type": "string"
},
"token": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/execution-identities": {
"get": {
"operationId": "listExecutionIdentities",
"summary": "List execution identities",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"identities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ListManagedExecutionIdentitiesRow"
}
}
},
"required": [
"identities"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createExecutionIdentity",
"summary": "Create execution identity",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"external_id": {},
"id": {
"type": "string"
}
},
"required": [
"external_id",
"id"
]
}
}
}
},
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ManagedExecutionIdentity"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"external_id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/execution-identities/{identityId}": {
"delete": {
"operationId": "revokeExecutionIdentity",
"summary": "Revoke execution identity",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "identityId",
"in": "path",
"required": true,
"description": "identityId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ManagedExecutionIdentity"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/harnesses/{harness}/models": {
"get": {
"operationId": "listHarnessModels",
"summary": "List harness models",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "harness",
"in": "path",
"required": true,
"description": "harness from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelEntry"
}
},
"supported": {
"type": "boolean"
}
},
"required": [
"models",
"supported"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/interactions/{interactionId}": {
"get": {
"operationId": "getInteraction",
"summary": "Get interaction",
"description": "Workspace member with access to this resource.\n\nRequest: Path: interaction UUID (and Task ID for the scoped route).\n\nResponse: InteractionRequestResponse.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "interactionId",
"in": "path",
"required": true,
"description": "interactionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "InteractionRequestResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/interactions/{interactionId}/cancel": {
"post": {
"operationId": "cancelInteraction",
"summary": "Cancel interaction",
"description": "Respond/decline: the authenticated recipient, or a current workspace owner or admin. The responder is recorded and supplies authority for any continuation Run. Cancel: authorized member, or the original active source Run.\n\nRequest: `response:object` for respond; optional `audit_text:string`. Approval response uses `decision:\"approve_once\"|\"deny\"|\"decline\"`; clarification uses `answers:object` keyed by question IDs.\n\nResponse: InteractionRequestResponse.\n\nStatus: 200; 400 invalid answers; 403 actor/recipient mismatch; 409 already resolved or continuation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "interactionId",
"in": "path",
"required": true,
"description": "interactionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/cancelInteractionRequestBodyInput"
}
}
}
}
}
},
"/api/interactions/{interactionId}/decline": {
"post": {
"operationId": "declineInteraction",
"summary": "Decline interaction",
"description": "Respond/decline: the authenticated recipient, or a current workspace owner or admin. The responder is recorded and supplies authority for any continuation Run. Cancel: authorized member, or the original active source Run.\n\nRequest: `response:object` for respond; optional `audit_text:string`. Approval response uses `decision:\"approve_once\"|\"deny\"|\"decline\"`; clarification uses `answers:object` keyed by question IDs.\n\nResponse: InteractionRequestResponse.\n\nStatus: 200; 400 invalid answers; 403 actor/recipient mismatch; 409 already resolved or continuation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "interactionId",
"in": "path",
"required": true,
"description": "interactionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/respondInteractionRequestBodyInput"
}
}
}
}
}
},
"/api/interactions/{interactionId}/respond": {
"post": {
"operationId": "respondInteraction",
"summary": "Respond interaction",
"description": "Respond/decline: the authenticated recipient, or a current workspace owner or admin. The responder is recorded and supplies authority for any continuation Run. Cancel: authorized member, or the original active source Run.\n\nRequest: `response:object` for respond; optional `audit_text:string`. Approval response uses `decision:\"approve_once\"|\"deny\"|\"decline\"`; clarification uses `answers:object` keyed by question IDs.\n\nResponse: InteractionRequestResponse.\n\nStatus: 200; 400 invalid answers; 403 actor/recipient mismatch; 409 already resolved or continuation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "interactionId",
"in": "path",
"required": true,
"description": "interactionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/respondInteractionRequestBodyInput"
}
}
}
}
}
},
"/api/knowledge/{operation}": {
"post": {
"operationId": "callKnowledge",
"summary": "Call knowledge",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Knowledge"
],
"parameters": [
{
"name": "operation",
"in": "path",
"required": true,
"description": "operation from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"description": "Operation-specific JSON from the Knowledge service. The selected operation determines its shape."
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific arguments. Discover the corresponding Knowledge MCP tool schema before calling."
}
}
}
}
}
},
"/api/mcp": {
"post": {
"operationId": "handleMCP",
"summary": "Handle mcp",
"description": "MCP OAuth access token or active Run token, each acting in its one company. A personal access token is refused with 401.\n\nRequest: JSON-RPC `{jsonrpc:\"2.0\",id:string|number,method:string,params?:object}`. Initialize first. For `tools/call`, params are `{name:string,arguments:object}`, for example `{\"name\":\"areas\",\"arguments\":{\"action\":\"create\",\"title\":\"Product\"}}`.\n\nResponse: JSON-RPC `{jsonrpc:\"2.0\",id,result}` or `{jsonrpc:\"2.0\",id,error}`; tool results include content blocks and optional structured data.\n\nStatus: 200 JSON-RPC response; 202 notification; 400/403 invalid protocol or actor; 401 personal access token; 413 oversized request. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"MCP"
],
"parameters": [],
"responses": {
"200": {
"description": "JSON-RPC response or an SSE stream for streaming clients.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jsonrpc": {
"type": "string",
"const": "2.0"
},
"id": {},
"result": {},
"error": {
"type": "object",
"properties": {
"code": {
"type": "integer"
},
"message": {
"type": "string"
},
"data": {}
}
}
},
"required": [
"jsonrpc"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"202": {
"description": "Notification accepted; no response body."
}
},
"security": [
{
"mcpOAuth": [
"mcp:tools"
]
},
{
"runToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/mcpRPCRequestInput"
}
}
}
}
}
},
"/api/mcp/upload-file": {
"post": {
"operationId": "uploadFile",
"summary": "Upload file",
"description": "MCP OAuth token; acts in its granted workspace. Run credentials retain their Task scope.\n\nRequest: Multipart `file:binary` required; same size limit (under 100 MiB per request on melso.ai and mcp.melso.ai) and optional Task/message/Run association fields as POST /api/upload-file in [Tasks](/concepts/tasks-api). Upload each file separately.\n\nResponse: AttachmentResponse (see Tasks). Pass returned IDs as `attachment_ids:UUID[]` to `tasks_create` or `tasks_send`.\n\nStatus: 200; 400 invalid upload; 403 denied; 503 storage unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"MCP"
],
"parameters": [],
"responses": {
"200": {
"description": "AttachmentResponse (see Tasks). Pass returned IDs as `attachment_ids:UUID[]` to `tasks_create` or `tasks_send`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttachmentResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"mcpOAuth": [
"mcp:tools"
]
},
{
"runToken": []
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"task_id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"run_id": {
"type": "string"
}
},
"required": [
"file"
]
}
}
}
}
}
},
"/api/mcp/upload-secret": {
"post": {
"operationId": "uploadVaultFile",
"summary": "Upload vault file",
"description": "MCP OAuth token; uses its granted workspace. Run tokens rejected.\n\nRequest: Multipart `file:binary` (at most 1 MB) and `env_name:string`, the variable that will hold the file's path. Optional `filename`, `share` and `area_ids` (repeat the field or separate IDs with commas). Replaces your file with the same variable.\n\nResponse: `{item:VaultItem}`\n\nStatus: 201; 400 invalid upload or variable; 403 Run token; 409 the variable holds another kind; 503 vault unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"MCP"
],
"parameters": [],
"responses": {
"201": {
"description": "`{item:VaultItem}`",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"item": {}
},
"required": [
"item"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"mcpOAuth": [
"mcp:tools"
]
},
{
"runToken": []
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"env_name": {
"type": "string"
},
"share": {
"type": "string"
},
"area_ids": {
"type": "string"
}
},
"required": [
"file"
]
}
}
}
}
}
},
"/api/mcp/upload-skill": {
"post": {
"operationId": "uploadMCPSkill",
"summary": "Upload mcp skill",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"MCP"
],
"parameters": [],
"responses": {
"200": {
"description": "Imported Skill result; conflict handling can return an existing Skill.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillImportResult"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"201": {
"description": "New Skill imported.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillImportResult"
}
}
}
}
},
"security": [
{
"mcpOAuth": [
"mcp:tools"
]
},
{
"runToken": []
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"scope": {
"type": "string"
},
"area_ids": {
"type": "string"
},
"on_conflict": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"file"
]
}
}
}
}
}
},
"/api/me": {
"get": {
"operationId": "getMe",
"summary": "Get me",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MeResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/oauth/mcp/authorize": {
"get": {
"operationId": "describeMCPOAuthAuthorization",
"summary": "Describe mcpo auth authorization",
"description": "Signed-in member; validates the OAuth client and requested resource.\n\nRequest: OAuth authorization query fields: `client_id`, `redirect_uri`, `response_type=code`, `code_challenge`, `code_challenge_method=S256`, optional scope/resource as validated by the handler.\n\nResponse: `{client_name:string,scope:string}`.\n\nStatus: 200; 400 invalid consent request. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"200": {
"description": "`{client_name:string,scope:string}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"client_id": {
"type": "string"
},
"client_name": {
"type": "string"
},
"scope": {}
},
"required": [
"client_id",
"client_name",
"scope"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "approveMCPOAuthAuthorization",
"summary": "Approve mcpo auth authorization",
"description": "Signed-in member approving access to their selected workspace.\n\nRequest: `client_id:string`, `redirect_uri:string`, `state:string`, `code_challenge:string`, `resource:string`, `scope:string`, `workspace_id:UUID` (required: the one company the connection acts in; `all_workspaces` is refused).\n\nResponse: `{redirect_uri:string}` containing a short-lived authorization code.\n\nStatus: 200; 400 invalid consent, no company or `all_workspaces`; 403/404 workspace access denied. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"200": {
"description": "`{redirect_uri:string}` containing a short-lived authorization code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"redirect_uri": {
"type": "string"
}
},
"required": [
"redirect_uri"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/mcpOAuthApproveRequestInput"
},
"example": {
"client_id": "client-id",
"redirect_uri": "http://127.0.0.1:8080/callback",
"state": "random-state",
"code_challenge": "S256-challenge",
"resource": "https://mcp.melso.ai/mcp",
"scope": "mcp:tools",
"workspace_id": "00000000-0000-4000-8000-000000000001"
}
}
}
}
}
},
"/api/oauth/mcp/grants": {
"get": {
"operationId": "listMCPOAuthGrants",
"summary": "List mcpo auth grants",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"grants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/mcpOAuthGrantResponse"
}
}
},
"required": [
"grants"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/oauth/mcp/grants/{grantId}": {
"delete": {
"operationId": "revokeMCPOAuthGrant",
"summary": "Revoke mcpo auth grant",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"OAuth"
],
"parameters": [
{
"name": "grantId",
"in": "path",
"required": true,
"description": "grantId from the corresponding authorized response.",
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts": {
"get": {
"operationId": "listProviderAccounts",
"summary": "List provider accounts",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"accounts": {}
},
"required": [
"accounts"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/auth-sessions": {
"post": {
"operationId": "beginProviderAccountAuth",
"summary": "Begin provider account auth",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthSession"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"reconnect_id": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/provider-accounts/auth-sessions/{sessionId}": {
"delete": {
"operationId": "cancelProviderAccountAuth",
"summary": "Cancel provider account auth",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "sessionId",
"in": "path",
"required": true,
"description": "sessionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"operationId": "getProviderAccountAuth",
"summary": "Get provider account auth",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "sessionId",
"in": "path",
"required": true,
"description": "sessionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthSession"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/auth-sessions/{sessionId}/submit": {
"post": {
"operationId": "completeProviderAccountAuth",
"summary": "Complete provider account auth",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "sessionId",
"in": "path",
"required": true,
"description": "sessionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthSession"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/provider-accounts/defaults/{provider}": {
"delete": {
"operationId": "clearDefaultProviderAccount",
"summary": "Clear default provider account",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "provider",
"in": "path",
"required": true,
"description": "provider from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/harnesses": {
"get": {
"operationId": "listHarnessAccess",
"summary": "List harness access",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"harnesses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HarnessAccess"
}
}
},
"required": [
"harnesses"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/harnesses/{harness}": {
"put": {
"operationId": "updateHarnessAccess",
"summary": "Update harness access",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "harness",
"in": "path",
"required": true,
"description": "harness from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"harnesses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HarnessAccess"
}
}
},
"required": [
"harnesses"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HarnessAccessUpdateInput"
}
}
}
}
}
},
"/api/provider-accounts/import": {
"post": {
"operationId": "importProviderAccount",
"summary": "Import provider account",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string"
}
},
"required": [
"status"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"api_key": {
"type": "string"
},
"refresh_token": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/provider-accounts/{accountId}": {
"delete": {
"operationId": "deleteProviderAccount",
"summary": "Delete provider account",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "accountId",
"in": "path",
"required": true,
"description": "accountId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"operationId": "getProviderAccount",
"summary": "Get provider account",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "accountId",
"in": "path",
"required": true,
"description": "accountId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/{accountId}/default": {
"post": {
"operationId": "selectDefaultProviderAccount",
"summary": "Select default provider account",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "accountId",
"in": "path",
"required": true,
"description": "accountId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/{accountId}/disable": {
"post": {
"operationId": "disableProviderAccount",
"summary": "Disable provider account",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "accountId",
"in": "path",
"required": true,
"description": "accountId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/{accountId}/enable": {
"post": {
"operationId": "enableProviderAccount",
"summary": "Enable provider account",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "accountId",
"in": "path",
"required": true,
"description": "accountId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"204": {
"description": "Successful response."
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/{accountId}/execution-identities/{identityId}": {
"delete": {
"operationId": "shareProviderAccountExecutionIdentity",
"summary": "Share provider account execution identity",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "accountId",
"in": "path",
"required": true,
"description": "accountId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "identityId",
"in": "path",
"required": true,
"description": "identityId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "shareProviderAccountExecutionIdentity2",
"summary": "Share provider account execution identity",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "accountId",
"in": "path",
"required": true,
"description": "accountId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "identityId",
"in": "path",
"required": true,
"description": "identityId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/{accountId}/pause": {
"post": {
"operationId": "pauseProviderAccount",
"summary": "Pause provider account",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "accountId",
"in": "path",
"required": true,
"description": "accountId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"204": {
"description": "Successful response."
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/provider-accounts/{accountId}/refresh-usage": {
"post": {
"operationId": "refreshProviderAccountUsage",
"summary": "Refresh provider account usage",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Execution funding"
],
"parameters": [
{
"name": "accountId",
"in": "path",
"required": true,
"description": "accountId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Execution-Identity-ID",
"in": "header",
"required": false,
"description": "For an admin company key managing an execution customer owned by its integration. Omit for personal account management.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/public/artifacts/{shareID}/{operation}": {
"post": {
"operationId": "publicArtifacts",
"summary": "Public artifacts",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Artifacts"
],
"parameters": [
{
"name": "shareID",
"in": "path",
"required": true,
"description": "shareID from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "operation",
"in": "path",
"required": true,
"description": "operation from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"description": "Operation-specific JSON from the Artifact service. The selected operation determines its shape."
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific arguments. Discover the corresponding Artifact MCP tool schema before calling."
}
}
}
}
}
},
"/api/pull-requests/resolve": {
"get": {
"operationId": "resolvePullRequest",
"summary": "Resolve pull request",
"description": "Workspace member with access to this resource.\n\nRequest: Query `owner:string`, `repo:string`, `number:integer` required.\n\nResponse: `{id:UUID}` for an authorized linked PR.\n\nStatus: 200; 400 missing/invalid query; 404 no accessible PR. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "number",
"in": "query",
"description": "Optional number filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "owner",
"in": "query",
"description": "Optional owner filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "repo",
"in": "query",
"description": "Optional repo filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{id:UUID}` for an authorized linked PR.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/resolvePullRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/pull-requests/{id}": {
"get": {
"operationId": "getPullRequest",
"summary": "Get pull request",
"description": "Workspace member with access to this resource.\n\nRequest: Path: PR record UUID.\n\nResponse: GitHubPullRequestDetailResponse.\n\nStatus: 200; 404 inaccessible PR. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "GitHubPullRequestDetailResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GitHubPullRequestDetailResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/pull-requests/{id}/merge": {
"post": {
"operationId": "mergePullRequest",
"summary": "Merge pull request",
"description": "Workspace owner/admin (a person), or a workspace API key with `admin` scope. Run and MCP credentials are rejected, and `tasks` API keys get `403 workspace_key_scope`; `can_merge` on the PR detail reports whether the caller may merge.\n\nRequest: `merge_method?:\"merge\"|\"squash\"|\"rebase\"`, `commit_title?:string`, `commit_message?:string`.\n\nResponse: `{merged:boolean,sha:string,pull_request:GitHubPullRequestResponse}`.\n\nStatus: 200; 400 invalid method; 403 denied; 409 merge/check conflict; 502 GitHub failure. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{merged:boolean,sha:string,pull_request:GitHubPullRequestResponse}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"merged": {
"type": "boolean"
},
"pull_request": {
"$ref": "#/components/schemas/GitHubPullRequestResponse"
},
"sha": {}
},
"required": [
"merged",
"pull_request",
"sha"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/mergePullRequestRequestInput"
},
"example": {
"merge_method": "squash"
}
}
}
}
}
},
"/api/runs/{runId}": {
"get": {
"operationId": "getRunByUser",
"summary": "Get run by user",
"description": "Workspace member with access to the Run’s Task, under the same rules as `GET /api/tasks/{id}/runs`. A workspace API key reads Runs of its own workspace.\n\nRequest: Path: Run UUID. No body.\n\nResponse: RunResponse, identical to the Run’s item in `GET /api/tasks/{id}/runs`, including `usage` and `attribution`.\n\nStatus: 200; 400 invalid UUID; 404 unknown Run. A Run the caller may not see (another workspace, a private Area the caller is not in, an isolated Task for another Task’s Run) returns the same 404. Authentication errors follow [Overview](/api-reference/errors).",
"tags": [
"Runs"
],
"parameters": [
{
"name": "runId",
"in": "path",
"required": true,
"description": "runId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "RunResponse, identical to the Run’s item in `GET /api/tasks/{id}/runs`, including `usage` and `attribution`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/runs/{runId}/cancel": {
"post": {
"operationId": "cancelRun",
"summary": "Cancel run",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Run UUID. Query parameters, not a JSON body: optional `task_id=` rejects a Run from another Task; cancelling a queued follow-up uses `expected_status=queued` plus `task_id` and `queue_action=edit|remove`.\n\nResponse: RunResponse plus optional `cancelled_input:{task_id:UUID,message_id:UUID,content:string,restore_to_input:boolean,attachments:object[]}`. Cancelling a Run that already ended returns it unchanged.\n\nStatus: 200; 400 invalid query parameters; 404 unknown Run; 409 mismatched Task or a follow-up that is no longer queued. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Runs"
],
"parameters": [
{
"name": "runId",
"in": "path",
"required": true,
"description": "runId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "expected_status",
"in": "query",
"description": "Optional expected_status filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "queue_action",
"in": "query",
"description": "Optional queue_action filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "task_id",
"in": "query",
"description": "Optional task_id filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "RunResponse plus optional `cancelled_input:{task_id:UUID,message_id:UUID,content:string,restore_to_input:boolean,attachments:object[]}`. Cancelling a Run that already ended returns it unchanged.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelRunResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/runs/{runId}/events": {
"get": {
"operationId": "listRunEventsByUser",
"summary": "List run events by user",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Run UUID. No pagination parameters.\n\nResponse: `{events:RunEventPayload[]}`.\n\nStatus: 200; 400 invalid UUID. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Runs"
],
"parameters": [
{
"name": "runId",
"in": "path",
"required": true,
"description": "runId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{events:RunEventPayload[]}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunEventResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/runs/{runId}/messages": {
"get": {
"operationId": "listRunMessagesByUser",
"summary": "List run messages by user",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Run UUID; optional `since:integer` query.\n\nResponse: RunMessagePayload array.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Runs"
],
"parameters": [
{
"name": "runId",
"in": "path",
"required": true,
"description": "runId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "since",
"in": "query",
"description": "Optional since filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "RunMessagePayload array.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RunMessagePayload"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/runs/{runId}/pause": {
"post": {
"operationId": "pauseRun",
"summary": "Pause run",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Run UUID.\n\nResponse: RunResponse for the Run it acted on. A live Cloud Run drains first and keeps its status until the worker saves; it then ends `cancelled` with `user_paused` and a `paused` successor appears in the Task’s Runs. A queued or deferred Run is cancelled with `user_paused`; an already paused Run is returned unchanged.\n\nStatus: 200; 409 incompatible Run state. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Runs"
],
"parameters": [
{
"name": "runId",
"in": "path",
"required": true,
"description": "runId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "RunResponse for the Run it acted on. A live Cloud Run drains first and keeps its status until the worker saves; it then ends `cancelled` with `user_paused` and a `paused` successor appears in the Task’s Runs. A queued or deferred Run is cancelled with `user_paused`; an already paused Run is returned unchanged.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/runs/{runId}/usage": {
"get": {
"operationId": "getRunUsage",
"summary": "Get run usage",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Runs"
],
"parameters": [
{
"name": "runId",
"in": "path",
"required": true,
"description": "runId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runUsageResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/secret-requests": {
"get": {
"operationId": "listVaultRequests",
"summary": "List vault requests",
"description": "Workspace member or Run token. Returns only the caller's own requests; for a Run, those of the member who started it.\n\nRequest: None.\n\nResponse: `{requests:OpenVaultRequest[]}`, newest first: every request the caller has not answered yet. Each is a `VaultRequestView` plus `requested_by` (`member`, `run` or `agent`), `created_at` and `task` (`{id,identifier,title}` for the Task that waits, or `null` for a chat's request or a Task the caller can no longer open). `expires_at` is empty except for a public link a chat got before requests needed sign-in; such a request leaves the list when its hour ends.\n\nStatus: 200; 503 vault unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Vault"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{requests:OpenVaultRequest[]}`, newest first: every request the caller has not answered yet. Each is a `VaultRequestView` plus `requested_by` (`member`, `run` or `agent`), `created_at` and `task` (`{id,identifier,title}` for the Task that waits, or `null` for a chat's request or a Task the caller can no longer open). `expires_at` is empty except for a public link a chat got before requests needed sign-in; such a request leaves the list when its hour ends.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"requests": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwnedRequest"
}
}
},
"required": [
"requests"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createVaultRequest",
"summary": "Create vault request",
"description": "Workspace member, or the Run token of an active Run. The saved item belongs to the caller; for a Run, to the member who started it.\n\nRequest: `kind` (`login`, `card`, `text` or `file`) and optional non-secret prefill: `name`, `env_name`, `url`, `username`, `cardholder`, `note` (at most 500 characters, shown on the request), `share`, `area_ids`. A `text` request needs its variable name in `name` or `env_name`; a `file` request needs `env_name`.\n\nResponse: `{request:{id,kind},url:string}`. `url` is `https:///settings?tab=vault&request=&workspace_id=`: it opens the request in the caller's Settings → Secrets once they are signed in, and never expires.\n\nStatus: 201; 400 invalid input; 403 Run token without an active Run; 503 vault unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Vault"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "`{request:{id,kind},url:string}`. `url` is `https:///settings?tab=vault&request=&workspace_id=`: it opens the request in the caller's Settings → Secrets once they are signed in, and never expires.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"request": {
"$ref": "#/components/schemas/Request"
},
"url": {
"type": "string"
}
},
"required": [
"request",
"url"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/vaultRequestBodyInput"
},
"example": {
"kind": "login",
"url": "dashboard.stripe.com",
"username": "ops@example.com",
"note": "Download monthly payouts"
}
}
}
}
}
},
"/api/secret-requests/fulfill": {
"post": {
"operationId": "fulfillVaultRequest",
"summary": "Fulfill vault request",
"description": "Public; the `token` in the body is the credential. Rate limited per IP.\n\nRequest: `token:string` and one value of the request's kind: `text`, `login`, `card` or `file`, in the same shapes as `POST /api/secrets`. Optional `name` renames a login or card; the variable of a text or file request is fixed.\n\nResponse: `{item:{kind,name,env_name}}`\n\nStatus: 200; 400 invalid value or wrong kind, and the link stays usable; 404 unknown token; 409 the variable holds another kind; 410 `link_expired` or `link_used`; 429 rate limited; 503 vault unavailable.",
"tags": [
"Vault"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{item:{kind,name,env_name}}`",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"410": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/vaultFulfillBodyInput"
}
}
}
}
}
},
"/api/secret-requests/lookup": {
"post": {
"operationId": "lookupVaultRequest",
"summary": "Lookup vault request",
"description": "Public; the `token` in the body is the credential. Rate limited per IP. Only a request a WhatsApp, Telegram or email chat made before requests needed sign-in has a token; nothing mints one any more, and these two endpoints go once those links have expired.\n\nRequest: `token:string`, the link's URL fragment.\n\nResponse: `{request:VaultRequestView}`. Reading does not use the link.\n\nStatus: 200; 404 unknown token; 429 rate limited; 503 vault unavailable.",
"tags": [
"Vault"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{request:VaultRequestView}`. Reading does not use the link.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"request": {
"$ref": "#/components/schemas/RequestView"
}
},
"required": [
"request"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/vaultTokenBodyInput"
}
}
}
}
}
},
"/api/secret-requests/{id}": {
"delete": {
"operationId": "dismissVaultRequest",
"summary": "Dismiss vault request",
"description": "The workspace member the request was sent to. Run tokens rejected.\n\nRequest: None.\n\nResponse: Empty.\n\nStatus: 204; 403 Run token; 404 unknown, already saved, or sent to another member; 503 vault unavailable.",
"tags": [
"Vault"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/secret-requests/{id}/fulfill": {
"post": {
"operationId": "fulfillOwnedVaultRequest",
"summary": "Fulfill owned vault request",
"description": "The workspace member the request was sent to. Run tokens rejected.\n\nRequest: One value of the request's kind: `text`, `login`, `card` or `file`, in the same shapes as `POST /api/secrets`. Optional `name` renames a login or card; the variable of a text or file request is fixed.\n\nResponse: `{item:{kind,name,env_name}}`\n\nStatus: 200; 400 invalid value or wrong kind, and the request stays open; 403 Run token; 404 unknown request, or one sent to another member; 409 the variable holds another kind; 410 `link_used` (already saved) or `link_expired` (a chat's link ran out); 503 vault unavailable.",
"tags": [
"Vault"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{item:{kind,name,env_name}}`",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"410": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/vaultFulfillBodyInput"
},
"example": {
"text": "replace-with-the-key"
}
}
}
}
}
},
"/api/secrets": {
"get": {
"operationId": "listVaultItems",
"summary": "List vault items",
"description": "Workspace member or Run token. Admins see every item; members see their own items and the items shared with them.\n\nRequest: None.\n\nResponse: `{items:VaultItem[]}`, ordered by kind, then name. Repository variables are not listed.\n\nStatus: 200; 503 vault unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Vault"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{items:VaultItem[]}`, ordered by kind, then name. Repository variables are not listed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {}
},
"required": [
"items"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createVaultItem",
"summary": "Create vault item",
"description": "Workspace member; Run tokens rejected. The caller owns the item.\n\nRequest: Exactly one value: `text:string` (at most 64 KB), `login:{url,username,password,totp_secret?}`, `card:{cardholder?,number,exp_month,exp_year,cvc,billing_address?}` or `file:{filename,content_base64}` (at most 1 MB decoded). Optional `kind` (must match the value); `name` (a login or card's display name, or a text item's variable name, which `env_name` can also supply); `env_name` (required for a file; derived from `name` for a login or card, such as `STRIPE_LOGIN`); `share` and `area_ids`; `replace:boolean` to overwrite your item with the same variable name instead of returning 409. `totp_secret` is the base32 2FA setup key. A new item without `share` is private; a replaced item keeps its sharing.\n\nResponse: `{item:VaultItem}`\n\nStatus: 201; 400 invalid value, name, Area or reserved variable (`MELSO_*`, `HOME`, `PATH` and other runtime keys); 403 Run token; 409 variable already used; 503 vault unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Vault"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "`{item:VaultItem}`",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"item": {}
},
"required": [
"item"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/vaultCreateBodyInput"
},
"example": {
"kind": "text",
"name": "OPENAI_API_KEY",
"text": "replace-with-the-key",
"share": "workspace"
}
}
}
}
}
},
"/api/secrets/repository": {
"get": {
"operationId": "getVaultRepositoryVariables",
"summary": "Get vault repository variables",
"description": "Workspace owner/admin, or a workspace API key with `admin` scope; Run tokens rejected.\n\nRequest: Query `repository_url:string`, an http(s) or SSH repository URL. It is normalized to `https://host/owner/repo`.\n\nResponse: `{repository_url:string,variables:RepositoryVariable[]}`; keys only.\n\nStatus: 200; 400 invalid repository URL; 403 not an owner/admin, or a Run token; 503 vault unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Vault"
],
"parameters": [
{
"name": "repository_url",
"in": "query",
"description": "Optional repository_url filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{repository_url:string,variables:RepositoryVariable[]}`; keys only.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"repository_url": {
"type": "string"
},
"variables": {}
},
"required": [
"repository_url",
"variables"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "replaceVaultRepositoryVariables",
"summary": "Replace vault repository variables",
"description": "Workspace owner/admin, or a workspace API key with `admin` scope; Run tokens rejected.\n\nRequest: `repository_url:string` and `variables:object`, mapping each key to a string value or to `null` to keep its stored value. The map replaces the repository's whole `.env`: a key left out is removed, and `{}` clears it.\n\nResponse: `{repository_url:string,variables:RepositoryVariable[]}`\n\nStatus: 200; 400 invalid key or value, missing `variables`, or `null` for a key with no stored value; 403 not an owner/admin, or a Run token; 503 vault unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Vault"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{repository_url:string,variables:RepositoryVariable[]}`",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"repository_url": {
"type": "string"
},
"variables": {}
},
"required": [
"repository_url",
"variables"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/vaultRepositoryBodyInput"
},
"example": {
"repository_url": "https://github.com/example/repo.git",
"variables": {
"API_URL": "https://api.example.com"
}
}
}
}
}
}
},
"/api/secrets/{id}": {
"delete": {
"operationId": "deleteVaultItem",
"summary": "Delete vault item",
"description": "The item's owner or a workspace owner/admin; Run tokens rejected.\n\nRequest: Path: item UUID.\n\nResponse: Empty.\n\nStatus: 204; 403 not the owner or an admin, or a Run token; 404 unknown item; 503 vault unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Vault"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"operationId": "updateVaultItem",
"summary": "Update vault item",
"description": "The item's owner or a workspace owner/admin; Run tokens rejected.\n\nRequest: Path: item UUID. At least one of `name` (a login or card's display name, or a text item's variable; ignored for a file, whose name is its file name); `env_name` (login, card or file); a replacement value of the item's kind (`text`, `login`, `card` or `file`); `share`, with `area_ids` when sharing with Areas. `area_ids` requires `share`. The kind never changes.\n\nResponse: `{item:VaultItem}`\n\nStatus: 200; 400 nothing to change or invalid input; 403 not the owner or an admin, or a Run token; 404 unknown item; 409 variable already used; 503 vault unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Vault"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{item:VaultItem}`",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"item": {}
},
"required": [
"item"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/vaultUpdateBodyInput"
},
"example": {
"share": "areas",
"area_ids": [
"00000000-0000-4000-8000-000000000001"
]
}
}
}
}
}
},
"/api/skills": {
"get": {
"operationId": "listSkills",
"summary": "List skills",
"description": "Workspace member.\n\nResponse: skill rows without `content`.\n\nStatus: 200. Authentication errors follow [Overview](/api-reference/errors).",
"tags": [
"Skills"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "skill rows without `content`.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SkillSummaryResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createSkill",
"summary": "Create skill",
"description": "Workspace member.\n\nRequest: `name:string` required, `description?:string`, `content?:string` (the `SKILL.md` text), `config?:object`, `files?:{path,content,encoding?}[]`.\n\nResponse: the skill with `files`.\n\nStatus: 201; 400 invalid body or file; 409 name taken.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "the skill with `files`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillWithFilesResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSkillRequestInput"
},
"example": {
"name": "release-notes",
"description": "Write release notes",
"content": "---\nname: release-notes\ndescription: Write release notes\n---\n"
}
}
}
}
}
},
"/api/skills/builtin": {
"get": {
"operationId": "listBuiltinSkills",
"summary": "List builtin skills",
"description": "Workspace member.\n\nResponse: `{name,description}[]`, sorted by name: the read-only skills Melso installs in every Run. Each is published at `/skills/.md`. The onboarding guides `melso-onboarding` and `melso-onboarding-mcp` are published there too but are not installed in Runs or listed here.\n\nStatus: 200.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{name,description}[]`, sorted by name: the read-only skills Melso installs in every Run. Each is published at `/skills/.md`. The onboarding guides `melso-onboarding` and `melso-onboarding-mcp` are published there too but are not installed in Runs or listed here.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BuiltinSkillResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/skills/import": {
"post": {
"operationId": "importSkill",
"summary": "Import skill",
"description": "Workspace member.\n\nResponse: with `on_conflict` (always for an archive): `{status,reason?,skill?,existing_skill?}` where `status` is `created`, `updated`, `conflict`, `skipped` or `failed`. `overwrite` replaces the existing skill only for its creator. Without `on_conflict`, a URL import returns the created skill, or a 409 with `existing_skill`.\n\nStatus: 201 created; 200 updated or skipped; 400 invalid source or archive; 403 overwrite by someone else; 409 conflict; 413 over the limits; 502/503/504 source unavailable or slow.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "New Skill imported.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillImportResult"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"200": {
"description": "Imported Skill result; conflict handling can return an existing Skill.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillImportResult"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportSkillRequestInput"
},
"example": {
"url": "https://skills.sh/anthropics/skills/pdf",
"on_conflict": "fail"
}
}
}
}
}
},
"/api/skills/search": {
"get": {
"operationId": "searchSkills",
"summary": "Search skills",
"description": "Workspace member.\n\nRequest: Query `q:string`, at least 2 characters.\n\nResponse: `{name,url,source,repo,install_count,description,audit_risk,audits}[]` from skills.sh. `url` is the install URL. `audit_risk` is the highest risk skills.sh's security audits report (`safe`, `low`, `medium`, `high` or `critical`), or null; it informs and never blocks an install.\n\nStatus: 200; 400 missing or short query; 502 `upstream_unavailable`.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "q",
"in": "query",
"description": "Optional q filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{name,url,source,repo,install_count,description,audit_risk,audits}[]` from skills.sh. `url` is the install URL. `audit_risk` is the highest risk skills.sh's security audits report (`safe`, `low`, `medium`, `high` or `critical`), or null; it informs and never blocks an install.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SkillSearchCandidateResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/skills/{id}": {
"delete": {
"operationId": "deleteSkill",
"summary": "Delete skill",
"description": "the skill's creator or a workspace owner/admin.\n\nStatus: 204; 403; 404. Runs stop receiving the skill.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"operationId": "getSkill",
"summary": "Get skill",
"description": "Workspace member.\n\nResponse: the skill with `content`, `files` and, for a sourced skill, `source_edited`: true once it was changed in Melso, which pauses its updates.\n\nStatus: 200; 404.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "the skill with `content`, `files` and, for a sourced skill, `source_edited`: true once it was changed in Melso, which pauses its updates.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillWithFilesResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "updateSkill",
"summary": "Update skill",
"description": "the skill's creator or a workspace owner/admin.\n\nRequest: any of `name`, `description`, `content`, `config`, `files` (replaces every file) and `auto_update:boolean`, which turns following the source on or off.\n\nResponse: the skill with `files`.\n\nStatus: 200; 400 invalid body, or `auto_update` on a skill with no source; 403; 404; 409 name taken.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "the skill with `files`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillWithFilesResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSkillRequestInput"
},
"example": {
"auto_update": false
}
}
}
}
}
},
"/api/skills/{id}/files": {
"get": {
"operationId": "listSkillFiles",
"summary": "List skill files",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SkillFileResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "upsertSkillFile",
"summary": "Upsert skill file",
"description": "the skill's creator or a workspace owner/admin.\n\nRequest: `path:string`, `content:string`, `encoding?:\"utf8\"|\"base64\"`. `SKILL.md` is reserved for the skill's `content`.\n\nResponse: the file. The skill's `updated_at` moves, so a sourced skill counts as edited.\n\nStatus: 200; 400 invalid path, encoding or `SKILL.md`; 403; 404.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "the file. The skill's `updated_at` moves, so a sourced skill counts as edited.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillFileResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSkillFileRequestInput"
},
"example": {
"path": "scripts/run.sh",
"content": "#!/bin/sh\necho ok\n"
}
}
}
}
}
},
"/api/skills/{id}/files/{fileId}": {
"delete": {
"operationId": "deleteSkillFile",
"summary": "Delete skill file",
"description": "the skill's creator or a workspace owner/admin.\n\nStatus: 204; 403; 404.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "fileId",
"in": "path",
"required": true,
"description": "fileId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No content."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/skills/{id}/refresh": {
"post": {
"operationId": "refreshSkill",
"summary": "Refresh skill",
"description": "the skill's creator or a workspace owner/admin.\n\nRequest: no body.\n\nResponse: the skill with `files`, replaced by its source's current version. Edits made in Melso are discarded and updates resume; the id and creator stay.\n\nStatus: 200; 403; 404; 409 the source renamed it to a taken name; 422 no source to update from; 413/502/503/504 source too large, gone or slow.",
"tags": [
"Skills"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "the skill with `files`, replaced by its source's current version. Edits made in Melso are discarded and updates resume; the id and creator stay.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillWithFilesResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/task-messages/{messageId}": {
"delete": {
"operationId": "deleteTaskMessage",
"summary": "Delete task message",
"description": "Workspace member with access to this resource.\n\nRequest: Path: message UUID; the author or a workspace owner/admin.\n\nResponse: Empty.\n\nStatus: 204; 403 neither author nor admin; 409 message already used for execution. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Messages"
],
"parameters": [
{
"name": "messageId",
"in": "path",
"required": true,
"description": "messageId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "updateTaskMessage",
"summary": "Update task message",
"description": "Workspace member with access to this resource.\n\nRequest: `content:string`, optional `attachment_ids:UUID[]`; the author or a workspace owner/admin.\n\nResponse: TaskMessageResponse.\n\nStatus: 200; 400 invalid content; 403 neither author nor admin. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Messages"
],
"parameters": [
{
"name": "messageId",
"in": "path",
"required": true,
"description": "messageId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "TaskMessageResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskMessageResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"attachment_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
}
},
"example": {
"content": "Updated note."
}
}
}
}
}
},
"/api/task-watches": {
"get": {
"operationId": "listTaskWatches",
"summary": "List task watches",
"description": "Active Run token for the subscribing Task.\n\nRequest: No body.\n\nResponse: `{watches:TaskWatchResponse[]}`. Lists this conversation's active watches for Tasks it can currently access, ordered by registration time and watch ID.\n\nStatus: 200; 403 no active Run; 409 closed subscriber. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{watches:TaskWatchResponse[]}`. Lists this conversation's active watches for Tasks it can currently access, ordered by registration time and watch ID.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"watches": {
"type": "array",
"items": {
"$ref": "#/components/schemas/taskWatchResponse"
}
}
},
"required": [
"watches"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks": {
"get": {
"operationId": "listTasks",
"summary": "List tasks",
"description": "Workspace member with access to this resource.\n\nRequest: Query: `limit?: integer`, `offset?: integer`, `area_id?: UUID`, `creator_id?: UUID`, `status?: string`, `include_closed?: boolean`, `open_only?: boolean`, `metadata?: JSON object`. `status=done` lists completed Tasks; other status values do not filter derived statuses. Default excludes closed Tasks. `include_closed=true` includes them; `open_only=true` bypasses pagination. Limit defaults to 100 and is capped at 100. Retired assignee/label/property filters return 400.\n\nResponse: `{tasks:TaskResponse[],total:integer}`.\n\nStatus: 200; 400 invalid filters. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "area_id",
"in": "query",
"description": "Optional area_id filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "creator_id",
"in": "query",
"description": "Optional creator_id filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "exclude_origin_type",
"in": "query",
"description": "Optional exclude_origin_type filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "include_closed",
"in": "query",
"description": "Optional include_closed filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Optional limit filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "metadata",
"in": "query",
"description": "Optional metadata filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"description": "Optional offset filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "open_only",
"in": "query",
"description": "Optional open_only filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "participated_only",
"in": "query",
"description": "Optional participated_only filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"description": "Optional sort filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "status",
"in": "query",
"description": "Optional status filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "top_level_only",
"in": "query",
"description": "Optional top_level_only filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{tasks:TaskResponse[],total:integer}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskResponse"
}
},
"total": {
"type": "integer"
}
},
"required": [
"tasks",
"total"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createTask",
"summary": "Create task",
"description": "Workspace member with access to this resource.\n\nRequest: `title?: string` (derived from nonempty input when omitted), `input?: string`, `description?: string|null`, `area_id?: UUID|null`, `parent_task_id?: UUID|null`, `attachment_ids?: UUID[]`, `client_request_id?: UUID`, `allow_duplicate?: boolean`, `callback_url?: HTTPS URL`, `execution?: {harness:string,model?:string,thinking_level?:string,service_tier?:string,max_attempts?:1}`, `start?: boolean` (`false` saves the Task and its input without running it; an autónomo's or an empresa's company otherwise runs input alone on its default execution, and refuses `area_id` or an execution other than that default with 400 `agents_only`), `isolated?: boolean` (default `false`, immutable; see [Isolated Tasks](/concepts/tasks-api#isolated-tasks)), `mcp_servers?: McpServerInput[]` (at most 10, stored before the first Run starts; workspace owners, admins and API keys only; see [Task MCP servers](/concepts/tasks-api#task-mcp-servers)). Execution requires nonempty input. Text fields must not contain NUL characters, and the JSON body is limited to 1 MiB. `origin_type`/`origin_id` are restricted to the authenticated source Run.\n\nResponse: TaskResponse with the same derived fields as `GET /api/tasks/{id}`, plus the initial `run_id` when a Run was created. A `client_request_id` replay returns the original Task in its current state and the same `run_id`; see [Idempotency](/api-reference/idempotency). The response never includes `mcp_servers`; read them with `GET /api/tasks/{id}/mcp-servers`.\n\nStatus: 201; 400 invalid input (`code: \"task_mcp_servers_invalid\"` for `mcp_servers`); 403 `code: \"task_mcp_servers_forbidden\"` when `mcp_servers` come from anyone but a workspace owner, admin or API key, Run tokens included; 413 body over 1 MiB or `mcp_servers` over 64 KiB sealed; 409 duplicate/idempotency/company/callback-secret conflict; 503 webhook signing or, with `mcp_servers`, the Secrets unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).\n\nCreation also accepts `metadata`, `instructions`, `repositories`, and `execution_identity_id`. The execution object accepts `funding_source` and `provider_account_id`; see the request schema and [Task context](/concepts/tasks-api#atomic-task-context). Requested execution funding that is unavailable returns `409` with `error: requested execution funding is unavailable`.",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "TaskResponse with the same derived fields as `GET /api/tasks/{id}`, plus the initial `run_id` when a Run was created. A `client_request_id` replay returns the original Task in its current state and the same `run_id`; see [Idempotency](/api-reference/idempotency). The response never includes `mcp_servers`; read them with `GET /api/tasks/{id}/mcp-servers`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Duplicate Task, conflicting retry payload, company/callback state, or requested execution funding is unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTaskRequestInput"
},
"example": {
"input": "Compare the build options.",
"execution": {
"harness": "codex"
}
}
}
}
}
}
},
"/api/tasks/batch-delete": {
"post": {
"operationId": "batchDeleteTasks",
"summary": "Batch delete tasks",
"description": "Workspace member with access to this resource.\n\nRequest: `task_ids:UUID[]`.\n\nResponse: `{deleted:integer}`.\n\nStatus: 200; 400 missing IDs. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{deleted:integer}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "integer"
}
},
"required": [
"deleted"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchDeleteTasksRequestInput"
},
"example": {
"task_ids": [
"00000000-0000-4000-8000-000000000001"
]
}
}
}
}
}
},
"/api/tasks/batch-update": {
"post": {
"operationId": "batchUpdateTasks",
"summary": "Batch update tasks",
"description": "Workspace member with access to this resource.\n\nRequest: `task_ids:UUID[]`, `updates:UpdateTaskRequest`.\n\nResponse: `{updated:integer}`.\n\nStatus: 200; 400 invalid update; 413 body over 1 MiB. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{updated:integer}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"updated": {
"type": "integer"
}
},
"required": [
"updated"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchUpdateTasksRequestInput"
},
"example": {
"task_ids": [
"00000000-0000-4000-8000-000000000001"
],
"updates": {
"status": "done"
}
}
}
}
}
}
},
"/api/tasks/child-progress": {
"get": {
"operationId": "childTaskProgress",
"summary": "Child task progress",
"description": "Workspace member with access to this resource.\n\nRequest: No body.\n\nResponse: `{progress:[{parent_task_id:UUID,total:integer,done:integer}]}`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{progress:[{parent_task_id:UUID,total:integer,done:integer}]}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"progress": {
"type": "array",
"items": {
"$ref": "#/components/schemas/progressEntry"
}
}
},
"required": [
"progress"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/children": {
"get": {
"operationId": "listChildrenByParents",
"summary": "List children by parents",
"description": "Workspace member with access to this resource.\n\nRequest: Query `parent_ids:string` is a comma-separated list of parent UUIDs.\n\nResponse: `{tasks:TaskResponse[]}`.\n\nStatus: 200; 400 too many/invalid parent IDs. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "parent_ids",
"in": "query",
"description": "Optional parent_ids filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{tasks:TaskResponse[]}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskResponse"
}
}
},
"required": [
"tasks"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/query": {
"post": {
"operationId": "queryTasks",
"summary": "Query tasks",
"description": "Workspace member with access to this resource.\n\nRequest: JSON object mapping GET filter names to **string** values (including numbers, booleans and encoded metadata).\n\nResponse: `{tasks:TaskResponse[],total:integer}`.\n\nStatus: 200; 400 invalid body/filters. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{tasks:TaskResponse[],total:integer}`.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}
},
"/api/tasks/search": {
"get": {
"operationId": "searchTasks",
"summary": "Search tasks",
"description": "Workspace member with access to this resource.\n\nRequest: Query: `q:string` required; `limit?:integer`, `offset?:integer`, `include_closed?:boolean`.\n\nResponse: `{tasks:SearchTaskResponse[],total:integer}`; each result includes Task fields and `match_source`, optional description/comment snippets.\n\nStatus: 200; 400 missing query; 503 search timeout. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "include_closed",
"in": "query",
"description": "Optional include_closed filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Optional limit filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"description": "Optional offset filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"description": "Optional q filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{tasks:SearchTaskResponse[],total:integer}`; each result includes Task fields and `match_source`, optional description/comment snippets.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchTaskResponse"
}
},
"total": {
"type": "integer"
}
},
"required": [
"tasks",
"total"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}": {
"delete": {
"operationId": "deleteTask",
"summary": "Delete task",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task ID. No body.\n\nResponse: Empty.\n\nStatus: 204. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"operationId": "getTask",
"summary": "Get task",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task ID. No body.\n\nResponse: TaskResponse with the same `status`, `has_active_run`, `has_pending_interaction`, `has_paused_run`, `attention_reason`, `failure_reason`, `failure_class`, `unread` and `pull_request` as the Task's list row, plus `attachments`. To see work start, input requests and failures as they happen, [stream the Task](/concepts/task-stream) instead of polling this route.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "TaskResponse with the same `status`, `has_active_run`, `has_pending_interaction`, `has_paused_run`, `attention_reason`, `failure_reason`, `failure_class`, `unread` and `pull_request` as the Task's list row, plus `attachments`. To see work start, input requests and failures as they happen, [stream the Task](/concepts/task-stream) instead of polling this route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "updateTask",
"summary": "Update task",
"description": "Workspace member with access to this resource.\n\nRequest: Optional `title:string`, `description:string|null`, `parent_task_id:UUID|null`, `area_id:UUID|null`, `attachment_ids:UUID[]`, `status:\"done\"|\"cancelled\"|\"reopen\"`. A sent `title` is trimmed and must not be blank; text fields must not contain NUL characters. The JSON body is limited to 1 MiB.\n\nResponse: TaskResponse with the same derived fields as `GET /api/tasks/{id}`.\n\nStatus: 200; 400 blank title or invalid lifecycle/relationship; 413 body over 1 MiB. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "TaskResponse with the same derived fields as `GET /api/tasks/{id}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTaskRequestInput"
},
"example": {
"status": "done"
}
}
}
}
}
},
"/api/tasks/{id}/attachments": {
"get": {
"operationId": "listAttachments",
"summary": "List attachments",
"description": "Workspace member with Task access. Run tokens can read only their own active Task attachments.\n\nRequest: Path: Task ID.\n\nResponse: AttachmentResponse array.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AttachmentResponse array.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttachmentResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/attention/dismiss": {
"post": {
"operationId": "dismissTaskAttention",
"summary": "Dismiss task attention",
"description": "Workspace member with access to this resource.\n\nRequest: No body.\n\nResponse: TaskResponse with the same derived fields as `GET /api/tasks/{id}`, no longer reporting the dismissed `run_failed`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "TaskResponse with the same derived fields as `GET /api/tasks/{id}`, no longer reporting the dismissed `run_failed`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/children": {
"get": {
"operationId": "listChildTasks",
"summary": "List child tasks",
"description": "Workspace member with access to this resource.\n\nRequest: Path: parent Task ID.\n\nResponse: `{tasks:TaskResponse[]}`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{tasks:TaskResponse[]}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskResponse"
}
}
},
"required": [
"tasks"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/execution": {
"get": {
"operationId": "getTaskExecution",
"summary": "Get task execution",
"description": "Human workspace member; rejects Run and MCP actors.\n\nRequest: Path: Task ID.\n\nResponse: `{execution:TaskExecutionSettings|null}`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{execution:TaskExecutionSettings|null}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/taskExecutionResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "setTaskExecution",
"summary": "Set task execution",
"description": "Human workspace member; rejects Run and MCP actors.\n\nRequest: `harness:string`, optional `model:string`, `thinking_level:string`, `service_tier:string`. `melso` selects Melso, which runs without a computer and takes no `thinking_level`; see [Harnesses and models](/concepts/provider-accounts#harnesses-and-models).\n\nResponse: `{execution:TaskExecutionSettings}`.\n\nStatus: 200; 400 invalid selection. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{execution:TaskExecutionSettings}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/taskExecutionResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskExecutionRequestInput"
},
"example": {
"harness": "codex"
}
}
}
}
}
},
"/api/tasks/{id}/input": {
"post": {
"operationId": "sendTaskInput",
"summary": "Send task input",
"description": "Workspace member with access to this resource.\n\nRequest: `content:string` required (not blank, no NUL characters), `attachment_ids?:UUID[]`, `client_request_id?:UUID`, `fresh_session?:boolean`, `max_attempts?:1`. Task path must be a UUID. The JSON body is limited to 1 MiB, and unknown fields are rejected.\n\nResponse: TaskInputResponse.\n\nStatus: 201, also for a replay; 400 blank or invalid content, an unknown field or a field of the wrong type, `max_attempts` other than 1, or a `client_request_id` that is not a UUID; 413 body over 1 MiB; 409 cancelled Task, missing execution settings, or a `client_request_id` already used with a different payload (`\"code\":\"client_request_conflict\"`). Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Messages"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "TaskInputResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskInputResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskInputRequestInput"
},
"example": {
"content": "Include operating costs.",
"client_request_id": "8b2f6c1e-4a7d-4f5e-9c3b-1d2e3f4a5b6c"
}
}
}
}
}
},
"/api/tasks/{id}/interactions": {
"get": {
"operationId": "listTaskInteractions",
"summary": "List task interactions",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task ID.\n\nResponse: InteractionRequestResponse array.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "InteractionRequestResponse array.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createTaskInteraction",
"summary": "Create task interaction",
"description": "Workspace member with access to this resource.\n\nRequest: `kind:\"clarification\"|\"approval\"`, `title?:string`, `message:string`, `payload:object`, `recipient_user_id?:UUID`, `parent_message_id?:UUID`, `expires_at?:RFC3339`.\n\nResponse: InteractionRequestResponse.\n\nStatus: 201 created; 200 existing request; 400 invalid payload; 403 invalid source Run. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "InteractionRequestResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/createInteractionRequestBodyInput"
},
"example": {
"kind": "approval",
"title": "Publish",
"message": "Publish the draft?",
"payload": {
"version": 1
}
}
}
}
}
}
},
"/api/tasks/{id}/interactions/{interactionId}": {
"get": {
"operationId": "getTaskInteraction",
"summary": "Get task interaction",
"description": "Workspace member with access to this resource.\n\nRequest: Path: interaction UUID (and Task ID for the scoped route).\n\nResponse: InteractionRequestResponse.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "interactionId",
"in": "path",
"required": true,
"description": "interactionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "InteractionRequestResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/interactions/{interactionId}/cancel": {
"post": {
"operationId": "cancelTaskInteraction",
"summary": "Cancel task interaction",
"description": "Respond/decline: the authenticated recipient, or a current workspace owner or admin. The responder is recorded and supplies authority for any continuation Run. Cancel: authorized member, or the original active source Run.\n\nRequest: `response:object` for respond; optional `audit_text:string`. Approval response uses `decision:\"approve_once\"|\"deny\"|\"decline\"`; clarification uses `answers:object` keyed by question IDs.\n\nResponse: InteractionRequestResponse.\n\nStatus: 200; 400 invalid answers; 403 actor/recipient mismatch; 409 already resolved or continuation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "interactionId",
"in": "path",
"required": true,
"description": "interactionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/interactions/{interactionId}/decline": {
"post": {
"operationId": "declineTaskInteraction",
"summary": "Decline task interaction",
"description": "Respond/decline: the authenticated recipient, or a current workspace owner or admin. The responder is recorded and supplies authority for any continuation Run. Cancel: authorized member, or the original active source Run.\n\nRequest: `response:object` for respond; optional `audit_text:string`. Approval response uses `decision:\"approve_once\"|\"deny\"|\"decline\"`; clarification uses `answers:object` keyed by question IDs.\n\nResponse: InteractionRequestResponse.\n\nStatus: 200; 400 invalid answers; 403 actor/recipient mismatch; 409 already resolved or continuation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "interactionId",
"in": "path",
"required": true,
"description": "interactionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/interactions/{interactionId}/respond": {
"post": {
"operationId": "respondTaskInteraction",
"summary": "Respond task interaction",
"description": "Respond/decline: the authenticated recipient, or a current workspace owner or admin. The responder is recorded and supplies authority for any continuation Run. Cancel: authorized member, or the original active source Run.\n\nRequest: `response:object` for respond; optional `audit_text:string`. Approval response uses `decision:\"approve_once\"|\"deny\"|\"decline\"`; clarification uses `answers:object` keyed by question IDs.\n\nResponse: InteractionRequestResponse.\n\nStatus: 200; 400 invalid answers; 403 actor/recipient mismatch; 409 already resolved or continuation conflict. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Interactions"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "interactionId",
"in": "path",
"required": true,
"description": "interactionId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InteractionRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/mcp-servers": {
"get": {
"operationId": "listTaskMcpServers",
"summary": "List task mcp servers",
"description": "Anyone who can read the Task, through a browser session, personal access token or workspace API key: the summary holds no values. Run tokens get 403, including a Run of this Task.\n\nRequest: Path: Task ID. No body.\n\nResponse: `{mcp_servers:McpServerSummary[]}` in the order they were set; `[]` when the Task has none. Header and env values are never returned. See [Task MCP servers](/concepts/tasks-api#task-mcp-servers).\n\nStatus: 200; 403 Run token (`code: \"isolated_task_scope\"` for a Run of an isolated Task). Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{mcp_servers:McpServerSummary[]}` in the order they were set; `[]` when the Task has none. Header and env values are never returned. See [Task MCP servers](/concepts/tasks-api#task-mcp-servers).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/taskMcpServersResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "replaceTaskMcpServers",
"summary": "Replace task mcp servers",
"description": "A workspace owner or admin (browser session or personal access token) or a workspace API key of the Task's workspace, who can also edit the Task with `PUT /api/tasks/{id}`. Other members get 403 `{error:\"only workspace owners, admins and API keys can set Task MCP servers\",code:\"task_mcp_servers_forbidden\"}`, also for `[]`. Run tokens get 403, including a Run of this Task.\n\nRequest: `{mcp_servers:McpServerInput[]}` (required) replaces the Task's whole set; `[]` removes every server. At most 10 servers. The JSON body is limited to 1 MiB and the sealed set to 64 KiB.\n\nResponse: `{mcp_servers:McpServerSummary[]}`: the new set, without header or env values.\n\nStatus: 200; 400 `{error:string,code:\"task_mcp_servers_invalid\"}`; 403 `code: \"task_mcp_servers_forbidden\"` for anyone but a workspace owner, admin or API key, or a Run token (`code: \"isolated_task_scope\"` for a Run of an isolated Task); 413 body over 1 MiB or set over 64 KiB sealed; 503 Secrets unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{mcp_servers:McpServerSummary[]}`: the new set, without header or env values.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/taskMcpServersResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replaceTaskMcpServersRequestInput"
}
}
}
}
}
},
"/api/tasks/{id}/messages": {
"get": {
"operationId": "listTaskMessages",
"summary": "List task messages",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task ID. No pagination.\n\nResponse: TaskMessageResponse array holding the oldest 2000 messages, oldest first. A longer conversation’s newest messages are missing here; read them from the page route below.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Messages"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "TaskMessageResponse array holding the oldest 2000 messages, oldest first. A longer conversation’s newest messages are missing here; read them from the page route below.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskMessageResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createTaskMessage",
"summary": "Create task message",
"description": "Workspace member with access to this resource.\n\nRequest: `content:string`, `attachment_ids?:UUID[]`.\n\nResponse: TaskMessageResponse. A member’s message reopens a completed Task but never starts a Run.\n\nStatus: 201; 400 empty content/invalid attachments; 409 cancelled Task. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Messages"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "TaskMessageResponse. A member’s message reopens a completed Task but never starts a Run.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskMessageResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTaskMessageRequestInput"
},
"example": {
"content": "For reference: the budget is approved."
}
}
}
}
}
},
"/api/tasks/{id}/messages/page": {
"get": {
"operationId": "listTaskMessagePage",
"summary": "List task message page",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task UUID. Query: `limit?:integer`, `before_created_at?:RFC3339Nano`, `before_id?:UUID` (cursor pair).\n\nResponse: TaskMessagesPageResponse; default limit 50, valid range 1–100, chronological order within each page. The first page, without a cursor, holds the newest messages. For older ones, pass `next_cursor.created_at` and `next_cursor.id` as `before_created_at` and `before_id` while `has_more` is true. Queued follow-ups that are not yet next in line are omitted.\n\nStatus: 200; 400 invalid limit or cursor. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Messages"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
},
"description": "Messages per page."
},
{
"name": "before_created_at",
"in": "query",
"schema": {
"type": "string",
"format": "date-time"
},
"description": "next_cursor.created_at from the previous page. Send with before_id."
},
{
"name": "before_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
},
"description": "next_cursor.id from the previous page. Send with before_created_at."
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "TaskMessagesPageResponse; default limit 50, valid range 1–100, chronological order within each page. The first page, without a cursor, holds the newest messages. For older ones, pass `next_cursor.created_at` and `next_cursor.id` as `before_created_at` and `before_id` while `has_more` is true. Queued follow-ups that are not yet next in line are omitted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskMessagesPageResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/metadata": {
"get": {
"operationId": "listTaskMetadata",
"summary": "List task metadata",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task ID.\n\nResponse: `{metadata:object}`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{metadata:object}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"metadata"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/metadata/{key}": {
"delete": {
"operationId": "deleteTaskMetadataKey",
"summary": "Delete task metadata key",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task ID and metadata key.\n\nResponse: `{metadata:object}`.\n\nStatus: 200; 400 invalid key; 403 reserved key. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "key",
"in": "path",
"required": true,
"description": "key from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{metadata:object}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"metadata"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "setTaskMetadataKey",
"summary": "Set task metadata key",
"description": "Workspace member with access to this resource.\n\nRequest: `value:string|number|boolean`; key is a bounded metadata key. Total metadata is limited to 8 KiB and 50 keys.\n\nResponse: `{metadata:object}`.\n\nStatus: 200; 400 invalid/oversized value; 403 reserved GitHub-review keys. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "key",
"in": "path",
"required": true,
"description": "key from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{metadata:object}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"metadata"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetTaskMetadataKeyRequestInput"
},
"example": {
"value": "ready"
}
}
}
}
}
},
"/api/tasks/{id}/mute": {
"post": {
"operationId": "muteTask",
"summary": "Mute task",
"description": "Human workspace member; Run and MCP actors rejected.\n\nRequest: `muted?:boolean` (defaults true).\n\nResponse: Empty.\n\nStatus: 204. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/muteTaskRequestInput"
},
"example": {
"muted": true
}
}
}
}
}
},
"/api/tasks/{id}/outputs": {
"get": {
"operationId": "listTaskOutputs",
"summary": "List task outputs",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task ID.\n\nResponse: `{artifacts:[{id,title,kind,file_name?}]}`. A Task's outputs are the completed Artifacts deployed from it or by its Runs, filtered by the caller's current Artifact access. `kind` is `file` (one delivered file, named by `file_name`) or `app`. Runs deliver files with `melso artifacts deploy `.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{artifacts:[{id,title,kind,file_name?}]}`. A Task's outputs are the completed Artifacts deployed from it or by its Runs, filtered by the caller's current Artifact access. `kind` is `file` (one delivered file, named by `file_name`) or `app`. Runs deliver files with `melso artifacts deploy `.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"artifacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskOutput"
}
}
},
"required": [
"artifacts"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/participation": {
"get": {
"operationId": "getTaskParticipation",
"summary": "Get task participation",
"description": "Human workspace member; Run/MCP actors rejected.\n\nRequest: No body.\n\nResponse: Participation state with `following:boolean`, `muted:boolean`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Participation state with `following:boolean`, `muted:boolean`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetTaskParticipationRow"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "setTaskParticipation",
"summary": "Set task participation",
"description": "Human workspace member; Run/MCP actors rejected.\n\nRequest: `following:boolean` required.\n\nResponse: `{following:boolean,muted:boolean}`.\n\nStatus: 200; 400 missing following. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{following:boolean,muted:boolean}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"following": {},
"muted": {}
},
"required": [
"following",
"muted"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"following": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
},
"example": {
"following": true
}
}
}
}
}
},
"/api/tasks/{id}/pull-requests": {
"get": {
"operationId": "listPullRequestsForTask",
"summary": "List pull requests for task",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task ID.\n\nResponse: `{pull_requests:GitHubPullRequestResponse[]}`.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{pull_requests:GitHubPullRequestResponse[]}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"pull_requests": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GitHubPullRequestResponse"
}
}
},
"required": [
"pull_requests"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/queue": {
"delete": {
"operationId": "clearTaskRunQueue",
"summary": "Clear task run queue",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task UUID.\n\nResponse: Empty.\n\nStatus: 204. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"operationId": "getTaskRunQueue",
"summary": "Get task run queue",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task UUID.\n\nResponse: TaskRunQueueResponse.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "TaskRunQueueResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskRunQueueResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/read": {
"post": {
"operationId": "markTaskRead",
"summary": "Mark task read",
"description": "Workspace member with access to this resource.\n\nRequest: No body.\n\nResponse: Empty.\n\nStatus: 204. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/rerun": {
"post": {
"operationId": "rerunTask",
"summary": "Rerun task",
"description": "Workspace member with access to this resource.\n\nRequest: `run_id:UUID`: historical source Run in this Task.\n\nResponse: RunResponse for the new attempt.\n\nStatus: 202; 400 invalid source; 403 execution denied. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"202": {
"description": "RunResponse for the new attempt.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RerunTaskRequestInput"
},
"example": {
"run_id": "00000000-0000-4000-8000-000000000001"
}
}
}
}
}
},
"/api/tasks/{id}/resume": {
"post": {
"operationId": "resumeTask",
"summary": "Resume task",
"description": "Human workspace member; rejects Run and MCP actors.\n\nRequest: Path: Task UUID. No execution override.\n\nResponse: RunResponse for the resumed successor, now `queued`.\n\nStatus: 200; 409 nothing resumable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "RunResponse for the resumed successor, now `queued`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/runs": {
"get": {
"operationId": "listRunsByTask",
"summary": "List runs by task",
"description": "Workspace member with access to this resource.\n\nRequest: Path: Task ID. No body.\n\nResponse: RunResponse array, newest first.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "RunResponse array, newest first.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RunResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/start": {
"post": {
"operationId": "startTaskRun",
"summary": "Start task run",
"description": "Human workspace member; rejects Run and MCP actors.\n\nRequest: Optional top-level `harness:string`, `model:string`, `thinking_level:string`, `service_tier:string` (TaskExecutionRequest). Cannot override `max_attempts`. Requires saved conversation instructions and an idle open Task.\n\nResponse: `{run:RunResponse,execution?:TaskExecutionSettings}`.\n\nStatus: 202; 400 no instructions/invalid selection; 409 not idle or no target. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"202": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/startTaskRunResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/startTaskRunRequestInput"
}
}
}
}
}
},
"/api/tasks/{id}/stream": {
"get": {
"operationId": "streamTask",
"summary": "Stream task",
"description": "Exactly as `GET /api/tasks/{id}`: workspace membership and Area access. A workspace API key streams Tasks of its own workspace only. A Run token of an [isolated Task](/concepts/tasks-api#isolated-tasks) streams only that Task, and a Run token of another Task never sees an isolated one.\n\nRequest: Path: Task UUID or identifier. Headers: `Last-Event-ID` (optional) resumes after that event. Query: `cursor` resumes like `Last-Event-ID` for clients that cannot set the header (the header wins); `from=start` replays the Task's history on a stream opened without a cursor (default `from=now`). A personal access token or browser session selects the workspace as on every route; a browser `EventSource`, which cannot set headers, uses `?workspace_id=` or `?workspace_slug=` with its session cookie.\n\nResponse: `200` with `Content-Type: text/event-stream`, `Cache-Control: no-cache, no-transform` and `X-Accel-Buffering: no`, then events until the server closes the stream.\n\nStatus: 200; 400 invalid cursor, a cursor issued for another Task, or an unknown `from`; 429 too many open streams or requests (honor `Retry-After`); 503 live updates unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors), with the same statuses `GET /api/tasks/{id}` returns.",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"in": "query",
"description": "Optional cursor filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "from",
"in": "query",
"description": "Optional from filter or control; see the operation contract.",
"schema": {
"type": "string",
"enum": [
"now",
"start"
],
"default": "now"
}
},
{
"name": "Last-Event-ID",
"in": "header",
"schema": {
"type": "string"
},
"description": "Resume cursor from the previous SSE event; takes precedence over cursor."
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Server-sent task events; see Task stream for the event contract.",
"content": {
"text/event-stream": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/timeline": {
"get": {
"operationId": "listTimeline",
"summary": "List timeline",
"description": "Workspace member with access to this resource.\n\nRequest: No pagination. Legacy `limit`, `before`, `after`, `around` queries are rejected.\n\nResponse: TimelineEntry array in ascending time order; comments and activities capped separately at 2000 each. `X-Timeline-Truncated` reports truncation.\n\nStatus: 200; 400 pagination unsupported. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "TimelineEntry array in ascending time order; comments and activities capped separately at 2000 each. `X-Timeline-Truncated` reports truncation.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TimelineEntry"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/usage": {
"get": {
"operationId": "getTaskUsage",
"summary": "Get task usage",
"description": "Workspace member with access to this resource.\n\nRequest: No body.\n\nResponse: Object of token counters: `total_input_tokens`, `total_output_tokens`, `total_cache_read_tokens`, `total_cache_write_tokens`, `cost_usd_ticks`, `uncosted_input_tokens`, `uncosted_output_tokens`, `uncosted_cache_read_tokens`, `uncosted_cache_write_tokens`, `run_count` (integers).\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Object of token counters: `total_input_tokens`, `total_output_tokens`, `total_cache_read_tokens`, `total_cache_write_tokens`, `cost_usd_ticks`, `uncosted_input_tokens`, `uncosted_output_tokens`, `uncosted_cache_read_tokens`, `uncosted_cache_write_tokens`, `run_count` (integers).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cost_usd_ticks": {
"type": "integer"
},
"run_count": {
"type": "integer"
},
"total_cache_read_tokens": {
"type": "integer"
},
"total_cache_write_tokens": {
"type": "integer"
},
"total_input_tokens": {
"type": "integer"
},
"total_output_tokens": {
"type": "integer"
},
"uncosted_cache_read_tokens": {
"type": "integer"
},
"uncosted_cache_write_tokens": {
"type": "integer"
},
"uncosted_input_tokens": {
"type": "integer"
},
"uncosted_output_tokens": {
"type": "integer"
}
},
"required": [
"cost_usd_ticks",
"run_count",
"total_cache_read_tokens",
"total_cache_write_tokens",
"total_input_tokens",
"total_output_tokens",
"uncosted_cache_read_tokens",
"uncosted_cache_write_tokens",
"uncosted_input_tokens",
"uncosted_output_tokens"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/tasks/{id}/watch": {
"delete": {
"operationId": "unwatchTask",
"summary": "Unwatch task",
"description": "Active Run token for the subscribing Task.\n\nRequest: No body. Path: watched Task UUID or identifier. Access to the watched Task is not required to remove this conversation's own watch; use its UUID if the Task has been deleted.\n\nResponse: `{task_id:UUID,status:\"cancelled\"}`. Repeating removal succeeds even when no active watch remains. It does not cancel the watched Task, its Runs, or human interactions.\n\nStatus: 200; 400 invalid identifier; 403 no active Run; 409 closed subscriber. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{task_id:UUID,status:\"cancelled\"}`. Repeating removal succeeds even when no active watch remains. It does not cancel the watched Task, its Runs, or human interactions.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"task_id": {
"type": "string"
}
},
"required": [
"status",
"task_id"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "watchTask",
"summary": "Watch task",
"description": "Active Run token for the subscribing Task, with access to the watched Task.\n\nRequest: `events?:string[]`, `instruction?:string` (at most 4000 UTF-8 bytes; no NUL). The body is limited to 16 KiB; unknown fields are rejected. Omitting `events` or sending an empty array selects `delivered`, `failed`, `needs_input`, `completed`, and `cancelled`. At most seven entries are accepted; duplicates are removed. Linked PR events `pr_checks_finished` and `pr_checks_passed` are opt-in. A Task can watch itself only for PR events.\n\nResponse: TaskWatchResponse. Repeating registration for the same subscriber and watched Task updates its events and instruction.\n\nStatus: 200 created or updated; 400 invalid body/events/instruction or lifecycle self-watch; 403 no active Run or missing access; 409 closed subscriber or watch owned by another execution owner. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Tasks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "TaskWatchResponse. Repeating registration for the same subscriber and watched Task updates its events and instruction.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/taskWatchResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/taskWatchRequestInput"
},
"example": {
"events": [
"delivered",
"failed",
"needs_input"
],
"instruction": "Read the result and continue this conversation."
}
}
}
}
}
},
"/api/tokens": {
"get": {
"operationId": "listPersonalAccessTokens",
"summary": "List personal access tokens",
"description": "Authenticated member; account-scoped.\n\nRequest: None.\n\nResponse: PersonalAccessTokenResponse array.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "PersonalAccessTokenResponse array.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonalAccessTokenResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createPersonalAccessToken",
"summary": "Create personal access token",
"description": "Authenticated member; account-scoped.\n\nRequest: `name:string`, `expires_in_days?:integer`; a positive value sets expiry, otherwise the token has no expiry.\n\nResponse: PersonalAccessTokenResponse plus one-time `token:string`.\n\nStatus: 201; 400 missing name or invalid JSON. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "PersonalAccessTokenResponse plus one-time `token:string`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePATResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePATRequestInput"
},
"example": {
"name": "Factory",
"expires_in_days": 90
}
}
}
}
}
},
"/api/tokens/{id}": {
"delete": {
"operationId": "revokePersonalAccessToken",
"summary": "Revoke personal access token",
"description": "Token-owning member.\n\nRequest: Path: token UUID.\n\nResponse: Empty.\n\nStatus: 204. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/upload-file": {
"post": {
"operationId": "uploadFile2",
"summary": "Upload file",
"description": "Authenticated member; associations require current workspace/Task access. Active Run tokens may upload only within their own Task.\n\nRequest: Multipart `file:binary` required. Optional `task_id:UUID`, `message_id:UUID`, `run_id:UUID`; each at most once. A workspace API key always creates an attachable workspace file; with a personal access token, send `X-Workspace-ID` to create one.\n\nResponse: AttachmentResponse with workspace context; otherwise `{id:string,url:string,filename:string}` for a user file.\n\nStatus: 200; 400 invalid multipart or a body over the 100 MiB cap; 403 missing permission; 503 storage unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Files"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "AttachmentResponse with workspace context; otherwise `{id:string,url:string,filename:string}` for a user file.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttachmentResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"task_id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"run_id": {
"type": "string"
}
},
"required": [
"file"
]
}
}
}
}
}
},
"/api/uploads/direct": {
"post": {
"operationId": "startDirectUpload",
"summary": "Start direct upload",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Files"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"headers": {},
"id": {
"type": "string"
},
"upload_url": {
"type": "string"
}
},
"required": [
"headers",
"id",
"upload_url"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/directUploadRequestInput"
}
}
}
}
}
},
"/api/uploads/direct/{id}/complete": {
"post": {
"operationId": "completeDirectUpload",
"summary": "Complete direct upload",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Files"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttachmentResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces": {
"get": {
"operationId": "listWorkspaces",
"summary": "List workspaces",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Companies"
],
"parameters": [
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkspaceResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}": {
"get": {
"operationId": "getWorkspace",
"summary": "Get workspace",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Companies"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/api-keys": {
"get": {
"operationId": "listWorkspaceAPIKeys",
"summary": "List workspace api keys",
"description": "Workspace owner or admin with a browser session or personal access token. Run tokens, MCP credentials and workspace API keys receive `403`.\n\nRequest: Path: workspace UUID.\n\nResponse: `{keys: WorkspaceAPIKeyResponse[]}` with every key that is not revoked, newest first. Expired keys stay listed until revoked.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{keys: WorkspaceAPIKeyResponse[]}` with every key that is not revoked, newest first. Expired keys stay listed until revoked.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"keys": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkspaceAPIKeyResponse"
}
}
},
"required": [
"keys"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createWorkspaceAPIKey",
"summary": "Create workspace api key",
"description": "Company owner or admin using a browser session or personal access token in an Agents company. Other company types receive `403` with `code: agents_only`. Company API keys, Run tokens and MCP grants cannot create keys.\n\nRequest: `name:string` (1–120 characters), `expires_in_days?:integer` from 1 to 3650 (omit it for a key that never expires), `scope?:\"tasks\"|\"admin\"` (default `tasks`; see [Credential types](/api-reference/authentication#credential-types)). The scope never changes.\n\nResponse: `{key: WorkspaceAPIKeyResponse, token: string}`. `token` (`mwk_…`) is returned only here; Melso stores its hash.\n\nStatus: 201; 400 invalid name, expiry, scope or JSON; 429 when key creation is rate limited. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "`{key: WorkspaceAPIKeyResponse, token: string}`. `token` (`mwk_…`) is returned only here; Melso stores its hash.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"key": {
"$ref": "#/components/schemas/WorkspaceAPIKeyResponse"
},
"token": {
"type": "string"
}
},
"required": [
"key",
"token"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Agents company required (agents_only), or credential/role denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkspaceAPIKeyRequestInput"
},
"example": {
"name": "Production",
"expires_in_days": 90
}
}
}
}
}
},
"/api/workspaces/{id}/api-keys/{keyId}": {
"delete": {
"operationId": "revokeWorkspaceAPIKey",
"summary": "Revoke workspace api key",
"description": "As for listing keys.\n\nRequest: Path: workspace UUID and key UUID.\n\nResponse: Empty. The key stops working on its next request; revoking a revoked or unknown key is a no-op. Provider API keys saved in its funding policy are deleted; the rest of that policy stays. Its Tasks keep their attribution, and Runs already executing finish.\n\nStatus: 204. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "keyId",
"in": "path",
"required": true,
"description": "keyId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty. The key stops working on its next request; revoking a revoked or unknown key is a no-op. Provider API keys saved in its funding policy are deleted; the rest of that policy stays. Its Tasks keep their attribution, and Runs already executing finish."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/api-keys/{keyId}/rotate": {
"post": {
"operationId": "rotateWorkspaceAPIKey",
"summary": "Rotate workspace api key",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "keyId",
"in": "path",
"required": true,
"description": "keyId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"key": {
"$ref": "#/components/schemas/WorkspaceAPIKeyResponse"
},
"token": {
"type": "string"
}
},
"required": [
"key",
"token"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/github/connect": {
"get": {
"operationId": "gitHubConnect",
"summary": "Git hub connect",
"description": "Human workspace member; Run/MCP actors rejected.\n\nRequest: Optional query `return_to:\"github\"|\"repositories\"|\"chat\"`, the page GitHub returns to. Optional `mode:\"install\"` opens GitHub's installation page to add another account instead of finding existing installations.\n\nResponse: `{configured:boolean,url?:string,error?:string}`. Open `url` in the member's browser; it expires with its one-use state after 10 minutes.\n\nStatus: 200; 400 invalid return target or mode; 403 human member required. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "mode",
"in": "query",
"description": "Optional mode filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "return_to",
"in": "query",
"description": "Optional return_to filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{configured:boolean,url?:string,error?:string}`. Open `url` in the member's browser; it expires with its one-use state after 10 minutes.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GitHubConnectResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/github/connect/candidates": {
"get": {
"operationId": "listGitHubConnectCandidates",
"summary": "List git hub connect candidates",
"description": "The human workspace member who authorized on GitHub.\n\nRequest: Query `state:string`, the `github_choose` value GitHub returned to the page.\n\nResponse: `{candidates:{installation_id:integer,account_login:string,account_type:string,account_avatar_url?:string}[],return_to:string}`. The user authorization proof stays on the server.\n\nStatus: 200; 400 invalid state; 403 human member required; 404 no pending choice. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "state",
"in": "query",
"description": "Optional state filter or control; see the operation contract.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{candidates:{installation_id:integer,account_login:string,account_type:string,account_avatar_url?:string}[],return_to:string}`. The user authorization proof stays on the server.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GitHubConnectCandidatesResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/github/connect/complete": {
"post": {
"operationId": "completeGitHubConnect",
"summary": "Complete git hub connect",
"description": "The human workspace member who authorized on GitHub.\n\nRequest: `{state:string,installation_ids:integer[]}`, installations from the pending choice.\n\nResponse: Empty.\n\nStatus: 204; 400 installation outside the choice; 403 access revoked; 404 no pending choice; 409 the choice expired or an installation changed. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/completeGitHubConnectRequestInput"
}
}
}
}
}
},
"/api/workspaces/{id}/github/installations": {
"get": {
"operationId": "listGitHubInstallations",
"summary": "List git hub installations",
"description": "Workspace member with access to this resource.\n\nRequest: Path: workspace UUID.\n\nResponse: `{installations:GitHubInstallationResponse[],can_manage:boolean,configured:boolean,repository_browse_configured:boolean,configuration_error:string}`; only the current member’s connections are included. `has_shared_repositories:boolean` reports usable repositories without exposing other members’ connections. `can_manage` is true for human members and false for machine credentials.\n\nStatus: 200; 503 GitHub authorization unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{installations:GitHubInstallationResponse[],can_manage:boolean,configured:boolean,repository_browse_configured:boolean,configuration_error:string}`; only the current member’s connections are included. `has_shared_repositories:boolean` reports usable repositories without exposing other members’ connections. `can_manage` is true for human members and false for machine credentials.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"can_manage": {},
"configuration_error": {
"type": "string"
},
"configured": {},
"has_shared_repositories": {
"type": "boolean"
},
"installations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GitHubInstallationResponse"
}
},
"personal_area_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"repository_browse_configured": {}
},
"required": [
"can_manage",
"configuration_error",
"configured",
"has_shared_repositories",
"installations",
"personal_area_id",
"repository_browse_configured"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/github/installations/{installationId}": {
"delete": {
"operationId": "deleteGitHubInstallation",
"summary": "Delete git hub installation",
"description": "The human member who owns the connection.\n\nRequest: Path: workspace and installation record IDs.\n\nResponse: Empty.\n\nStatus: 204; 404 no connection owned by this member matches the installation. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "installationId",
"in": "path",
"required": true,
"description": "installationId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/github/installations/{installationId}/repositories": {
"get": {
"operationId": "listGitHubInstallationRepositories",
"summary": "List git hub installation repositories",
"description": "The human member who owns the connection.\n\nRequest: Path: workspace and installation record UUIDs. Query `page?:integer` (default 1), `per_page?:integer` (default/max 100).\n\nResponse: `{repositories:GitHubRepositoryResponse[],total_count:integer,next_page:integer|null}`.\n\nStatus: 200; 403 reconnect required; 404 installation mismatch; 502 GitHub request failed; 503 GitHub unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "installationId",
"in": "path",
"required": true,
"description": "installationId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{repositories:GitHubRepositoryResponse[],total_count:integer,next_page:integer|null}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GitHubRepositoriesResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/github/personal-repositories": {
"post": {
"operationId": "addPersonalGitHubRepositories",
"summary": "Add personal git hub repositories",
"description": "Human workspace member.\n\nRequest: `{urls:string[]}`; 1–100 GitHub repository URLs the member can access through their own connection.\n\nResponse: Empty. Creates or reuses the member's private **My repositories** Area and adds the repositories atomically. Repeating the request is safe.\n\nStatus: 204; 400 invalid input; 403 machine credential; 422 GitHub access could not be verified.",
"tags": [
"GitHub"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty. Creates or reuses the member's private **My repositories** Area and adds the repositories atomically. Repeating the request is safe."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"urls": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
}
},
"/api/workspaces/{id}/members": {
"get": {
"operationId": "listMembersWithUser",
"summary": "List members with user",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"Companies"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MemberWithUserResponse"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/private-network": {
"delete": {
"operationId": "deleteWorkspacePrivateNetwork",
"summary": "Delete workspace private network",
"description": "Workspace owner/admin (a person), or an admin API key.\n\nRequest: None.\n\nResponse: Empty.\n\nStatus: 204; 403 as for `PUT`. Runs already connected keep their device until they end. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Private network"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"get": {
"operationId": "getWorkspacePrivateNetwork",
"summary": "Get workspace private network",
"description": "Workspace member (a person), or an admin API key.\n\nRequest: None.\n\nResponse: `{private_network:PrivateNetwork|null}`, where `null` means none is connected. `PrivateNetwork` is `{provider:\"tailscale\"|\"headscale\",enabled:boolean,client_id:string,tags:string[],login_server:string,accept_routes:boolean,accept_dns:boolean,generation:integer,configured_by:UUID,configured_at:timestamp,verified_at:timestamp|null,last_error:string}`. `client_id` and `tags` apply to Tailscale, `login_server` to Headscale. `verified_at` is the last successful check (null until one succeeds); `last_error` the last failure.\n\nStatus: 200; 403 `this endpoint is only available to human actors` for a credential that is neither a person's nor an admin API key, and `workspace_key_scope` for a `tasks` API key. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Private network"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{private_network:PrivateNetwork|null}`, where `null` means none is connected. `PrivateNetwork` is `{provider:\"tailscale\"|\"headscale\",enabled:boolean,client_id:string,tags:string[],login_server:string,accept_routes:boolean,accept_dns:boolean,generation:integer,configured_by:UUID,configured_at:timestamp,verified_at:timestamp|null,last_error:string}`. `client_id` and `tags` apply to Tailscale, `login_server` to Headscale. `verified_at` is the last successful check (null until one succeeds); `last_error` the last failure.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/privateNetworkResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "putWorkspacePrivateNetwork",
"summary": "Put workspace private network",
"description": "Workspace owner/admin (a person), or an admin API key. `configured_by` is then the key's identity.\n\nRequest: For Tailscale: `provider:\"tailscale\"`, `client_id:string`, `client_secret?:string` (starts with `tskey-client-`), `tags:string[]` (1–20 tags, each matching `tag:[a-zA-Z][a-zA-Z0-9-]*`), `accept_routes?:boolean`, `accept_dns?:boolean`, `enabled?:boolean`. For Headscale: `provider:\"headscale\"`, `login_server:string` (an `https://` origin with no path, credentials, query or fragment), `auth_key?:string` (20–512 characters, no whitespace), `accept_routes?:boolean`, `accept_dns?:boolean`, `enabled?:boolean`. Leaving out `client_secret` or `auth_key` keeps the stored one while the provider stays the same; switching provider needs a new one. A left-out switch keeps its saved value, and is on for a new network. Every save increments `generation`.\n\nResponse: The `GET` shape.\n\nStatus: 200; 400 `private_network_invalid` (a field failed validation; `error` names it); 403 `insufficient permissions` for a member who is not an owner or admin, `this endpoint is only available to human actors` for a credential that is neither a person's nor an admin API key, or `workspace_key_scope` for a `tasks` API key; 422 `private_network_rejected` (Tailscale refused the OAuth client, or could not be reached to check it; nothing changed); 503 when the server has no Secrets keyring to seal the secret. A Tailscale save that changes the provider, client ID, secret or tags is checked first: Melso mints a one-minute, single-use key for the tags with the OAuth client and deletes it at once. Saving the same credential again, for example to turn the network on or off, does not check it again. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Private network"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The `GET` shape.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/privateNetworkResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateInput"
}
}
}
}
}
},
"/api/workspaces/{id}/webhooks": {
"get": {
"operationId": "listOutboundWebhookEndpoints",
"summary": "List outbound webhook endpoints",
"description": "Human workspace owner/admin; Run and MCP actors rejected.\n\nRequest: None.\n\nResponse: `{id:UUID,workspace_id:UUID,url:string,description:string,event_types:string[],enabled:boolean,created_at:timestamp}` array.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{id:UUID,workspace_id:UUID,url:string,description:string,event_types:string[],enabled:boolean,created_at:timestamp}` array.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OutboundWebhookEndpoint"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"operationId": "createOutboundWebhookEndpoint",
"summary": "Create outbound webhook endpoint",
"description": "Human workspace owner/admin; Run and MCP actors rejected.\n\nRequest: `url:HTTPS URL`, `event_types:string[]` (1–5 supported event names), `description?:string` (max 500), `enabled?:boolean` (default true).\n\nResponse: `{endpoint:Endpoint,signing_secret?:string}`; secret only when first initialized.\n\nStatus: 201; 400 URL/DNS/events invalid; 503 signing key unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "`{endpoint:Endpoint,signing_secret?:string}`; secret only when first initialized.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"endpoint": {
"$ref": "#/components/schemas/OutboundWebhookEndpoint"
},
"signing_secret": {
"type": "string"
}
},
"required": [
"endpoint"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/outboundEndpointRequestInput"
},
"example": {
"url": "https://receiver.example.com/melso",
"description": "Factory",
"event_types": [
"task.delivered",
"task.needs_input",
"task.failed",
"task.completed",
"task.cancelled"
]
}
}
}
}
}
},
"/api/workspaces/{id}/webhooks/deliveries": {
"get": {
"operationId": "listOutboundWebhookDeliveries",
"summary": "List outbound webhook deliveries",
"description": "Human workspace owner/admin; Run and MCP actors rejected.\n\nRequest: None. Latest 100 deliveries.\n\nResponse: Array of `{id,event_id,endpoint_id:UUID|null,url,status,attempts,response_code:integer|null,latency_ms:integer|null,response_body,error,created_at,next_attempt_at,payload}`. IDs are UUID strings, attempts is an integer; time fields are timestamps. Status is pending/delivering/succeeded/failed/disabled.\n\nStatus: 200. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Array of `{id,event_id,endpoint_id:UUID|null,url,status,attempts,response_code:integer|null,latency_ms:integer|null,response_body,error,created_at,next_attempt_at,payload}`. IDs are UUID strings, attempts is an integer; time fields are timestamps. Status is pending/delivering/succeeded/failed/disabled.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/webhooks/deliveries/{deliveryId}/resend": {
"post": {
"operationId": "resendOutboundWebhookDelivery",
"summary": "Resend outbound webhook delivery",
"description": "Human workspace owner/admin; Run and MCP actors rejected.\n\nRequest: Path: delivery UUID.\n\nResponse: `{status:\"pending\"}`.\n\nStatus: 202; 409 absent, disabled, or currently leased delivery. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "deliveryId",
"in": "path",
"required": true,
"description": "deliveryId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"202": {
"description": "`{status:\"pending\"}`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string"
}
},
"required": [
"status"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/webhooks/signing-secret/rotate": {
"post": {
"operationId": "rotateOutboundWebhookSecret",
"summary": "Rotate outbound webhook secret",
"description": "Human workspace owner/admin; Run and MCP actors rejected.\n\nRequest: No body. Also initializes a signing key for callback-only use.\n\nResponse: `{signing_secret:string}` shown once.\n\nStatus: 200; 503 signing key unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{signing_secret:string}` shown once.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"signing_secret": {
"type": "string"
}
},
"required": [
"signing_secret"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/workspaces/{id}/webhooks/{endpointId}": {
"delete": {
"operationId": "deleteOutboundWebhookEndpoint",
"summary": "Delete outbound webhook endpoint",
"description": "Human workspace owner/admin; Run and MCP actors rejected.\n\nRequest: Path: endpoint UUID.\n\nResponse: Empty.\n\nStatus: 204; 404 missing endpoint. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "endpointId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Empty."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"operationId": "updateOutboundWebhookEndpoint",
"summary": "Update outbound webhook endpoint",
"description": "Human workspace owner/admin; Run and MCP actors rejected.\n\nRequest: Same fields as creation; full replacement. `enabled` defaults true when omitted.\n\nResponse: `{id:UUID,workspace_id:UUID,url:string,description:string,event_types:string[],enabled:boolean,created_at:timestamp}`.\n\nStatus: 200; 400 invalid URL/events; 404 missing endpoint. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "endpointId",
"in": "path",
"required": true,
"description": "endpointId from the corresponding authorized response.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-ID",
"in": "header",
"required": false,
"description": "Company UUID for a personal token on company-scoped operations. A company API key already binds its company.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "`{id:UUID,workspace_id:UUID,url:string,description:string,event_types:string[],enabled:boolean,created_at:timestamp}`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OutboundWebhookEndpoint"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/outboundEndpointRequestInput"
},
"example": {
"url": "https://receiver.example.com/melso",
"event_types": [
"task.delivered"
],
"enabled": false
}
}
}
}
}
},
"/mcp": {
"post": {
"operationId": "handleMCP2",
"summary": "Handle mcp",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"MCP"
],
"parameters": [],
"responses": {
"200": {
"description": "JSON-RPC response or an SSE stream for streaming clients.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jsonrpc": {
"type": "string",
"const": "2.0"
},
"id": {},
"result": {},
"error": {
"type": "object",
"properties": {
"code": {
"type": "integer"
},
"message": {
"type": "string"
},
"data": {}
}
}
},
"required": [
"jsonrpc"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"202": {
"description": "Notification accepted; no response body."
}
},
"security": [
{
"mcpOAuth": [
"mcp:tools"
]
},
{
"runToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/mcpRPCRequestInput"
}
}
}
}
}
},
"/mcp/upload-file": {
"post": {
"operationId": "uploadFile3",
"summary": "Upload file",
"description": "MCP OAuth token; acts in its granted workspace. Run credentials retain their Task scope.\n\nRequest: Multipart `file:binary` required; same size limit (under 100 MiB per request on melso.ai and mcp.melso.ai) and optional Task/message/Run association fields as POST /api/upload-file in [Tasks](/concepts/tasks-api). Upload each file separately.\n\nResponse: AttachmentResponse (see Tasks). Pass returned IDs as `attachment_ids:UUID[]` to `tasks_create` or `tasks_send`.\n\nStatus: 200; 400 invalid upload; 403 denied; 503 storage unavailable. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"MCP"
],
"parameters": [],
"responses": {
"200": {
"description": "AttachmentResponse (see Tasks). Pass returned IDs as `attachment_ids:UUID[]` to `tasks_create` or `tasks_send`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttachmentResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"mcpOAuth": [
"mcp:tools"
]
},
{
"runToken": []
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"task_id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"run_id": {
"type": "string"
}
},
"required": [
"file"
]
}
}
}
}
}
},
"/mcp/upload-secret": {
"post": {
"operationId": "uploadVaultFile2",
"summary": "Upload vault file",
"description": "Authenticated member; company membership and credential scope apply.",
"tags": [
"MCP"
],
"parameters": [],
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"item": {}
},
"required": [
"item"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"mcpOAuth": [
"mcp:tools"
]
},
{
"runToken": []
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"env_name": {
"type": "string"
},
"share": {
"type": "string"
},
"area_ids": {
"type": "string"
}
},
"required": [
"file"
]
}
}
}
}
}
},
"/mcp/upload-skill": {
"post": {
"operationId": "uploadMCPSkill2",
"summary": "Upload mcp skill",
"description": "MCP OAuth token or Run credential; acts in its workspace. Also served at `/api/mcp/upload-skill`.\n\nRequest: Multipart `file:binary` required: a `.zip` or `.skill` archive of one skill folder with its `SKILL.md`, scripts and binary files. Optional `on_conflict`: `fail` (default), `overwrite`, `rename` or `skip`.\n\nResponse: `{status:\"created\"|\"updated\"|\"skipped\"|\"conflict\"|\"failed\",reason?:string,skill?:SkillResponse,existing_skill?:{id,name}}`.\n\nStatus: 201 created; 200 updated or skipped; 400 not a multipart archive; 403 denied; 409 a skill with that name exists; 413 too large. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"MCP"
],
"parameters": [],
"responses": {
"201": {
"description": "New Skill imported.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillImportResult"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Credential, company or resource access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource unavailable to this caller.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limited; respect Retry-After when present.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Request failed; see the operation contract for the condition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"200": {
"description": "Imported Skill result; conflict handling can return an existing Skill.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillImportResult"
}
}
}
}
},
"security": [
{
"mcpOAuth": [
"mcp:tools"
]
},
{
"runToken": []
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"scope": {
"type": "string"
},
"area_ids": {
"type": "string"
},
"on_conflict": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"file"
]
}
}
}
}
}
},
"/oauth/register": {
"post": {
"operationId": "registerMCPOAuthClient",
"summary": "Register mcpo auth client",
"description": "Public dynamic client registration.\n\nRequest: `client_name:string` (1–200), `redirect_uris:string[]` (1–10), optional `grant_types:string[]`, `token_endpoint_auth_method:\"none\"`.\n\nResponse: Registered client metadata with `client_id`; no client secret.\n\nStatus: 201; 400 invalid metadata; 429 rate limited. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"201": {
"description": "Registered client metadata with `client_id`; no client secret.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"client_id": {
"type": "string"
},
"client_name": {
"type": "string"
},
"grant_types": {
"type": "array",
"items": {
"type": "string"
}
},
"redirect_uris": {},
"response_types": {
"type": "array",
"items": {
"type": "string"
}
},
"token_endpoint_auth_method": {
"type": "string"
}
},
"required": [
"client_id",
"client_name",
"grant_types",
"redirect_uris",
"response_types",
"token_endpoint_auth_method"
]
}
}
}
},
"400": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"403": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"429": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"500": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
}
},
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/mcpOAuthRegisterRequestInput"
},
"example": {
"client_name": "Factory",
"redirect_uris": [
"http://127.0.0.1:8080/callback"
],
"token_endpoint_auth_method": "none"
}
}
}
}
}
},
"/oauth/revoke": {
"post": {
"operationId": "revokeMCPOAuthToken",
"summary": "Revoke mcpo auth token",
"description": "Token holder.\n\nRequest: Form-urlencoded `token:string`.\n\nResponse: Empty.\n\nStatus: 200; 400 missing token. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"200": {
"description": "Revocation processed; empty response."
},
"400": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"403": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"429": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"500": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
}
},
"security": [],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
},
"required": [
"token"
]
}
}
}
}
}
},
"/oauth/token": {
"post": {
"operationId": "exchangeMCPOAuthToken",
"summary": "Exchange mcpo auth token",
"description": "OAuth client with valid code/verifier or refresh token.\n\nRequest: Form-urlencoded: authorization code grant uses `grant_type=authorization_code`, `client_id`, `code`, `redirect_uri`, `code_verifier`, resource as required by the grant. Refresh uses `grant_type=refresh_token`, `client_id`, `refresh_token`.\n\nResponse: `{access_token:string,refresh_token:string,token_type:\"Bearer\",expires_in:integer,scope:string}`.\n\nStatus: 200; 400 invalid grant; 429 rate limited. Authentication and resource-access errors follow [Overview](/api-reference/errors).",
"tags": [
"OAuth"
],
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"token_type": {
"type": "string",
"const": "Bearer"
},
"expires_in": {
"type": "integer"
},
"refresh_token": {
"type": "string"
},
"scope": {
"type": "string"
}
},
"required": [
"access_token",
"token_type",
"expires_in",
"refresh_token",
"scope"
]
}
}
}
},
"400": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"403": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"429": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
},
"500": {
"description": "OAuth request failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}
}
},
"security": [],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"grant_type": {
"type": "string"
},
"code": {
"type": "string"
},
"redirect_uri": {
"type": "string"
},
"client_id": {
"type": "string"
},
"code_verifier": {
"type": "string"
},
"refresh_token": {
"type": "string"
},
"resource": {
"type": "string"
}
},
"required": [
"grant_type"
]
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Company API key (mwk_) or personal access token (mel_). A PAT requires X-Workspace-ID on company-scoped routes. An API key implies its own company."
},
"runToken": {
"type": "http",
"scheme": "bearer",
"description": "Active Run token; execution-scoped permissions apply."
},
"mcpOAuth": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://app.melso.ai/oauth/authorize",
"tokenUrl": "https://melso.ai/oauth/token",
"scopes": {
"mcp:tools": "Call the tools available in the company selected at consent."
}
}
}
}
},
"schemas": {
"Account": {
"type": "object",
"properties": {
"is_owner": {
"type": "boolean"
},
"owner_name": {
"type": "string"
},
"shared_workspaces": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SharedWorkspace"
}
},
"is_default": {
"type": "boolean"
},
"id": {
"type": "string"
},
"provider": {
"type": "string"
},
"identity_key": {
"type": "string"
},
"tenant_key": {
"type": "string"
},
"label": {
"type": "string"
},
"email": {
"type": "string"
},
"plan": {
"type": "string"
},
"credential_version": {
"type": "integer"
},
"enabled": {
"type": "boolean"
},
"health": {
"type": "string"
},
"usage_status": {
"type": "string"
},
"usage_windows": {},
"usage_captured_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"is_owner",
"owner_name",
"shared_workspaces",
"is_default",
"id",
"provider",
"identity_key",
"tenant_key",
"label",
"email",
"credential_version",
"enabled",
"health",
"usage_status",
"usage_windows",
"usage_captured_at"
]
},
"AreaAccessMember": {
"type": "object",
"properties": {
"member_id": {
"type": "string"
},
"user_id": {
"type": "string"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"avatar_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string"
},
"workspace_role": {
"type": "string"
},
"explicit": {
"type": "boolean"
}
},
"required": [
"member_id",
"user_id",
"name",
"email",
"avatar_url",
"role",
"workspace_role",
"explicit"
]
},
"AreaAccessRequestInput": {
"type": "object",
"properties": {
"visibility": {
"type": "string"
},
"member_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"AreaAccessResponse": {
"type": "object",
"properties": {
"visibility": {
"type": "string"
},
"member_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"members": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AreaAccessMember"
}
},
"can_manage": {
"type": "boolean"
}
},
"required": [
"visibility",
"member_ids",
"members",
"can_manage"
]
},
"AreaConnectionResponse": {
"type": "object",
"properties": {
"area_id": {
"type": "string"
},
"connection_kind": {
"type": "string"
},
"connection_ref": {
"type": "string"
},
"owner_user_id": {
"type": "string"
},
"visibility": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string"
}
},
"required": [
"area_id",
"connection_kind",
"connection_ref",
"owner_user_id",
"visibility",
"enabled",
"created_at"
]
},
"AreaRecipe": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"area_key": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"prompt": {
"type": "string"
},
"schedule": {
"$ref": "#/components/schemas/AreaRecipeSchedule"
},
"prerequisites": {
"$ref": "#/components/schemas/AreaRecipePrerequisites"
},
"installed": {
"type": "boolean"
},
"installed_automation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"installed_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"key",
"area_key",
"title",
"description",
"prompt",
"schedule",
"prerequisites",
"installed"
]
},
"AreaRecipeExecutionResponse": {
"type": "object",
"properties": {
"area_id": {
"type": "string"
},
"harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"thinking_level": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"area_id",
"harness",
"model",
"thinking_level",
"service_tier"
]
},
"AreaRecipePrerequisites": {
"type": "object",
"properties": {
"connected_apps": {
"type": "array",
"items": {
"type": "string"
}
},
"area_resources": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"connected_apps",
"area_resources"
]
},
"AreaRecipeSchedule": {
"type": "object",
"properties": {
"cron_expression": {
"type": "string"
},
"timezone": {
"type": "string"
}
},
"required": [
"cron_expression",
"timezone"
]
},
"AreaResourceResponse": {
"type": "object",
"properties": {
"company_commit_sha": {
"type": "string"
},
"id": {
"type": "string"
},
"area_id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"resource_type": {
"type": "string"
},
"resource_ref": {},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"position": {
"type": "integer"
},
"created_at": {
"type": "string"
},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"company_commit_sha",
"id",
"area_id",
"workspace_id",
"resource_type",
"resource_ref",
"label",
"position",
"created_at",
"created_by"
]
},
"AreaResponse": {
"type": "object",
"properties": {
"company_commit_sha": {
"type": "string"
},
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"icon": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sandbox_size": {
"type": "string"
},
"visibility": {
"type": "string"
},
"key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sort_order": {
"type": "integer"
},
"default_harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"default_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"default_thinking_level": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"default_service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"instructions": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"resource_count": {
"type": "integer"
}
},
"required": [
"company_commit_sha",
"id",
"workspace_id",
"title",
"description",
"icon",
"sandbox_size",
"visibility",
"key",
"sort_order",
"default_harness",
"default_model",
"default_thinking_level",
"default_service_tier",
"instructions",
"created_at",
"updated_at",
"resource_count"
]
},
"AttachmentResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"uploader_type": {
"type": "string"
},
"uploader_id": {
"type": "string"
},
"filename": {
"type": "string"
},
"url": {
"type": "string"
},
"download_url": {
"type": "string"
},
"attachment_download_url": {
"type": "string"
},
"markdown_url": {
"type": "string"
},
"content_type": {
"type": "string"
},
"size_bytes": {
"type": "integer"
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"workspace_id",
"task_id",
"message_id",
"run_id",
"uploader_type",
"uploader_id",
"filename",
"url",
"download_url",
"markdown_url",
"content_type",
"size_bytes",
"created_at"
]
},
"AttributionUser": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"avatar_url": {
"type": "string"
}
},
"required": [
"id"
]
},
"AuthSession": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"provider": {
"type": "string"
},
"status": {
"type": "string"
},
"prompt": {
"$ref": "#/components/schemas/Prompt"
},
"account_id": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"provider",
"status",
"prompt",
"expires_at"
]
},
"AutomationCollaboratorEntry": {
"type": "object",
"properties": {
"user_type": {
"type": "string"
},
"user_id": {
"type": "string"
},
"granted_by": {
"type": "string"
},
"created_at": {
"type": "string"
}
},
"required": [
"user_type",
"user_id",
"granted_by",
"created_at"
]
},
"AutomationCollaboratorRequestInput": {
"type": "object",
"properties": {
"user_id": {
"type": "string"
}
}
},
"AutomationInvocationResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"automation_id": {
"type": "string"
},
"trigger_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source": {
"type": "string"
},
"status": {
"type": "string"
},
"task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"triggered_at": {
"type": "string"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"failure_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reason_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"trigger_payload": {},
"result": {},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"automation_id",
"trigger_id",
"source",
"status",
"task_id",
"run_id",
"triggered_at",
"completed_at",
"failure_reason",
"trigger_payload",
"result",
"created_at"
]
},
"AutomationResponse": {
"type": "object",
"properties": {
"company_commit_sha": {
"type": "string"
},
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"area_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"thinking_level": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source_recipe_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"execution_owner_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
"pause_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"task_title_template": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_by_type": {
"type": "string"
},
"created_by_id": {
"type": "string"
},
"last_invoked_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"trigger_kinds": {
"type": "array",
"items": {
"type": "string"
}
},
"next_fire_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_invocation_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"subscribers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AutomationSubscriberEntry"
}
},
"my_delivery": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"can_write": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"can_manage_access": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"required": [
"company_commit_sha",
"id",
"workspace_id",
"title",
"description",
"area_id",
"harness",
"model",
"thinking_level",
"service_tier",
"source_recipe_key",
"execution_owner_id",
"status",
"pause_reason",
"task_title_template",
"created_by_type",
"created_by_id",
"last_invoked_at",
"created_at",
"updated_at",
"subscribers",
"my_delivery"
]
},
"AutomationSubscriberEntry": {
"type": "object",
"properties": {
"user_type": {
"type": "string"
},
"user_id": {
"type": "string"
},
"delivery": {
"type": "string"
},
"created_at": {
"type": "string"
}
},
"required": [
"user_type",
"user_id",
"delivery",
"created_at"
]
},
"AutomationTriggerResponse": {
"type": "object",
"properties": {
"integration_trigger": {
"anyOf": [
{
"$ref": "#/components/schemas/IntegrationTrigger"
},
{
"type": "null"
}
]
},
"integration_status": {
"type": "string"
},
"integration_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"provider_trigger_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"company_commit_sha": {
"type": "string"
},
"id": {
"type": "string"
},
"automation_id": {
"type": "string"
},
"kind": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"cron_expression": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"next_fire_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"webhook_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"webhook_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"has_signing_secret": {
"type": "boolean"
},
"signing_secret_hint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_fired_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"event_filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEventFilter"
}
}
},
"required": [
"company_commit_sha",
"id",
"automation_id",
"kind",
"enabled",
"cron_expression",
"timezone",
"next_fire_at",
"webhook_token",
"webhook_path",
"webhook_url",
"provider",
"has_signing_secret",
"signing_secret_hint",
"label",
"last_fired_at",
"created_at",
"updated_at"
]
},
"BatchDeleteTasksRequestInput": {
"type": "object",
"properties": {
"task_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"BatchUpdateTasksRequestInput": {
"type": "object",
"properties": {
"task_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"updates": {
"$ref": "#/components/schemas/UpdateTaskRequestInput"
}
}
},
"BuiltinSkillResponse": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"name",
"description"
]
},
"CancelRunResponse": {
"type": "object",
"properties": {
"access": {
"anyOf": [
{
"$ref": "#/components/schemas/RunAccessReceipt"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"execution_owner_id": {
"type": "string"
},
"worker_id": {
"type": "string"
},
"model": {
"type": "string"
},
"thinking_level": {
"type": "string"
},
"service_tier": {
"type": "string"
},
"execution_receipt": {
"anyOf": [
{
"$ref": "#/components/schemas/RunExecutionReceipt"
},
{
"type": "null"
}
]
},
"task_id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"status": {
"type": "string"
},
"dispatched_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"result": {},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"failure_reason": {
"type": "string"
},
"attempt": {
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"parent_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"work_dir": {
"type": "string"
},
"relative_work_dir": {
"type": "string"
},
"branch_name": {
"type": "string"
},
"trigger_message_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"coalesced_message_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"delivered_message_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"trigger_summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"automation_invocation_id": {
"type": "string"
},
"interaction_continuation": {
"anyOf": [
{
"$ref": "#/components/schemas/InteractionContinuationData"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string"
},
"attribution": {
"anyOf": [
{
"$ref": "#/components/schemas/RunAttribution"
},
{
"type": "null"
}
]
},
"usage": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RunUsageData"
}
},
"billed": {
"anyOf": [
{
"$ref": "#/components/schemas/RunBilledUsage"
},
{
"type": "null"
}
]
},
"cancelled_input": {
"anyOf": [
{
"$ref": "#/components/schemas/CancelledTaskInputResponse"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"execution_owner_id",
"worker_id",
"task_id",
"workspace_id",
"status",
"dispatched_at",
"started_at",
"completed_at",
"result",
"error",
"attempt",
"max_attempts",
"created_at",
"delivered_message_ids",
"kind"
]
},
"CancelledTaskInputResponse": {
"type": "object",
"properties": {
"task_id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"content": {
"type": "string"
},
"restore_to_input": {
"type": "boolean"
},
"attachments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttachmentResponse"
}
}
},
"required": [
"task_id",
"message_id",
"content",
"restore_to_input"
]
},
"CardInput": {
"type": "object",
"properties": {
"cardholder": {
"type": "string"
},
"number": {
"type": "string"
},
"exp_month": {
"type": "integer"
},
"exp_year": {
"type": "integer"
},
"cvc": {
"type": "string"
},
"billing_address": {
"type": "string"
}
}
},
"ConnectedAppConnectionResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"connected_account_id": {
"type": "string"
},
"toolkit_slug": {
"type": "string"
},
"status": {
"type": "string"
},
"connected_at": {
"type": "string"
},
"last_used_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"owner_user_id": {
"type": "string"
},
"is_owner": {
"type": "boolean"
},
"shared_with_workspace": {
"type": "boolean"
},
"account_label": {
"type": "string"
},
"description": {
"type": "string"
},
"account_identity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"connected_account_id",
"toolkit_slug",
"status",
"connected_at",
"last_used_at",
"owner_user_id",
"is_owner",
"shared_with_workspace",
"account_identity"
]
},
"CreateAreaResourceRequestPayloadInput": {
"type": "object",
"properties": {
"resource_type": {
"type": "string"
},
"resource_ref": {},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"position": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
}
},
"CreateAutomationTriggerRequestInput": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"cron_expression": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"event_filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEventFilterInput"
}
}
}
},
"CreatePATRequestInput": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"expires_in_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
}
},
"CreatePATResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"token_prefix": {
"type": "string"
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"token": {
"type": "string"
}
},
"required": [
"id",
"name",
"token_prefix",
"expires_at",
"last_used_at",
"created_at",
"token"
]
},
"CreateSkillFileRequestInput": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"content": {
"type": "string"
},
"encoding": {
"type": "string"
}
}
},
"CreateSkillRequestInput": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"content": {
"type": "string"
},
"config": {},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateSkillFileRequestInput"
}
}
}
},
"CreateTaskMessageRequestInput": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"CreateTaskRequestInput": {
"type": "object",
"properties": {
"repositories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskRepositoryGrantInput"
},
"maxItems": 20,
"description": "At most 20 repository grants, fixed at Task creation. Requires an admin company key and an enabled integration broker. Each grant names a canonical GitHub HTTPS URL, read or write permission and a credential_reference identifying an authorization grant, never a token. The broker response must contain token, expires_at and permission matching the request. expires_at must be more than 30 seconds and at most 70 minutes after the exchange validation time. This expiry rule applies to the broker response, not to a Task creation field."
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
},
"maxProperties": 50,
"propertyNames": {
"pattern": "^[a-zA-Z_][a-zA-Z0-9_.-]{0,63}$"
},
"description": "A flat map of strings, numbers and booleans with at most 50 keys. Keys match ^[a-zA-Z_][a-zA-Z0-9_.-]{0,63}$. The encoded create value and stored JSONB each have an 8 KiB limit; storage size is checked by the server, not by a JSON Schema character limit. Null values, arrays and nested objects are rejected."
},
"instructions": {
"type": "string",
"pattern": "^[^\u0000]*$",
"description": "Immutable guidance for every Run on the Task. At most 32768 UTF-8 bytes and no NUL characters. The server checks bytes, not Unicode character count. Run credentials cannot configure this field."
},
"callback_url": {
"type": "string"
},
"client_request_id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"parent_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"area_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"origin_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"origin_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"allow_duplicate": {
"type": "boolean"
},
"execution": {
"anyOf": [
{
"$ref": "#/components/schemas/TaskExecutionRequestInput"
},
{
"type": "null"
}
]
},
"start": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"input": {
"type": "string"
},
"isolated": {
"type": "boolean"
},
"execution_identity_id": {
"type": "string"
},
"mcp_servers": {
"$ref": "#/components/schemas/McpServerInputsInput",
"description": "At most 10 servers with unique, non-reserved names. Each server uses exactly one of a remote HTTPS url or a stdio command. headers belong to remote servers; args and env belong to stdio servers. The encrypted set is limited to 64 KiB; the server rejects a larger sealed set with HTTP 413. This encrypted-size limit cannot be measured as JSON character count. Header and environment values are write-only; GET returns McpServerSummary objects."
}
}
},
"CreateWorkspaceAPIKeyRequestInput": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"expires_in_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"Error": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": true
},
"ExistingSkillIdentity": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"created_by": {
"type": "string"
},
"can_overwrite": {
"type": "boolean"
}
},
"required": [
"id",
"name"
]
},
"GetTaskParticipationRow": {
"type": "object",
"properties": {
"following": {
"type": "boolean"
},
"muted": {
"type": "boolean"
}
},
"required": [
"following",
"muted"
]
},
"GitHubConnectCandidateResponse": {
"type": "object",
"properties": {
"installation_id": {
"type": "integer"
},
"account_login": {
"type": "string"
},
"account_type": {
"type": "string"
},
"account_avatar_url": {
"type": "string"
}
},
"required": [
"installation_id",
"account_login",
"account_type"
]
},
"GitHubConnectCandidatesResponse": {
"type": "object",
"properties": {
"candidates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GitHubConnectCandidateResponse"
}
},
"return_to": {
"type": "string"
}
},
"required": [
"candidates",
"return_to"
]
},
"GitHubConnectResponse": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"configured": {
"type": "boolean"
},
"error": {
"type": "string"
}
},
"required": [
"url",
"configured"
]
},
"GitHubInstallationResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"installation_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"requires_reconnect": {
"type": "boolean"
},
"account_login": {
"type": "string"
},
"account_type": {
"type": "string"
},
"account_avatar_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"workspace_id",
"requires_reconnect",
"account_login",
"account_type",
"account_avatar_url",
"created_at"
]
},
"GitHubPRReviewTaskResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"identifier": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"id",
"identifier",
"title"
]
},
"GitHubPullRequestCheckResponse": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"conclusion": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"details_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"is_status_context": {
"type": "boolean"
}
},
"required": [
"name",
"status",
"conclusion",
"details_url",
"is_status_context"
]
},
"GitHubPullRequestDetailResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"provider": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"repo_owner": {
"type": "string"
},
"repo_name": {
"type": "string"
},
"number": {
"type": "integer"
},
"title": {
"type": "string"
},
"state": {
"type": "string"
},
"html_url": {
"type": "string"
},
"branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"head_sha": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"author_login": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"author_avatar_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"merged_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"closed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"pr_created_at": {
"type": "string"
},
"pr_updated_at": {
"type": "string"
},
"mergeable_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mergeable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"merge_state_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"snapshot_available": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"checks_rollup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"checks_conclusion": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"checks_total": {
"type": "integer"
},
"checks_passed": {
"type": "integer"
},
"checks_failed": {
"type": "integer"
},
"checks_running": {
"type": "integer"
},
"checks_pending": {
"type": "integer"
},
"failed_check_names": {
"type": "array",
"items": {
"type": "string"
}
},
"snapshot_stale": {
"type": "boolean"
},
"snapshot_fetched_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"snapshot_head_sha": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"additions": {
"type": "integer"
},
"deletions": {
"type": "integer"
},
"changed_files": {
"type": "integer"
},
"body": {
"type": "string"
},
"commits_count": {
"type": "integer"
},
"checks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GitHubPullRequestCheckResponse"
}
},
"preferred_merge_method": {
"type": "string"
},
"allow_merge_commit": {
"type": "boolean"
},
"allow_squash_merge": {
"type": "boolean"
},
"allow_rebase_merge": {
"type": "boolean"
},
"can_merge": {
"type": "boolean"
},
"review_decision": {
"type": "string"
},
"review_task": {
"anyOf": [
{
"$ref": "#/components/schemas/GitHubPRReviewTaskResponse"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"provider",
"workspace_id",
"repo_owner",
"repo_name",
"number",
"title",
"state",
"html_url",
"branch",
"head_sha",
"author_login",
"author_avatar_url",
"merged_at",
"closed_at",
"pr_created_at",
"pr_updated_at",
"mergeable_state",
"mergeable",
"merge_state_status",
"checks_rollup",
"checks_conclusion",
"checks_total",
"checks_passed",
"checks_failed",
"checks_running",
"checks_pending",
"failed_check_names",
"snapshot_stale",
"snapshot_fetched_at",
"snapshot_head_sha",
"additions",
"deletions",
"changed_files",
"body",
"commits_count",
"checks",
"preferred_merge_method",
"allow_merge_commit",
"allow_squash_merge",
"allow_rebase_merge",
"can_merge"
]
},
"GitHubPullRequestResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"provider": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"repo_owner": {
"type": "string"
},
"repo_name": {
"type": "string"
},
"number": {
"type": "integer"
},
"title": {
"type": "string"
},
"state": {
"type": "string"
},
"html_url": {
"type": "string"
},
"branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"head_sha": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"author_login": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"author_avatar_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"merged_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"closed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"pr_created_at": {
"type": "string"
},
"pr_updated_at": {
"type": "string"
},
"mergeable_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mergeable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"merge_state_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"snapshot_available": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"checks_rollup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"checks_conclusion": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"checks_total": {
"type": "integer"
},
"checks_passed": {
"type": "integer"
},
"checks_failed": {
"type": "integer"
},
"checks_running": {
"type": "integer"
},
"checks_pending": {
"type": "integer"
},
"failed_check_names": {
"type": "array",
"items": {
"type": "string"
}
},
"snapshot_stale": {
"type": "boolean"
},
"snapshot_fetched_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"snapshot_head_sha": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"additions": {
"type": "integer"
},
"deletions": {
"type": "integer"
},
"changed_files": {
"type": "integer"
}
},
"required": [
"id",
"provider",
"workspace_id",
"repo_owner",
"repo_name",
"number",
"title",
"state",
"html_url",
"branch",
"head_sha",
"author_login",
"author_avatar_url",
"merged_at",
"closed_at",
"pr_created_at",
"pr_updated_at",
"mergeable_state",
"mergeable",
"merge_state_status",
"checks_rollup",
"checks_conclusion",
"checks_total",
"checks_passed",
"checks_failed",
"checks_running",
"checks_pending",
"failed_check_names",
"snapshot_stale",
"snapshot_fetched_at",
"snapshot_head_sha",
"additions",
"deletions",
"changed_files"
]
},
"GitHubRepositoriesResponse": {
"type": "object",
"properties": {
"repositories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GitHubRepositoryResponse"
}
},
"total_count": {
"type": "integer"
},
"next_page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"repositories",
"total_count",
"next_page"
]
},
"GitHubRepositoryResponse": {
"type": "object",
"properties": {
"permissions": {
"type": "object",
"properties": {
"admin": {
"type": "boolean"
}
},
"required": [
"admin"
]
},
"id": {
"type": "integer"
},
"full_name": {
"type": "string"
},
"html_url": {
"type": "string"
},
"clone_url": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"private": {
"type": "boolean"
},
"archived": {
"type": "boolean"
},
"default_branch": {
"type": "string"
}
},
"required": [
"permissions",
"id",
"full_name",
"html_url",
"clone_url",
"description",
"private",
"archived",
"default_branch"
]
},
"HarnessAccess": {
"type": "object",
"properties": {
"next_method": {
"type": "string"
},
"next_reason": {
"type": "string"
},
"accounts": {
"type": "integer"
},
"usable_accounts": {
"type": "integer"
},
"account_headroom": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"harness": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"accounts_enabled": {
"type": "boolean"
},
"key_enabled": {
"type": "boolean"
},
"gateway_enabled": {
"type": "boolean"
},
"has_key": {
"type": "boolean"
},
"key_health": {
"type": "string"
},
"key_cooldown_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"gateway_limit_ticks": {
"type": "string"
},
"settled_ticks": {
"type": "string"
},
"reserved_ticks": {
"type": "string"
},
"gateway_suspended": {
"type": "boolean"
},
"supports_accounts": {
"type": "boolean"
},
"supports_key": {
"type": "boolean"
},
"supports_gateway": {
"type": "boolean"
}
},
"required": [
"next_method",
"next_reason",
"accounts",
"usable_accounts",
"harness",
"enabled",
"accounts_enabled",
"key_enabled",
"gateway_enabled",
"has_key",
"key_health",
"key_cooldown_until",
"gateway_limit_ticks",
"settled_ticks",
"reserved_ticks",
"gateway_suspended",
"supports_accounts",
"supports_key",
"supports_gateway"
]
},
"HarnessAccessUpdateInput": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"accounts_enabled": {
"type": "boolean"
},
"key_enabled": {
"type": "boolean"
},
"gateway_enabled": {
"type": "boolean"
},
"gateway_limit_ticks": {
"type": "string"
},
"api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"ImportSkillRequestInput": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"on_conflict": {
"type": "string"
},
"scope": {
"type": "string"
},
"area_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"auto_update": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
},
"InstallAreaRecipeRequestInput": {
"type": "object",
"properties": {
"idempotency_key": {
"type": "string"
},
"area_id": {
"type": "string"
},
"harness": {
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cron_expression": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"thinking_level": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
}
}
},
"InstallAreaRecipeResponse": {
"type": "object",
"properties": {
"catalog_version": {
"type": "string"
},
"recipe_key": {
"type": "string"
},
"created": {
"type": "boolean"
},
"automation": {
"$ref": "#/components/schemas/AutomationResponse"
},
"trigger": {
"$ref": "#/components/schemas/AutomationTriggerResponse"
},
"execution": {
"$ref": "#/components/schemas/AreaRecipeExecutionResponse"
}
},
"required": [
"catalog_version",
"recipe_key",
"created",
"automation",
"trigger",
"execution"
]
},
"IntegrationTrigger": {
"type": "object",
"properties": {
"toolkit_slug": {
"type": "string"
},
"connected_account_id": {
"type": "string"
},
"trigger_slug": {
"type": "string"
},
"trigger_config": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"toolkit_slug",
"connected_account_id",
"trigger_slug",
"trigger_config"
]
},
"IntegrationTriggerInput": {
"type": "object",
"properties": {
"toolkit_slug": {
"type": "string"
},
"connected_account_id": {
"type": "string"
},
"trigger_slug": {
"type": "string"
},
"trigger_config": {
"type": "object",
"additionalProperties": {}
}
}
},
"InteractionContinuationData": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"request_id": {
"type": "string"
},
"source_run_id": {
"type": "string"
},
"kind": {
"type": "string"
},
"status": {
"type": "string"
},
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"payload": {},
"response": {},
"audit_text": {
"type": "string"
},
"response_actor_type": {
"type": "string"
},
"response_actor_id": {
"type": "string"
},
"resolved_at": {
"type": "string"
},
"resume_provider": {
"type": "string"
},
"resume_session_id": {
"type": "string"
},
"tool_call_id": {
"type": "string"
},
"tool_name": {
"type": "string"
},
"tool_result": {}
},
"required": [
"type",
"request_id",
"kind",
"status"
]
},
"InteractionRequestResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"task_id": {
"type": "string"
},
"source_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"parent_message_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"recipient_user_id": {
"type": "string"
},
"kind": {
"type": "string"
},
"status": {
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message": {
"type": "string"
},
"payload": {},
"response": {},
"audit_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"response_actor_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"response_actor_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resolved_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"workspace_id",
"task_id",
"source_run_id",
"parent_message_id",
"recipient_user_id",
"kind",
"status",
"title",
"message",
"payload",
"response",
"audit_text",
"response_actor_type",
"response_actor_id",
"expires_at",
"resolved_at",
"created_at",
"updated_at"
]
},
"Kind": {
"type": "string"
},
"ListManagedExecutionIdentitiesRow": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"workspace_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"integration_user_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"external_id": {
"type": "string"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"workspace_id",
"integration_user_id",
"external_id",
"revoked_at",
"created_at",
"name"
]
},
"LoginInput": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"username": {
"type": "string"
},
"password": {
"type": "string"
},
"totp_secret": {
"type": "string"
}
}
},
"ManagedExecutionIdentity": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"workspace_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"integration_user_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"external_id": {
"type": "string"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"id",
"workspace_id",
"integration_user_id",
"external_id",
"revoked_at",
"created_at"
]
},
"McpServerInputInput": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"command": {
"type": "string"
},
"args": {
"type": "array",
"items": {
"type": "string"
}
},
"env": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"name"
],
"additionalProperties": false,
"description": "Remote input: name, url and optional headers. Stdio input: name, command and optional args and env. Exactly one nonempty url or command is required. Unknown fields are rejected; transport-specific fields are validated by the server."
},
"McpServerInputsInput": {
"type": "array",
"items": {
"$ref": "#/components/schemas/McpServerInputInput"
},
"maxItems": 10,
"description": "At most 10 servers with unique, non-reserved names. Each server uses exactly one of a remote HTTPS url or a stdio command. headers belong to remote servers; args and env belong to stdio servers. The encrypted set is limited to 64 KiB; the server rejects a larger sealed set with HTTP 413. This encrypted-size limit cannot be measured as JSON character count. Header and environment values are write-only; GET returns McpServerSummary objects."
},
"McpServerSummary": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"transport": {
"type": "string",
"enum": [
"http",
"stdio"
]
},
"url": {
"type": "string"
},
"header_names": {
"type": "array",
"items": {
"type": "string"
}
},
"command": {
"type": "string"
},
"args": {
"type": "array",
"items": {
"type": "string"
}
},
"env_names": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"name",
"transport"
]
},
"MeResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatar_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"onboarded_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"onboarding_questionnaire": {},
"starter_content_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"profile_description": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"workspace": {
"anyOf": [
{
"$ref": "#/components/schemas/MeWorkspaceResponse"
},
{
"type": "null"
}
]
},
"api_key_scope": {
"type": "string"
},
"impersonated": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"kind",
"email",
"phone",
"avatar_url",
"language",
"timezone",
"onboarded_at",
"onboarding_questionnaire",
"starter_content_state",
"profile_description",
"created_at",
"updated_at"
]
},
"MeWorkspaceResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"required": [
"id",
"name",
"slug"
]
},
"MemberWithUserResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"user_id": {
"type": "string"
},
"role": {
"type": "string"
},
"created_at": {
"type": "string"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"avatar_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"workspace_id",
"user_id",
"role",
"created_at",
"name",
"email",
"avatar_url"
]
},
"ModelEntry": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"provider": {
"type": "string"
},
"default": {
"type": "boolean"
},
"thinking": {
"anyOf": [
{
"$ref": "#/components/schemas/ModelThinking"
},
{
"type": "null"
}
]
},
"service_tiers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelServiceTier"
}
}
},
"required": [
"id",
"label"
]
},
"ModelServiceTier": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"ModelThinking": {
"type": "object",
"properties": {
"supported_levels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ThinkingLevel"
}
},
"default_level": {
"type": "string"
}
},
"required": [
"supported_levels"
]
},
"OutboundWebhookEndpoint": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"workspace_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"url": {
"type": "string"
},
"description": {
"type": "string"
},
"event_types": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"id",
"workspace_id",
"url",
"description",
"event_types",
"enabled",
"created_at"
]
},
"OwnedRequest": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"kind": {
"$ref": "#/components/schemas/Kind"
},
"status": {
"type": "string"
},
"prefill": {
"$ref": "#/components/schemas/Prefill"
},
"share": {
"$ref": "#/components/schemas/Share"
},
"area_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"workspace_name": {
"type": "string"
},
"owner_name": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"requested_by": {
"type": "string"
},
"created_at": {
"type": "string"
},
"task": {
"anyOf": [
{
"$ref": "#/components/schemas/RequestTask"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"kind",
"status",
"prefill",
"share",
"area_ids",
"workspace_name",
"owner_name",
"expires_at",
"requested_by",
"created_at",
"task"
]
},
"PersonalAccessTokenResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"token_prefix": {
"type": "string"
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"name",
"token_prefix",
"expires_at",
"last_used_at",
"created_at"
]
},
"Prefill": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"env_name": {
"type": "string"
},
"url": {
"type": "string"
},
"username": {
"type": "string"
},
"cardholder": {
"type": "string"
},
"note": {
"type": "string"
}
}
},
"Prompt": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"user_code": {
"type": "string"
},
"flow": {
"type": "string"
}
},
"required": [
"flow"
]
},
"QueuedRunResponse": {
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"status": {
"type": "string"
},
"created_at": {
"type": "string"
},
"message_id": {
"type": "string"
},
"content": {
"type": "string"
}
},
"required": [
"run_id",
"status",
"created_at"
]
},
"ReactionResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"actor_type": {
"type": "string"
},
"actor_id": {
"type": "string"
},
"emoji": {
"type": "string"
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"message_id",
"actor_type",
"actor_id",
"emoji",
"created_at"
]
},
"Request": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"kind": {
"$ref": "#/components/schemas/Kind"
}
},
"required": [
"id",
"kind"
]
},
"RequestTask": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"identifier": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"id",
"identifier",
"title"
]
},
"RequestView": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"kind": {
"$ref": "#/components/schemas/Kind"
},
"status": {
"type": "string"
},
"prefill": {
"$ref": "#/components/schemas/Prefill"
},
"share": {
"$ref": "#/components/schemas/Share"
},
"area_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"workspace_name": {
"type": "string"
},
"owner_name": {
"type": "string"
},
"expires_at": {
"type": "string"
}
},
"required": [
"id",
"kind",
"status",
"prefill",
"share",
"area_ids",
"workspace_name",
"owner_name",
"expires_at"
]
},
"RerunTaskRequestInput": {
"type": "object",
"properties": {
"run_id": {
"type": "string"
}
}
},
"RunAccessReceipt": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"reason": {
"type": "string"
},
"account_id": {
"type": "string"
},
"provider": {
"type": "string"
},
"label": {
"type": "string"
},
"email": {
"type": "string"
}
},
"required": [
"method",
"reason"
]
},
"RunAttribution": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"precise": {
"type": "boolean"
},
"initiator": {
"anyOf": [
{
"$ref": "#/components/schemas/AttributionUser"
},
{
"type": "null"
}
]
},
"originator": {
"anyOf": [
{
"$ref": "#/components/schemas/AttributionUser"
},
{
"type": "null"
}
]
},
"evidence": {
"anyOf": [
{
"$ref": "#/components/schemas/RunEvidence"
},
{
"type": "null"
}
]
},
"automation_version_id": {
"type": "string"
},
"delegated_from_run_id": {
"type": "string"
},
"retry_of_run_id": {
"type": "string"
},
"rerun_of_run_id": {
"type": "string"
}
},
"required": [
"source",
"precise"
]
},
"RunBilledUsage": {
"type": "object",
"properties": {
"model_usd_ticks": {
"type": "string"
},
"estimated": {
"type": "boolean"
}
},
"required": [
"model_usd_ticks",
"estimated"
]
},
"RunEventPayload": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"run_id": {
"type": "string"
},
"task_id": {
"type": "string"
},
"source": {
"type": "string"
},
"kind": {
"type": "string"
},
"label": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {}
},
"occurred_at": {
"type": "string"
},
"source_at": {
"type": "string"
},
"recorded_at": {
"type": "string"
}
},
"required": [
"id",
"run_id",
"source",
"kind",
"occurred_at",
"recorded_at"
]
},
"RunEventResponse": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RunEventPayload"
}
}
},
"required": [
"events"
]
},
"RunEvidence": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"ref_id": {
"type": "string"
}
},
"required": [
"kind",
"ref_id"
]
},
"RunExecutionReceipt": {
"type": "object",
"properties": {
"harness": {
"type": "string"
},
"worker_id": {
"type": "string"
},
"model": {
"type": "string"
},
"thinking_level": {
"type": "string"
},
"service_tier": {
"type": "string"
}
},
"required": [
"harness",
"model",
"thinking_level",
"service_tier"
]
},
"RunMessagePayload": {
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"task_id": {
"type": "string"
},
"seq": {
"type": "integer"
},
"type": {
"type": "string"
},
"tool": {
"type": "string"
},
"content": {
"type": "string"
},
"input": {
"type": "object",
"additionalProperties": {}
},
"output": {
"type": "string"
},
"created_at": {
"type": "string"
}
},
"required": [
"run_id",
"seq",
"type"
]
},
"RunResponse": {
"type": "object",
"properties": {
"access": {
"anyOf": [
{
"$ref": "#/components/schemas/RunAccessReceipt"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"execution_owner_id": {
"type": "string"
},
"worker_id": {
"type": "string"
},
"model": {
"type": "string"
},
"thinking_level": {
"type": "string"
},
"service_tier": {
"type": "string"
},
"execution_receipt": {
"anyOf": [
{
"$ref": "#/components/schemas/RunExecutionReceipt"
},
{
"type": "null"
}
]
},
"task_id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"deferred",
"dispatched",
"running",
"paused",
"completed",
"failed",
"cancelled"
],
"description": "See [Task, Run and fiscal states](/concepts/overview#completion-has-several-meanings)."
},
"dispatched_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"result": {},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"failure_reason": {
"type": "string"
},
"attempt": {
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"parent_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"work_dir": {
"type": "string"
},
"relative_work_dir": {
"type": "string"
},
"branch_name": {
"type": "string"
},
"trigger_message_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"coalesced_message_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"delivered_message_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"trigger_summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"automation_invocation_id": {
"type": "string"
},
"interaction_continuation": {
"anyOf": [
{
"$ref": "#/components/schemas/InteractionContinuationData"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string"
},
"attribution": {
"anyOf": [
{
"$ref": "#/components/schemas/RunAttribution"
},
{
"type": "null"
}
]
},
"usage": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RunUsageData"
}
},
"billed": {
"anyOf": [
{
"$ref": "#/components/schemas/RunBilledUsage"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"execution_owner_id",
"worker_id",
"task_id",
"workspace_id",
"status",
"dispatched_at",
"started_at",
"completed_at",
"result",
"error",
"attempt",
"max_attempts",
"created_at",
"delivered_message_ids",
"kind"
]
},
"RunUsageData": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"model": {
"type": "string"
},
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_usd_ticks": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"model",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens"
]
},
"SearchAreaResponse": {
"type": "object",
"properties": {
"company_commit_sha": {
"type": "string"
},
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"icon": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sandbox_size": {
"type": "string"
},
"visibility": {
"type": "string"
},
"key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sort_order": {
"type": "integer"
},
"default_harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"default_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"default_thinking_level": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"default_service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"instructions": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"resource_count": {
"type": "integer"
},
"match_source": {
"type": "string"
},
"matched_snippet": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"company_commit_sha",
"id",
"workspace_id",
"title",
"description",
"icon",
"sandbox_size",
"visibility",
"key",
"sort_order",
"default_harness",
"default_model",
"default_thinking_level",
"default_service_tier",
"instructions",
"created_at",
"updated_at",
"resource_count",
"match_source"
]
},
"SearchTaskResponse": {
"type": "object",
"properties": {
"execution": {
"anyOf": [
{
"$ref": "#/components/schemas/TaskExecutionSettings"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"number": {
"type": "integer"
},
"identifier": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
"delivered_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cancelled_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"creator_type": {
"type": "string"
},
"creator_id": {
"type": "string"
},
"parent_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"area_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"origin_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"execution_identity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"isolated": {
"type": "boolean"
},
"participant_member_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"participant_harnesses": {
"type": "array",
"items": {
"type": "string"
}
},
"has_pending_interaction": {
"type": "boolean"
},
"has_active_run": {
"type": "boolean"
},
"has_paused_run": {
"type": "boolean"
},
"attention_reason": {
"type": "string"
},
"failure_reason": {
"type": "string"
},
"failure_class": {
"type": "string"
},
"unread": {
"type": "boolean"
},
"viewer_participated": {
"type": "boolean"
},
"pull_request": {
"anyOf": [
{
"$ref": "#/components/schemas/TaskPullRequestSummary"
},
{
"type": "null"
}
]
},
"attachments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttachmentResponse"
}
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"match_source": {
"type": "string"
},
"matched_description_snippet": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"matched_comment_snippet": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"execution",
"id",
"workspace_id",
"number",
"identifier",
"title",
"description",
"status",
"delivered_at",
"completed_at",
"cancelled_at",
"creator_type",
"creator_id",
"parent_task_id",
"area_id",
"created_at",
"updated_at",
"origin_type",
"metadata",
"isolated",
"match_source"
]
},
"SetAreaConnectionRequestInput": {
"type": "object",
"properties": {
"connection_kind": {
"type": "string"
},
"connection_ref": {
"type": "string"
},
"owner_user_id": {
"type": "string"
},
"visibility": {
"type": "string"
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
},
"SetSigningSecretRequestInput": {
"type": "object",
"properties": {
"signing_secret": {
"type": "string"
}
}
},
"SetTaskMetadataKeyRequestInput": {
"type": "object",
"properties": {
"value": {}
}
},
"Settings": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"client_id": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"login_server": {
"type": "string"
},
"accept_routes": {
"type": "boolean"
},
"accept_dns": {
"type": "boolean"
},
"generation": {
"type": "integer"
},
"configured_by": {
"type": "string"
},
"configured_at": {
"type": "string",
"format": "date-time"
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"type": "string"
}
},
"required": [
"provider",
"enabled",
"client_id",
"tags",
"login_server",
"accept_routes",
"accept_dns",
"generation",
"configured_by",
"configured_at",
"verified_at",
"last_error"
]
},
"Share": {
"type": "string"
},
"SharedWorkspace": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"SkillAuditResult": {
"type": "object",
"properties": {
"auditor": {
"type": "string"
},
"risk": {
"type": "string"
}
},
"required": [
"auditor",
"risk"
]
},
"SkillFileResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"skill_id": {
"type": "string"
},
"path": {
"type": "string"
},
"content": {
"type": "string"
},
"encoding": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"skill_id",
"path",
"content",
"encoding",
"created_at",
"updated_at"
]
},
"SkillImportResult": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"reason": {
"type": "string"
},
"skill": {
"anyOf": [
{
"$ref": "#/components/schemas/SkillWithFilesResponse"
},
{
"type": "null"
}
]
},
"existing_skill": {
"anyOf": [
{
"$ref": "#/components/schemas/ExistingSkillIdentity"
},
{
"type": "null"
}
]
}
},
"required": [
"status"
]
},
"SkillSearchCandidateResponse": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"source": {
"type": "string"
},
"repo": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"install_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"github_stars": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"description": {
"type": "string"
},
"audit_risk": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"audits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SkillAuditResult"
}
}
},
"required": [
"name",
"url",
"source",
"repo",
"install_count",
"github_stars",
"description",
"audit_risk"
]
},
"SkillSummaryResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"config": {},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"scope": {
"type": "string"
},
"area_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"workspace_id",
"name",
"description",
"config",
"created_by",
"created_at",
"updated_at",
"scope",
"area_ids"
]
},
"SkillWithFilesResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"content": {
"type": "string"
},
"config": {},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"scope": {
"type": "string"
},
"area_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SkillFileResponse"
}
},
"source_edited": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"workspace_id",
"name",
"description",
"content",
"config",
"created_by",
"created_at",
"updated_at",
"scope",
"area_ids",
"files"
]
},
"SubscriberInputInput": {
"type": "object",
"properties": {
"user_type": {
"type": "string"
},
"user_id": {
"type": "string"
}
}
},
"Target": {
"type": "object",
"properties": {
"worker_id": {
"type": "string"
},
"harness": {
"type": "string"
},
"status": {
"type": "string"
},
"reason": {
"type": "string"
},
"gateway_supported": {
"type": "boolean"
}
},
"required": [
"worker_id",
"harness",
"status",
"gateway_supported"
]
},
"TaskExecutionRequestInput": {
"type": "object",
"properties": {
"funding_source": {
"type": "string"
},
"provider_account_id": {
"type": "string"
},
"harness": {
"type": "string"
},
"worker_id": {
"type": "string"
},
"model": {
"type": "string"
},
"thinking_level": {
"type": "string"
},
"service_tier": {
"type": "string"
},
"max_attempts": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
}
},
"TaskExecutionSettings": {
"type": "object",
"properties": {
"version": {
"type": "string"
},
"harness": {
"type": "string"
},
"worker_id": {
"type": "string"
},
"model": {
"type": "string"
},
"thinking_level": {
"type": "string"
},
"service_tier": {
"type": "string"
}
},
"required": [
"version",
"harness",
"model",
"thinking_level",
"service_tier"
]
},
"TaskInputRequestInput": {
"type": "object",
"properties": {
"execution": {
"anyOf": [
{
"$ref": "#/components/schemas/TaskExecutionRequestInput"
},
{
"type": "null"
}
]
},
"mcp_servers": {
"$ref": "#/components/schemas/McpServerInputsInput"
},
"content": {
"type": "string"
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"client_request_id": {
"type": "string"
},
"fresh_session": {
"type": "boolean"
},
"max_attempts": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
}
},
"TaskInputResponse": {
"type": "object",
"properties": {
"message_id": {
"type": "string"
},
"run_id": {
"type": "string"
},
"queued": {
"type": "boolean"
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"created_at": {
"type": "string"
}
},
"required": [
"message_id",
"run_id",
"queued",
"attachment_ids",
"created_at"
]
},
"TaskMessageResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"task_id": {
"type": "string"
},
"author_type": {
"type": "string"
},
"author_id": {
"type": "string"
},
"content": {
"type": "string"
},
"role": {
"type": "string"
},
"kind": {
"type": "string"
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"failure_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"elapsed_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"reactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReactionResponse"
}
},
"attachments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttachmentResponse"
}
},
"final": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"task_id",
"author_type",
"author_id",
"content",
"role",
"kind",
"created_at",
"updated_at",
"reactions",
"attachments"
]
},
"TaskMessagesCursorResponse": {
"type": "object",
"properties": {
"created_at": {
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"created_at",
"id"
]
},
"TaskMessagesPageResponse": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskMessageResponse"
}
},
"limit": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"anyOf": [
{
"$ref": "#/components/schemas/TaskMessagesCursorResponse"
},
{
"type": "null"
}
]
}
},
"required": [
"messages",
"limit",
"has_more"
]
},
"TaskOutput": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"kind": {
"type": "string"
},
"file_name": {
"type": "string"
}
},
"required": [
"id",
"title",
"kind"
]
},
"TaskPullRequestSummary": {
"type": "object",
"properties": {
"number": {
"type": "integer"
},
"state": {
"type": "string"
},
"html_url": {
"type": "string"
},
"checks_rollup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"additions": {
"type": "integer"
},
"deletions": {
"type": "integer"
},
"changed_files": {
"type": "integer"
}
},
"required": [
"number",
"state",
"html_url",
"additions",
"deletions",
"changed_files"
]
},
"TaskRepositoryGrantInput": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"ref": {
"type": "string"
},
"permission": {
"type": "string"
},
"credential_reference": {
"type": "string"
}
}
},
"TaskResponse": {
"type": "object",
"properties": {
"execution": {
"anyOf": [
{
"$ref": "#/components/schemas/TaskExecutionSettings"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"number": {
"type": "integer"
},
"identifier": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"cancelled",
"done",
"working",
"paused",
"needs_you",
"to_review",
"idle"
],
"description": "See [Task, Run and fiscal states](/concepts/overview#completion-has-several-meanings)."
},
"delivered_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cancelled_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"creator_type": {
"type": "string"
},
"creator_id": {
"type": "string"
},
"parent_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"area_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"origin_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"execution_identity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"isolated": {
"type": "boolean"
},
"participant_member_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"participant_harnesses": {
"type": "array",
"items": {
"type": "string"
}
},
"has_pending_interaction": {
"type": "boolean"
},
"has_active_run": {
"type": "boolean"
},
"has_paused_run": {
"type": "boolean"
},
"attention_reason": {
"type": "string"
},
"failure_reason": {
"type": "string"
},
"failure_class": {
"type": "string"
},
"unread": {
"type": "boolean"
},
"viewer_participated": {
"type": "boolean"
},
"pull_request": {
"anyOf": [
{
"$ref": "#/components/schemas/TaskPullRequestSummary"
},
{
"type": "null"
}
]
},
"attachments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttachmentResponse"
}
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"execution",
"id",
"workspace_id",
"number",
"identifier",
"title",
"description",
"status",
"delivered_at",
"completed_at",
"cancelled_at",
"creator_type",
"creator_id",
"parent_task_id",
"area_id",
"created_at",
"updated_at",
"origin_type",
"metadata",
"isolated"
]
},
"TaskRunQueueResponse": {
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"status": {
"type": "string"
},
"created_at": {
"type": "string"
},
"queued_runs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QueuedRunResponse"
}
}
}
},
"ThinkingLevel": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"label": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"value",
"label"
]
},
"TimelineEntry": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"id": {
"type": "string"
},
"actor_type": {
"type": "string"
},
"actor_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"action": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"details": {},
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"parent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"comment_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReactionResponse"
}
},
"attachments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttachmentResponse"
}
},
"resolved_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resolved_by_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resolved_by_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"actor_type",
"actor_id",
"created_at"
]
},
"UpdateAreaInstructionsRequestInput": {
"type": "object",
"properties": {
"instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"UpdateInput": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"client_id": {
"type": "string"
},
"client_secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"login_server": {
"type": "string"
},
"auth_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"accept_routes": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"accept_dns": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
},
"UpdateSkillRequestInput": {
"type": "object",
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config": {},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateSkillFileRequestInput"
}
},
"auto_update": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
},
"UpdateTaskRequestInput": {
"type": "object",
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"parent_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"area_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"WebhookDeliveryResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"automation_id": {
"type": "string"
},
"trigger_id": {
"type": "string"
},
"provider": {
"type": "string"
},
"event": {
"type": "string"
},
"dedupe_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"dedupe_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"signature_status": {
"type": "string"
},
"status": {
"type": "string"
},
"attempt_count": {
"type": "integer"
},
"dispatch_attempts": {
"type": "integer"
},
"available_at": {
"type": "string"
},
"content_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"response_status": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"automation_invocation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"replayed_from_delivery_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"received_at": {
"type": "string"
},
"last_attempt_at": {
"type": "string"
},
"created_at": {
"type": "string"
},
"selected_headers": {},
"raw_body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"response_body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"workspace_id",
"automation_id",
"trigger_id",
"provider",
"event",
"dedupe_key",
"dedupe_source",
"signature_status",
"status",
"attempt_count",
"dispatch_attempts",
"available_at",
"content_type",
"response_status",
"automation_invocation_id",
"replayed_from_delivery_id",
"error",
"received_at",
"last_attempt_at",
"created_at"
]
},
"WebhookEventFilter": {
"type": "object",
"properties": {
"event": {
"type": "string"
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"event"
]
},
"WebhookEventFilterInput": {
"type": "object",
"properties": {
"event": {
"type": "string"
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"WorkspaceAPIKeyResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"token_prefix": {
"type": "string"
},
"scope": {
"type": "string"
},
"created_by": {
"type": "string"
},
"created_at": {
"type": "string"
},
"last_used_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"name",
"token_prefix",
"scope",
"created_by",
"created_at",
"last_used_at",
"expires_at"
]
},
"WorkspaceKind": {
"type": "string"
},
"WorkspaceResponse": {
"type": "object",
"properties": {
"company_commit_sha": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"website_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"settings": {},
"repos": {},
"task_prefix": {
"type": "string"
},
"avatar_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"kind": {
"$ref": "#/components/schemas/WorkspaceKind"
},
"onboarded": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"company_commit_sha",
"id",
"name",
"slug",
"description",
"website_url",
"context",
"settings",
"repos",
"task_prefix",
"avatar_url",
"kind",
"onboarded",
"created_at",
"updated_at"
]
},
"areaRecipeCatalogResponse": {
"type": "object",
"properties": {
"version": {
"type": "string"
},
"recipes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AreaRecipe"
}
}
},
"required": [
"version",
"recipes"
]
},
"automationSubscriptionBodyInput": {
"type": "object",
"properties": {
"delivery": {
"type": "string"
}
}
},
"automationSubscriptionResponse": {
"type": "object",
"properties": {
"automation_id": {
"type": "string"
},
"delivery": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"automation_id",
"delivery"
]
},
"cancelInteractionRequestBodyInput": {
"type": "object",
"properties": {
"audit_text": {
"type": "string"
}
}
},
"completeGitHubConnectRequestInput": {
"type": "object",
"properties": {
"state": {
"type": "string"
},
"installation_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
}
},
"createInteractionRequestBodyInput": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"payload": {},
"recipient_user_id": {
"type": "string"
},
"parent_message_id": {
"type": "string"
},
"expires_at": {
"type": "string"
}
}
},
"directUploadRequestInput": {
"type": "object",
"properties": {
"filename": {
"type": "string"
},
"content_type": {
"type": "string"
},
"size_bytes": {
"type": "integer"
},
"task_id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"run_id": {
"type": "string"
}
}
},
"executionCapabilities": {
"type": "object",
"properties": {
"configured": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"reason": {
"type": "string"
},
"provider": {
"type": "string"
},
"harnesses": {
"type": "array",
"items": {
"type": "string"
}
},
"template_digest": {
"type": "string"
},
"active_workers": {
"type": "integer"
},
"max_workers": {
"type": "integer"
},
"workspace_active_workers": {
"type": "integer"
},
"workspace_max_workers": {
"type": "integer"
},
"archived_sandboxes": {
"type": "integer"
},
"targets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Target"
}
},
"melso": {
"anyOf": [
{
"$ref": "#/components/schemas/Target"
},
{
"type": "null"
}
]
}
},
"required": [
"configured",
"enabled",
"harnesses",
"active_workers",
"max_workers",
"workspace_active_workers",
"workspace_max_workers",
"archived_sandboxes",
"targets"
]
},
"mcpOAuthApproveRequestInput": {
"type": "object",
"properties": {
"client_id": {
"type": "string"
},
"redirect_uri": {
"type": "string"
},
"state": {
"type": "string"
},
"code_challenge": {
"type": "string"
},
"resource": {
"type": "string"
},
"scope": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"all_workspaces": {
"type": "boolean"
}
}
},
"mcpOAuthGrantResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"client_id": {
"type": "string"
},
"client_name": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"workspace_name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"client_id",
"client_name",
"workspace_id",
"workspace_name",
"created_at",
"last_used_at"
]
},
"mcpOAuthRegisterRequestInput": {
"type": "object",
"properties": {
"client_name": {
"type": "string"
},
"redirect_uris": {
"type": "array",
"items": {
"type": "string"
}
},
"grant_types": {
"type": "array",
"items": {
"type": "string"
}
},
"token_endpoint_auth_method": {
"type": "string"
}
}
},
"mcpRPCRequestInput": {
"type": "object",
"properties": {
"jsonrpc": {
"type": "string"
},
"id": {},
"method": {
"type": "string"
},
"params": {},
"_meta": {}
}
},
"mergePullRequestRequestInput": {
"type": "object",
"properties": {
"merge_method": {
"type": "string"
},
"commit_title": {
"type": "string"
},
"commit_message": {
"type": "string"
}
}
},
"muteTaskRequestInput": {
"type": "object",
"properties": {
"muted": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
},
"outboundEndpointRequestInput": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"description": {
"type": "string"
},
"event_types": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
},
"privateNetworkResponse": {
"type": "object",
"properties": {
"private_network": {
"anyOf": [
{
"$ref": "#/components/schemas/Settings"
},
{
"type": "null"
}
]
}
},
"required": [
"private_network"
]
},
"progressEntry": {
"type": "object",
"properties": {
"parent_task_id": {
"type": "string"
},
"total": {
"type": "integer"
},
"done": {
"type": "integer"
}
},
"required": [
"parent_task_id",
"total",
"done"
]
},
"replaceTaskMcpServersRequestInput": {
"type": "object",
"properties": {
"mcp_servers": {
"$ref": "#/components/schemas/McpServerInputsInput"
}
}
},
"resolvePullRequestResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
]
},
"respondInteractionRequestBodyInput": {
"type": "object",
"properties": {
"response": {},
"audit_text": {
"type": "string"
}
}
},
"runUsageFunding": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"account_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"source"
]
},
"runUsageOperation": {
"type": "object",
"properties": {
"usage_id": {
"type": "string"
},
"category": {
"type": "string"
},
"status": {
"type": "string"
},
"customer_billed_ticks": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"revision": {
"type": "integer"
},
"closed": {
"type": "boolean"
}
},
"required": [
"usage_id",
"category",
"status",
"customer_billed_ticks",
"revision",
"closed"
]
},
"runUsageReceipt": {
"type": "object",
"properties": {
"receipt_id": {
"type": "string"
},
"usage_id": {
"type": "string"
},
"category": {
"type": "string"
},
"customer_billed_ticks": {
"type": "string"
},
"estimated": {
"type": "boolean"
},
"settled_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"receipt_id",
"usage_id",
"category",
"customer_billed_ticks",
"estimated",
"settled_at"
]
},
"runUsageResponse": {
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"task_id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"execution_identity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"funding": {
"$ref": "#/components/schemas/runUsageFunding"
},
"as_of": {
"type": "string",
"format": "date-time"
},
"final": {
"type": "boolean"
},
"pending_count": {
"type": "integer"
},
"customer_billed_ticks": {
"type": "string"
},
"reported_model_cost_ticks": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reported_model_cost_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"receipts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/runUsageReceipt"
}
},
"usage": {
"type": "array",
"items": {
"$ref": "#/components/schemas/runUsageOperation"
}
}
},
"required": [
"run_id",
"task_id",
"workspace_id",
"funding",
"as_of",
"final",
"pending_count",
"customer_billed_ticks",
"reported_model_cost_ticks",
"reported_model_cost_updated_at",
"receipts",
"usage"
]
},
"startTaskRunRequestInput": {
"type": "object",
"properties": {
"funding_source": {
"type": "string"
},
"provider_account_id": {
"type": "string"
},
"harness": {
"type": "string"
},
"worker_id": {
"type": "string"
},
"model": {
"type": "string"
},
"thinking_level": {
"type": "string"
},
"service_tier": {
"type": "string"
},
"max_attempts": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
}
},
"startTaskRunResponse": {
"type": "object",
"properties": {
"run": {
"$ref": "#/components/schemas/RunResponse"
},
"execution": {
"anyOf": [
{
"$ref": "#/components/schemas/TaskExecutionSettings"
},
{
"type": "null"
}
]
}
},
"required": [
"run"
]
},
"taskExecutionResponse": {
"type": "object",
"properties": {
"execution": {
"anyOf": [
{
"$ref": "#/components/schemas/TaskExecutionSettings"
},
{
"type": "null"
}
]
}
},
"required": [
"execution"
]
},
"taskMcpServersResponse": {
"type": "object",
"properties": {
"mcp_servers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/McpServerSummary"
}
}
},
"required": [
"mcp_servers"
]
},
"taskWatchRequestInput": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"instruction": {
"type": "string"
}
}
},
"taskWatchResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"task_id": {
"type": "string"
},
"subscriber_task_id": {
"type": "string"
},
"status": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"instruction": {
"type": "string"
}
},
"required": [
"id",
"task_id",
"subscriber_task_id",
"status",
"events",
"instruction"
]
},
"vaultCreateBodyInput": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"name": {
"type": "string"
},
"env_name": {
"type": "string"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"login": {
"anyOf": [
{
"$ref": "#/components/schemas/LoginInput"
},
{
"type": "null"
}
]
},
"card": {
"anyOf": [
{
"$ref": "#/components/schemas/CardInput"
},
{
"type": "null"
}
]
},
"file": {
"anyOf": [
{
"$ref": "#/components/schemas/vaultFileBodyInput"
},
{
"type": "null"
}
]
},
"share": {
"type": "string"
},
"area_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"replace": {
"type": "boolean"
}
}
},
"vaultFileBodyInput": {
"type": "object",
"properties": {
"filename": {
"type": "string"
},
"content_base64": {
"type": "string"
}
}
},
"vaultFulfillBodyInput": {
"type": "object",
"properties": {
"token": {
"type": "string"
},
"name": {
"type": "string"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"login": {
"anyOf": [
{
"$ref": "#/components/schemas/LoginInput"
},
{
"type": "null"
}
]
},
"card": {
"anyOf": [
{
"$ref": "#/components/schemas/CardInput"
},
{
"type": "null"
}
]
},
"file": {
"anyOf": [
{
"$ref": "#/components/schemas/vaultFileBodyInput"
},
{
"type": "null"
}
]
}
}
},
"vaultRepositoryBodyInput": {
"type": "object",
"properties": {
"repository_url": {
"type": "string"
},
"variables": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
},
"vaultRequestBodyInput": {
"type": "object",
"properties": {
"kind": {
"type": "string"
},
"name": {
"type": "string"
},
"env_name": {
"type": "string"
},
"url": {
"type": "string"
},
"username": {
"type": "string"
},
"cardholder": {
"type": "string"
},
"note": {
"type": "string"
},
"share": {
"type": "string"
},
"area_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"vaultTokenBodyInput": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
}
},
"vaultUpdateBodyInput": {
"type": "object",
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"env_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"login": {
"anyOf": [
{
"$ref": "#/components/schemas/LoginInput"
},
{
"type": "null"
}
]
},
"card": {
"anyOf": [
{
"$ref": "#/components/schemas/CardInput"
},
{
"type": "null"
}
]
},
"file": {
"anyOf": [
{
"$ref": "#/components/schemas/vaultFileBodyInput"
},
{
"type": "null"
}
]
},
"share": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"area_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
}
}
}
}
}