API

Reference for the Swirls API -- authentication, RPC endpoints, public endpoints, pagination, and error handling.

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

Base URL

All API requests are made against your Swirls deployment's base URL. If you are using Swirls Cloud, the base URL is provided in your account dashboard. For self-hosted deployments, this is the URL where your API server is running.

Authentication

Most API endpoints require authentication. Include a valid JWT in the Authorization header of each request:

Authorization: Bearer <token>

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

Protocol

The Swirls API uses oRPC (type-safe RPC) for its authenticated endpoints. All RPC requests are routed through the /rpc path prefix. In addition, Swirls exposes several public REST-style endpoints for form submissions, webhooks, and agent chat that do not require authentication.

RPC endpoints

The following domains are available through the RPC layer. Each domain groups related operations.

Projects

Operation	Description
`createProject`	Create a new project with a given name.
`getProject`	Retrieve a project by ID.
`listProjects`	List all projects accessible to the authenticated user.
`createStorage`	Provision a storage instance for a project.
`getStorage`	Retrieve storage instance status and health for a project.

Graphs

Operation	Description
`createGraph`	Create a new graph within a project.
`getGraph`	Retrieve a graph by ID, including its nodes and edges.
`updateGraph`	Update a graph's name, description, or folder.
`deleteGraph`	Delete a graph.
`listGraphs`	List graphs in a project, optionally filtered by folder. Paginated.
`syncGraph`	Synchronize a graph's nodes and edges in a single operation. Creates, updates, and deletes nodes and edges to match the provided state.
`createNode`	Add a node to a graph. Node names must be unique within a graph.
`updateNode`	Update a node's type, configuration, schema, position, or other properties.
`deleteNode`	Remove a node from a graph. Edges must be deleted first.
`createEdge`	Add a directed edge between two nodes. Cycles are not allowed.
`deleteEdge`	Remove an edge.
`executeGraph`	Execute a graph from its root node with a given input payload. Returns an execution ID.
`getExecution`	Retrieve a graph execution by ID, including all node executions.
`listExecutions`	List executions for a graph. Paginated.
`listTriggers`	List triggers attached to a graph. Paginated.
`getStream`	Retrieve the stream associated with a graph, if one exists.

Forms

Operation	Description
`createForm`	Create a new form in a project. Names must be unique within a project.
`getForm`	Retrieve a form by ID.
`updateForm`	Update a form's name, description, schema, enabled status, or folder.
`deleteForm`	Delete a form.
`listForms`	List forms in a project, optionally filtered by folder. Paginated.
`listTriggersForForm`	List all triggers that reference a given form. Paginated.

Webhooks

Operation	Description
`createWebhook`	Create a new webhook in a project. Names must be unique within a project.
`getWebhook`	Retrieve a webhook by ID.
`updateWebhook`	Update a webhook's name, description, schema, enabled status, or folder.
`deleteWebhook`	Delete a webhook.
`listWebhooks`	List webhooks in a project, optionally filtered by folder. Paginated.
`listTriggersForWebhook`	List all triggers that reference a given webhook. Paginated.

Schedules

Operation	Description
`createSchedule`	Create a new schedule with a cron expression and optional timezone.
`getSchedule`	Retrieve a schedule by ID.
`updateSchedule`	Update a schedule's name, cron expression, timezone, or enabled status.
`deleteSchedule`	Delete a schedule.
`listSchedules`	List schedules in a project, optionally filtered by folder. Paginated.
`listTriggersForSchedule`	List all triggers that reference a given schedule. Paginated.

Agents

Operation	Description
`createAgent`	Create a new agent with a prompt and optional tool trigger bindings.
`getAgent`	Retrieve an agent by ID, including its tool configuration.
`updateAgent`	Update an agent's name, description, prompt, or tools.
`deleteAgent`	Delete an agent.
`listAgents`	List agents in a project, optionally filtered by folder. Paginated.

Triggers

Triggers connect a resource (form, webhook, schedule, or agent) to a graph. When the resource fires, the trigger executes the connected graph.

Operation	Description
`createTrigger`	Create a trigger linking a resource to a graph. The graph must have a valid root node.
`getTrigger`	Retrieve a trigger by ID.
`updateTrigger`	Update a trigger's enabled status, graph, or resource binding.
`deleteTrigger`	Delete a trigger.
`listTriggers`	List triggers in a project, optionally filtered by graph or resource. Paginated.
`listSchemaIncompatibilities`	List triggers with schema incompatibilities in a project. Paginated.
`executeTriggers`	Execute all valid triggers for a given resource with a payload. Returns execution IDs.

