API

Use the Swirls API to manage projects, deploy definitions, execute workflows, and query project resources. The namespaces below describe the available operations.

Base URL

For Swirls Cloud, the base URL is https://swirls.ai/api. Enterprise deployments in your own environment use the URL of your Swirls API instance.

Authentication

Authenticated RPC endpoints accept a Swirls bearer credential in the Authorization header. The CLI obtains a session through swirls auth login. For your own application, use OIDC federation to exchange a user's identity-provider JWT for a project-scoped credential. There is no standalone project API-key creation screen.

Authorization: Bearer <swirls-bearer-token>

Method availability does not grant permission. Project access and, for administrative operations, organization roles are checked by the API.

Protocol

The SDK uses oRPC over {baseUrl}/rpc, including its request and response serialization. Use the typed client to avoid constructing the wire format by hand:

import { Swirls } from '@swirls/sdk/client'

// Supply a session credential or a token source from @swirls/sdk/auth.
const swirls = new Swirls({ apiKey: credential })
const projects = await swirls.client.projects.listProjects()

RPC namespaces

The generated client reference lists methods, input fields, and output fields from the API contract. It covers projects, deployments, workflows, agents, resources, integrations, access configuration, billing, traces, and Studio. Use those per-method schemas for required parameters and permissions.

Public endpoints

These endpoints use the ingress authentication described below rather than an RPC session credential.

Hosted form pages

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.

Programmatic form submission

POST {baseUrl}/forms/:formName

The JSON submission endpoint the SDK form adapter uses. No CSRF token; rate limited. Include ?projectId=<id> to identify the project, especially when a name has multiple snapshots. Internal forms return 404 and disabled forms are rejected. Validates the payload against the form schema, enqueues a workflow execution, and returns { message, executionIds }.

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
}

For methods accepting pagination, put before, after, first, or last inside that object. Page limits and other pagination shapes vary by method; follow the generated input schema. Trace queries, for example, use a timestamp cursor.

Audit procedures use a separate cursor pagination shape:

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

Error handling

RPC errors are decoded by the SDK into errors with a code and message. Public ingress endpoints use their own response bodies; do not assume that their error JSON matches the RPC protocol.

Common RPC errors include:

Next steps

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