ForjioHuudisIdentityPlugipayPaymentsCatentioAgentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Catentio Docs
⌘K

Resources

The Catentio control plane exposes its routes under /v1/*, organised by the noun they manage: a workspace, an agent, a run, a project, a tool. This index lists the user-facing ones and links to each reference page.

Pages here cover the wire protocol — object shape, endpoint paths, query params, error bodies. For idiomatic SDK usage see SDK overview. For the dashboard equivalents see Portal.

These are the INTERNAL control-plane paths, not the public API. They are not reachable with an API key. From a signed-in browser, a control-plane path is reached through the portal proxy: /api/v1/cp/<path>.

If you are building against Catentio from your own code, you want the public API — nine endpoints at https://catent.io/v1/, authenticated with Authorization: Bearer cat_pk_.... Its paths resemble some of the ones below and are not the same surface.

Core

Resource Path What
Workspaces /v1/workspaces Tenant deployments + state machine.
Agents /v1/agents Roster, detail, CRUD. (invoke is broken.)
Runs /v1/runs Start a run, list history, events, cancel, retry.
Projects /v1/projects Pipeline-driven multi-step workflows: lifecycle, gates, backtrack.
Workflows /v1/workflows Versioned workflows — full CRUD.

Knowledge + capability

Resource Path What
Tools /v1/tools The capability registry.
Skills /v1/skills Versioned agent playbooks.
Memory /v1/memory RAG entries (OTP-gated mutations).

Account + integrations

Resource Path What
API keys /v1/api-keys Static cat_pk_* credentials — verified by the runtime, not the control plane.
Billing /v1/billing Tier catalog, subscribe, wallet, top-up, period summary.
Integrations /v1/integrations BYO credentials.
Scheduled jobs /v1/scheduled-jobs Runtime cron triggers.

Eventing

Resource Path What
Events /v1/events Queryable archive of runtime state changes. Poll it.
Webhook gates /v1/webhooks Inbound gates: a pipeline step blocks until an external system calls back. List only.
Webhooks (outbound) /v1/webhooks (public API) Outbound: Catentio POSTs to a URL you register when a run or project finishes.

Conventions across resources

  • Auth. Almost every route accepts the x-catentio-session header and nothing else. A Huudis Bearer JWT works only on billing, most of chat, and workspaces list/get/create/delete. API keys (cat_pk_*) are a runtime credential — the control plane never checks them. See Authentication.
  • No envelope. Responses are plain FastAPI JSON. Lists return { data, meta } where meta varies by route; detail routes return the object directly. There is no error key, no requestId, no timestamp.
  • Pagination is limit / offset. There are no cursors.
  • Errors are {"detail": …}. Validation failures are 422. Runtime failures are re-raised with the runtime's status and its payload nested under detail.
  • No idempotency keys. POST / PATCH / DELETE do not honour an Idempotency-Key header; a retried POST fires again.
  • Identifiers. Workspaces use the Huudis-issued id (the control plane calls it huudis_workspace_id). API keys are minted as cat_pk_… and referenced by an integer id. Projects use <title-slug>-<8 hex chars> (title-derived). Runs use a 26-char lowercase base32 id with no prefix. Event rows use integer ids.
  • Scope. Every route is scoped to the caller's customer_id server-side; a customer_id in a request body is ignored.
  • Limits. No HTTP rate limiting. Tier plan caps (e.g. runs/day) reject with 403 plan_limit_exceeded.

Not on this list

Operational namespaces without a dedicated reference page:

  • /v1/system — health, info, reload. /healthz and /v1/preflight also exist.
  • /v1/discord, /v1/heartbeats, /v1/output-destinations, /v1/files, /v1/feature-flags, /v1/run-artifacts, /v1/runners, /v1/benchmarks, /v1/resources, /v1/miniapps — portal-facing surfaces.
  • /v1/gojo — internal tenant only.
  • /v1/chat — the chat-bubble backend.
  • /v1/crm-admin, /v1/customers — admin-only.

For wire-level detail on these, the FastAPI route definitions are the source of truth: control_plane/app/routes/ in saas-catentio, and app/runtime/ in catentio. There is no published OpenAPI file.

Next

  • Authentication — what each credential actually opens.
  • Runs — the resource everything else orbits.
  • SDK overview — what the Node / Python / Go bindings can reach today.