API

The Swirls API provides programmatic access to every capability available in the Portal. Use it to manage projects, execute workflows, configure triggers, work with forms, webhooks, schedules, and more.

Base URL

For Swirls Cloud, the base URL is https://swirls.ai/api. For self-hosted deployments, use the URL where your API server is running.

Authentication

Most API endpoints require authentication. Include your API key in the Authorization header:

Authorization: Bearer <apiKey>

Get an API key from the Portal under project settings. The CLI authenticates via a session created by swirls auth login.

Requests with a missing or invalid token receive a 401 Unauthorized response.

Protocol

The Swirls API uses oRPC for its authenticated endpoints. All RPC calls are routed through {baseUrl}/rpc.

The API is not a REST API. There are no separate REST routes for resource management. Use the SDK for typed TypeScript clients. Raw HTTP calls to /rpc are supported but verbose.

Making a raw RPC call

const response = await fetch('https://swirls.ai/api/rpc/projects.listProjects', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <apiKey>',
  },
})
const projects = await response.json()

For POST procedures, send a JSON body:

const response = await fetch('https://swirls.ai/api/rpc/projects.createProject', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <apiKey>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'my-project' }),
})
const project = await response.json()

RPC namespaces

The contract is generated from packages/contract/src/contract.ts. The following namespaces are available.

agents

Agent chat sessions back persistent, multi-turn hosted conversations when agent chat is enabled for a project. Sessions store the full transcript.

projects

workflows

deployments

forms

webhooks

schedules

reviews

Reviews pause workflow execution at any node configured with review: { enabled: true }.

secrets

streams

billing

audit

Audit procedures use cursor-based pagination with limit (1–500, default 100) and optional cursor.

Audit event fields: id, occurredAt, ingestedAt, subject, actorId, actorType (user, service, or agent), orgId, projectId, resourceType, resourceId, action, workflowId, executionId, traceId, outcome (success, failure, or denied), errorCode, metadata.

traces

Execution and agent-session observability. Every procedure is scoped to a project; access is enforced per tenant.

integrations.github

integrations.connections

cli

Public endpoints

The Triggers service (apps/triggers) exposes these endpoints without API key authentication.

Form submission

GET  /triggers/forms/:projectId/:formName
POST /triggers/forms/:projectId/:formName

GET renders the HTML form. Forms with visibility: internal return 404. Forms with basic auth return 401 when credentials are missing.

POST validates the CSRF token, validates the submission against the form schema, and enqueues a workflow execution. Returns 503 if the 5-second hot-path budget is exceeded.

Webhook ingestion

POST /triggers/webhooks/:projectId/:webhookName

Verifies the optional shared secret (header name and value from the webhook's secret block), then enqueues a workflow execution.

Pagination

Standard list operations return:

{
  "pagination": {
    "hasNextPage": true,
    "hasPreviousPage": false,
    "startCursor": "...",
    "endCursor": "..."
  },
  "results": [],
  "totalCount": 42
}

Pass before, after, first, or last to navigate pages. Maximum page size is 500.

Audit procedures use a separate cursor pagination shape:

{
  "data": [],
  "nextCursor": "..."
}

Error handling

The API returns errors in a consistent format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Workflow not found"
  }
}

Next steps

• SDK reference: Typed TypeScript client for every namespace above.
• CLI reference: Authenticate and deploy from the command line.