{"openapi":"3.1.0","info":{"title":"Orkosi public API","version":"1.2.0","summary":"Sign up, create products and run tasks on Orkosi from any program or AI agent.","description":"Orkosi builds, hosts and maintains web apps and SaaS products from a written brief. This API lets a program or an AI assistant (ChatGPT, Claude, Grok, Gemini …) create an account for a person, get an API key in the same call, and then create and manage products and tasks. Authentication: `Authorization: Bearer ak_…` or `X-API-Key: ak_…`. Lists use `?limit=&offset=` and answer `{ data: [...], meta: { total, limit, offset } }`; single items answer `{ data: {...} }`; errors answer `{ error, code }`. Signup is rate limited per IP and per email; every key is rate limited per plan (X-RateLimit-* headers). The same API is available as an MCP server at /api/v1/public/mcp.","termsOfService":"https://orkosi.com/terms","contact":{"name":"Orkosi","url":"https://orkosi.com/docs/public-api"}},"servers":[{"url":"https://orkosi.com/api/v1/public"}],"tags":[{"name":"account","description":"Sign up and identity"},{"name":"products","description":"The products (apps, sites, SaaS) of the workspace"},{"name":"tasks","description":"Work orders on a product; Orkosi builds them"},{"name":"agents"},{"name":"templates"},{"name":"companies"},{"name":"protocols"},{"name":"runs"},{"name":"billing"},{"name":"mcp","description":"Model Context Protocol transport"},{"name":"meta"}],"paths":{"/signup":{"post":{"tags":["account"],"operationId":"signup","summary":"Create an account and get an API key","description":"No authentication. Creates the person’s account and workspace on the free plan with its signup credits, and returns an API key with the scopes products:read, products:write, tasks:read, tasks:write, agents:read, billing:read (keys with other scopes are created from Settings → API keys). Limits: per-IP and per-email rate limits, one account per email (409 EMAIL_TAKEN).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}}},"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SignupResponse"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An account with this email already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"tags":["account"],"operationId":"me","summary":"Who am I: workspace, plan, scopes and credit balance","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Me"}}}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"tags":["products"],"operationId":"list_products","summary":"List products","description":"Scope products:read. Archived products are hidden unless ?status=archived.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","paused","archived"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["products"],"operationId":"create_product","summary":"Create a product","description":"Scope products:write. The free plan holds one product; 402 PLAN_PRODUCT_LIMIT names the plan to upgrade to. The product starts as a placeholder with its own URL; tasks make it real.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan product limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}":{"get":{"tags":["products"],"operationId":"get_product","summary":"Get a product","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["products"],"operationId":"update_product","summary":"Rename, describe, pause, resume or archive a product","description":"Scope products:write. status=archived needs the owner role on the product.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["products"],"operationId":"archive_product","summary":"Archive a product (nothing is deleted)","description":"Scope products:write and the owner role. Hosting is torn down within a day; data is kept.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}/status":{"get":{"tags":["products"],"operationId":"get_product_status","summary":"Status of a product: hosting environments, latest builds/deploys and tasks","description":"Scope products:read. Answers { product, environments: [{ env, status, health, hostname, deployments: [...] }], tasks: { by_status, recent } }. tasks is null when the key lacks tasks:read. Only the key’s own tenant.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":{"type":"object","additionalProperties":true}}}}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"tags":["meta"],"operationId":"openapi","summary":"This document","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/mcp":{"post":{"tags":["mcp"],"operationId":"mcp","summary":"Model Context Protocol endpoint (Streamable HTTP, stateless)","description":"Send JSON-RPC 2.0 messages: initialize, tools/list, tools/call. The tools wrap this API (whoami, products, tasks, costs). Authenticate with the API key like every other call.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRequest"}}}},"responses":{"200":{"description":"JSON-RPC response (or an array for a batch); 202 for a notification","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["mcp"],"operationId":"mcp_info","summary":"Transport note: this server answers POST only (no server-sent events)","security":[],"responses":{"405":{"description":"Use POST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks":{"get":{"tags":["tasks"],"operationId":"list_tasks","summary":"List tasks","description":"Scope tasks:read.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"priority","in":"query","schema":{"type":"string"}},{"name":"product_id","in":"query","schema":{"type":"string"},"description":"Product id (uuid) or slug"},{"name":"assignee","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["tasks"],"operationId":"create_task","summary":"Create a task on a product","description":"Scope tasks:write. A task is a work order Orkosi builds; it is charged in credits when it runs.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"product_id is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{id}":{"get":{"tags":["tasks"],"operationId":"get_task","summary":"Get a task","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["tasks"],"operationId":"update_task","summary":"Update a task","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["tasks"],"operationId":"cancel_task","summary":"Cancel a task (status cancelled)","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents":{"get":{"tags":["agents"],"operationId":"list_agents","summary":"List agents","description":"Scope agents:read.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Meta"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["agents"],"operationId":"create_agent","summary":"Create a agent","description":"Scope agents:write.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{id}":{"get":{"tags":["agents"],"operationId":"get_agent","summary":"Get a agent","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["agents"],"operationId":"update_agent","summary":"Update a agent","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["agents"],"operationId":"delete_agent","summary":"Archive a agent","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates":{"get":{"tags":["templates"],"operationId":"list_templates","summary":"List templates","description":"Scope protocols:read.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Meta"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["templates"],"operationId":"create_template","summary":"Create a template","description":"Scope protocols:write.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/{id}":{"get":{"tags":["templates"],"operationId":"get_template","summary":"Get a template","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["templates"],"operationId":"update_template","summary":"Update a template","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["templates"],"operationId":"delete_template","summary":"Archive a template","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies":{"get":{"tags":["companies"],"operationId":"list_companies","summary":"List companies","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["companies"],"operationId":"create_company","summary":"Create a company","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{id}":{"get":{"tags":["companies"],"operationId":"get_company","summary":"Get a company","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{id}/members":{"get":{"tags":["companies"],"operationId":"list_company_members","summary":"List members","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["companies"],"operationId":"add_company_member","summary":"Add a member","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{id}/members/{userId}":{"delete":{"tags":["companies"],"operationId":"remove_company_member","summary":"Remove a member","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/protocols":{"get":{"tags":["protocols"],"operationId":"list_protocols","summary":"List protocols","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["protocols"],"operationId":"create_protocol","summary":"Create a protocol","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/protocols/{id}":{"get":{"tags":["protocols"],"operationId":"get_protocol","summary":"Get a protocol","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/protocols/{id}/run":{"post":{"tags":["protocols"],"operationId":"run_protocol","summary":"Run a protocol","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"Run started","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runs":{"get":{"tags":["runs"],"operationId":"list_runs","summary":"List agent runs","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runs/{id}":{"get":{"tags":["runs"],"operationId":"get_run","summary":"Get an agent run","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs":{"get":{"tags":["billing"],"operationId":"costs","summary":"Spend summary of the workspace","description":"Scope billing:read.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"tags":["meta"],"operationId":"health","summary":"API health","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/tasks/{id}/decide":{"post":{"tags":["tasks"],"operationId":"decide_task","summary":"Approve, reject or answer a task that waits for the person","description":"Scope tasks:write. approve / reject settle a pending approval card (else approve queues a pending_approval, on_hold, waiting_for_user or blocked task); answer records the answer to the task question and continues the task.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","reject","answer"]},"note":{"type":"string","maxLength":1000,"description":"Recorded with an approve / reject"},"answer":{"type":"string","maxLength":4000,"description":"The answer text (decision answer)"},"option_id":{"type":"string","maxLength":120,"description":"The chosen option id (decision answer)"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":{"type":"object","properties":{"task_id":{"type":"integer"},"decision":{"type":"string"},"status":{"type":"string","description":"The task status after the decision"},"approval_id":{"type":"string"},"already_decided":{"type":"boolean"},"queued":{"type":"boolean"},"comment_id":{"type":"integer"},"resumed":{"type":"boolean"}}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Nothing to decide on this task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{id}/report":{"get":{"tags":["tasks"],"operationId":"get_task_report","summary":"The task report as Markdown","description":"Scope tasks:read. What was done, the resolution, the pull request, the open question if any.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":{"type":"object","properties":{"task_id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string"},"product_slug":{"type":"string","nullable":true},"pr_url":{"type":"string","nullable":true},"resolution":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"markdown":{"type":"string","description":"The report as Markdown"}}}}}}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits":{"get":{"tags":["billing"],"operationId":"get_credits","summary":"Credit balance of the workspace","description":"Scope billing:read. The balance the Billing page shows, with what running tasks hold.","security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":{"type":"object","properties":{"balance":{"type":"integer","description":"Credits"},"balance_cents":{"type":"integer"},"reserved_cents":{"type":"integer","description":"Held by running or paused tasks"},"available_cents":{"type":"integer"},"reserved_by":{"type":"array","items":{"type":"object"}}}}}}}}}},"401":{"description":"No or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKeyBearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer ak_…"},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human readable message"},"code":{"type":"string","description":"Stable machine code, e.g. VALIDATION_ERROR, NOT_FOUND, PLAN_PRODUCT_LIMIT"}},"required":["error"]},"Meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"SignupRequest":{"type":"object","required":["name","email","terms_accepted"],"properties":{"name":{"type":"string","maxLength":128,"description":"The person or company the workspace is for"},"email":{"type":"string","format":"email","description":"The person’s email; a verification mail is sent"},"terms_accepted":{"type":"boolean","enum":[true],"description":"The person agrees to the terms of service and privacy policy"},"password":{"type":"string","minLength":12,"maxLength":128,"description":"Optional. Upper, lower, digit and symbol. Without one the person sets a password from the \"forgot password\" email."},"agent":{"type":"object","properties":{"client":{"type":"string","enum":["chatgpt","claude","grok","gemini","perplexity","copilot","cursor","other"]},"model":{"type":"string","maxLength":120}}}}},"SignupResponse":{"type":"object","properties":{"api_key":{"type":"string","description":"ak_… key, shown once. Send it as Authorization: Bearer or X-API-Key."},"key_prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"account":{"type":"object","properties":{"user_id":{"type":"integer"},"email":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"},"tenant_slug":{"type":"string"},"plan":{"type":"string"},"email_verification":{"type":"string"},"password":{"type":"string"}}},"credits":{"type":"object","properties":{"granted":{"type":"integer"}}},"next":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}}},"Me":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}},"tenant":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"}}},"user_id":{"type":"integer"},"credits":{"type":"object","properties":{"credits":{"type":"integer"},"cents":{"type":"integer"}}},"products":{"type":"integer"}}},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["active","paused","archived"]},"app_type":{"type":["string","null"]},"product_type":{"type":["string","null"]},"lifecycle":{"type":["string","null"],"description":"Hosting lifecycle (draft, queued, provisioning, live, failed …)"},"provisioning_status":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProductCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":2,"maxLength":200},"slug":{"type":"string","description":"Lower-case letters, digits and hyphens; derived from the name when absent"},"description":{"type":"string","maxLength":5000},"app_type":{"type":"string","description":"web (default), mobile, api …"},"product_type":{"type":"string","description":"saas, informational, shopify … (see /docs/public-api)"}}},"ProductUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":200},"description":{"type":"string","maxLength":5000},"status":{"type":"string","enum":["active","paused","archived"]}}},"Task":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string"},"priority":{"type":"string"},"status":{"type":"string"},"assignee":{"type":["string","null"],"description":"The agent working the task"},"product_slug":{"type":"string","description":"The product the task belongs to (its slug)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TaskCreate":{"type":"object","required":["title","product_id"],"properties":{"title":{"type":"string","maxLength":500},"description":{"type":"string"},"type":{"type":"string"},"priority":{"type":"string","enum":["low","medium","high","critical"]},"product_id":{"type":"string","description":"The product the task belongs to: the id GET /products answers (a uuid), or its slug"},"product_slug":{"type":"string","description":"The product slug (alternative to product_id)"},"worker_tier":{"type":["string","integer"],"description":"Worker tier slug or level 1–4; default: the product’s"},"output_type":{"type":"string","description":"Expected output kind (default text)"}}},"McpRequest":{"type":"object","description":"A JSON-RPC 2.0 request (or an array of them) in the Model Context Protocol","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string","enum":["initialize","notifications/initialized","ping","tools/list","tools/call"]},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}}