Schemas

Operation	Description
`createSchema`	Create a reusable JSON Schema in a project. Names must be unique within a project.
`getSchema`	Retrieve a schema by ID.
`updateSchema`	Update a schema's name, description, definition, or folder.
`deleteSchema`	Delete a schema.
`listSchemas`	List schemas in a project, optionally filtered by folder. Paginated.

Streams

Streams persist graph execution output to a structured data table.

Operation	Description
`createStream`	Create a stream linked to a graph. Streams have a 1:1 relationship with graphs.
`getStream`	Retrieve a stream by ID, including its associated graph.
`updateStream`	Update a stream's name, description, persistence condition, or enabled status.
`deleteStream`	Delete a stream.
`listStreams`	List streams in a project. Paginated.
`listStreamSchemas`	List schema versions for a stream. Paginated.
`promoteStreamSchema`	Promote a draft schema version to production and create the backing table.
`getStreamTableSchema`	Retrieve the table schema for a stream's current production version.
`listStreamTableColumns`	List the columns in a stream's backing table.
`executeStreamQuery`	Query a stream's persisted data with optional filters, limit, and offset.

Secrets

Operation	Description
`createSecret`	Create an encrypted secret (key-value pair) in a project's storage.
`getSecretValue`	Retrieve the decrypted value of a non-sensitive secret. Sensitive secrets cannot be revealed.
`updateSecret`	Update a secret's key, value, or sensitivity flag.
`deleteSecret`	Delete a secret.
`listSecrets`	List all secrets in a project (values are masked).

Folders

Operation	Description
`createFolder`	Create a folder within a project for organizing resources.
`getFolder`	Retrieve a folder by ID.
`updateFolder`	Update a folder's name.
`deleteFolder`	Delete a folder.
`listFolders`	List folders in a project. Paginated.

Reviews

Reviews enable human-in-the-loop approval during graph execution. When a node is configured for review, execution pauses until the review is approved or rejected.

Operation	Description
`listReviews`	List reviews for a project, optionally filtered by status. Defaults to pending reviews. Paginated.
`getReview`	Retrieve a review by ID, including the associated node and execution details.
`approveReview`	Approve a pending review, optionally providing form data that is validated against the node's review schema. Resumes execution.
`rejectReview`	Reject a pending review with an optional reason. Resumes execution with a failure state.

Public endpoints

The following REST endpoints do not require authentication and are designed for external integrations.

Form submission

POST /forms/:formId

Submit data to a form. The request body must be valid JSON. If the form has triggers attached, all enabled triggers execute and the response includes the resulting execution IDs.

Response:

{
  "message": "Form submitted successfully",
  "executionIds": ["exec_abc123", "exec_def456"]
}

Webhook

POST /webhooks/:webhookId

Send a payload to a webhook endpoint. If the webhook is enabled and has triggers attached, all matching triggers execute.

Response:

{
  "message": "Webhook received",
  "executionIds": ["exec_abc123"]
}

Agent chat

POST /agents/:agentId/chat

Send a message to an agent and receive a streaming response. The request body includes an array of messages and an optional conversationId to continue an existing conversation. This endpoint requires authentication and returns a streaming text/event-stream response.

Request body:

{
  "messages": [
    { "id": "msg_1", "role": "user", "parts": [{ "type": "text", "text": "Hello" }] }
  ],
  "conversationId": "conv_abc123"
}

Pagination

All list operations use cursor-based pagination and return results in the following structure:

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

Pass before, after, first, or last parameters to control which page of results is returned.

Error handling

The API returns errors in a consistent format:

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

Error codes:

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Authentication is missing or invalid.
`FORBIDDEN`	403	The authenticated user does not have access to the requested resource.
`BAD_REQUEST`	400	The request is malformed or contains invalid parameters.
`NOT_FOUND`	404	The requested resource does not exist.
`INTERNAL_SERVER_ERROR`	500	An unexpected error occurred on the server.

Next steps

CLI reference -- Authenticate and generate code from the command line.
Portal guide -- Build graphs, forms, and triggers through the visual interface.
Schemas guide -- Define and manage JSON Schemas for your resources.

API

On this page