ForjioHuudisIdentityPlugipayPaymentsCatentioAgentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Catentio Docs
⌘K

API reference

The Catentio control-plane API is a REST API that uses JSON for both requests and responses. It's the same API the portal and the SDKs use; if you want to integrate Catentio directly without an SDK, this section covers everything you need.

Base URL

https://catent.io

The control plane is co-located with the portal in v1 (internal mode). API paths live under /v1/* on the same origin.

For self-hosted or non-canonical deployments, point your client at the deployment's portal URL — the API will be there.

Authentication

The control plane accepts three credential shapes, in this order of preference per request:

Header When to use it
Authorization: Bearer <huudis-jwt> CLI / interactive scripts using OIDC device flow.
Authorization: Bearer <cat_ak_...> Server-to-server with a static API key minted in the dashboard.
x-catentio-session The portal's HMAC-signed session cookie. Browser-only; you generally won't set this manually.

All three resolve to the same Principal server-side and the same single-user gate (in v1) applies regardless of which path you took.

See Authentication for the full recipe with worked examples for each.

Response envelope

Every successful API response is wrapped in the Forjio envelope:

{
  "data": { /* the response payload */ },
  "error": null,
  "meta": {
    "requestId": "req_01H...",
    "timestamp": "2026-05-12T10:42:00Z"
  }
}

List endpoints have a paginated variant:

{
  "data": [ /* items */ ],
  "error": null,
  "meta": {
    "requestId": "req_01H...",
    "timestamp": "2026-05-12T10:42:00Z",
    "page": {
      "limit": 50,
      "hasMore": true,
      "nextCursor": "cur_xxx"
    }
  }
}

Errors keep the envelope shape but set error:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "agent slug is required",
    "field": "slug"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

This envelope comes from @forjio/sdk/http and is identical across every Forjio product.

Resources

The API is organised by resource. Each resource has a CRUD-like surface plus action endpoints where the verb isn't list/get/create/delete.

Resource Path prefix What it does
Workspaces /v1/workspaces Tenants.
Agents /v1/agents The agent roster + invoke.
Runs /v1/runs Per-invocation history + cancel.
Projects /v1/projects Pipeline-driven workflows.
Templates /v1/templates Available project templates.
Tools /v1/tools Per-agent tool budget.
Skills /v1/skills Versioned agent playbooks.
Memory /v1/memory RAG entries (OTP-gated mutations).
API keys /v1/api-keys Static credentials.
Billing /v1/billing Catalog, summary, subscribe.
Cost /v1/cost Workspace-level rollups.
Integrations /v1/integrations BYO credentials.
Webhooks /v1/webhooks Outbound event delivery.
Scheduled jobs /v1/scheduled-jobs Runtime cron.
Feature flags /v1/feature-flags Runtime kill switches.
Files /v1/files Run artifacts.
Output destinations /v1/output-destinations Where agent outputs go.
Heartbeats /v1/heartbeats Cron-triggered agent invocations.
System /v1/system Health, info (some unauth).
Chat /v1/chat The chat-bubble REPL backend.
Events /v1/events Outbox events feed.

The 25 namespaces are exposed identically across the Node, Python, and Go SDKs — same method names (modulo language casing), same arguments, same response shapes.

Idempotency

Mutating endpoints (POST, PATCH, DELETE) accept an Idempotency-Key header. Same key within 24 hours returns the same response — no duplicate operation.

Use idempotency keys for any operation that has side effects you don't want to double-fire: invoking an agent, creating a project, registering a webhook.

Rate limits

Default limits per workspace:

Endpoint class Limit
Read (GET) 100 req/sec
Write (POST/PATCH/DELETE) 20 req/sec
Agent invocations 10 req/sec, with a 50-run burst

Limits are returned in response headers:

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

On exceeding the limit you get 429 Too Many Requests with a Retry-After header.

Webhooks

Catentio sends webhook events for state changes you care about: run.succeeded, project.paused, subtask.failed, and so on. Events are signed; you verify the signature before trusting the payload.

The /v1/webhooks endpoints let you register endpoints and view delivery history. Event payloads carry the full Forjio envelope.

OpenAPI spec

A machine-readable OpenAPI 3.0 spec lives in the catentio runtime repo — that's the wire-protocol source of truth, since the runtime is the one defining it. The control plane consumes the same spec.

Next