Public API

Sign up, create products and run tasks on Orkosi from any program or AI agent. API keys, the machine-readable API document, limits and the MCP server.

Everything you can do in the Orkosi hub, a program can do over HTTPS. The public API lives under /api/v1/public, speaks JSON, and is described by one OpenAPI 3.1 document you can import into any client, SDK generator or AI assistant:

https://orkosi.com/api/v1/public/openapi.json

If you are wiring up ChatGPT, Claude or another assistant, read Build with an AI agent first. It uses the same API through a signup call and an MCP server.

Authentication

Every call except signup, health and the document itself carries a tenant API key. Keys start with ak_ and are sent either way:

Authorization: Bearer ak_0123456789abcdef...
X-API-Key: ak_0123456789abcdef...

A key belongs to one workspace and carries scopes. The scopes decide what it may do; the role of the person who created it decides what it may change (archiving a product needs the owner). You get a key in one of two ways:

  • Sign up by API. POST /signup creates the account, the workspace and the first key in one call. See Sign up.
  • Settings → API keys in the hub, for an existing account. Pick the scopes you need; the raw key is shown once.

Scopes follow the resource:action form: products:read, products:write, tasks:read, tasks:write, agents:read, billing:read and others listed at GET /api/settings/api-keys/scopes when signed in. A :write scope includes :read.

Sign up

POST /api/v1/public/signup
Content-Type: application/json

{
  "name": "Acme",
  "email": "founder@acme.com",
  "terms_accepted": true,
  "agent": { "client": "claude" }
}

{
  "data": {
    "api_key": "ak_...",
    "key_prefix": "ak_0123456",
    "scopes": ["products:read", "products:write", "tasks:read", "tasks:write", "agents:read", "billing:read"],
    "account": {
      "user_id": 42,
      "email": "founder@acme.com",
      "tenant_id": "…",
      "tenant_slug": "acme",
      "plan": "free",
      "email_verification": "sent",
      "password": "set one from the \"forgot password\" link"
    },
    "credits": { "granted": 100 },
    "next": { "docs": "…", "openapi": "…", "mcp": "…", "set_password": "…", "dashboard": "…" }
  }
}

What happens: the person's account is created on the free plan with its signup credits, a verification email goes out, and the key in the answer is ready to use. password is optional. Without one the person sets theirs from the "forgot password" link, so an agent never has to invent or store a password. terms_accepted must be true: the person agrees to the terms and the privacy policy.

Limits: signup is rate limited per IP address and per email, one account per email (409 EMAIL_TAKEN), and the free plan holds one product. GET /me answers the workspace, plan, scopes and credit balance of any key.

Products

A product is an app, a site or a SaaS Orkosi builds and hosts. Creating one gives it a URL at once; tasks make it real.

Method and path What it does Scope
GET /products List products (?status=active, paused or archived) products:read
POST /products Create a product: name, optional slug, description, product_type products:write
GET /products/{id} One product: state, lifecycle, URL products:read
PATCH /products/{id} Rename, describe, pause, resume or archive products:write
DELETE /products/{id} Archive (hosting is torn down within a day, nothing is deleted) products:write 
POST /api/v1/public/products
Authorization: Bearer ak_...

{ "name": "Acme CRM", "description": "A CRM for small agencies", "product_type": "saas" }

The answer is { "data": { "id", "slug", "name", "status", "lifecycle", "url", … } }. On the free plan a second product answers 402 PLAN_PRODUCT_LIMIT with the plan to upgrade to. Product types: saas (default), informational, shopify, blog.

Tasks

A task is a work order on a product: "add a login page", "connect Stripe", "write the pricing page". Orkosi plans it, builds it, tests it and deploys it; it is charged in credits when it runs.

Method and path What it does Scope
GET /tasks List tasks (?product_id=, ?status=) tasks:read
POST /tasks Create a task: title, description, product_id, priority tasks:write
GET /tasks/{id} One task: status and resolution tasks:read
PATCH /tasks/{id} Update a task tasks:write
DELETE /tasks/{id} Cancel a task tasks:write

product_id is the numeric id of the product row the hub shows, not the product's uuid. GET /costs answers the spend summary of the workspace (billing:read).

Responses and errors

  • A single item answers { "data": { … } }. A list answers { "data": [ … ], "meta": { "total", "limit", "offset" } } and takes ?limit= (1 to 200) and ?offset=.
  • An error answers { "error": "<message>", "code": "<STABLE_CODE>" } with the matching HTTP status: 400 VALIDATION_ERROR, 401 API_KEY_REQUIRED, 403 INSUFFICIENT_SCOPE, 404 NOT_FOUND, 402 PLAN_PRODUCT_LIMIT, 429 RATE_LIMIT_EXCEEDED.
  • Every keyed call carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. The allowance per minute follows the plan; a 429 carries Retry-After.

The MCP server

The same API is available as a Model Context Protocol server, so an assistant that speaks MCP gets orkosi_whoami, orkosi_list_products, orkosi_create_product, orkosi_create_task and friends as tools:

  • Remote: https://orkosi.com/api/v1/public/mcp (Streamable HTTP, stateless JSON responses; initialize, tools/list and tools/call). Authorization: OAuth 2.1 with dynamic client registration and PKCE (a call without a key answers 401 with WWW-Authenticate: Bearer resource_metadata="https://orkosi.com/.well-known/oauth-protected-resource"; the server metadata is at /.well-known/oauth-authorization-server), or an API key as Authorization: Bearer ak_…. Approving the sign-in creates a key with the agent scopes, listed in Settings → API keys.
  • Local (stdio): a stdio server exists for teams that run the Orkosi code (ORKOSI_API_KEY in its environment, no dependencies beyond Node 18). From a laptop, the remote server above is the one to use.

Every tool call is a call to this API with your key, so scopes, plan limits, rate limits and credits apply exactly as above. Build with an AI agent has the configuration for ChatGPT, Claude and Cursor.

This page as Markdown: /docs/public-api.md. All documentation in one file: /llms-full.txt.