API Reference

The Sire API lets you create and manage workflows, start executions, configure webhooks, and manage your account programmatically. All endpoints return JSON and follow consistent conventions for authentication, error handling, and pagination.

Base URL

https://api.sire.run

All API paths are relative to this base URL. For example, listing workflows is a GET request to https://api.sire.run/api/v1/workflows.

Authentication

Sire supports two authentication methods: API keys for server-to-server integrations and Bearer tokens (JWT) for session-based access from the dashboard or SDK.

API Keys

API keys are the recommended way to authenticate programmatic access. Generate keys from Settings > API Keys in the Sire dashboard.

API keys use the prefix sk_ followed by a 64-character hex string. You will only see the full key once at creation time -- store it securely.

Include your API key in the Authorization header:

curl -H "Authorization: Bearer sk_your_api_key_here" \
  https://api.sire.run/api/v1/workflows

Key management endpoints:

Each API key is scoped to your organization. Revoking a key takes effect immediately.

Bearer Tokens (JWT)

Bearer tokens are issued when you log in through the dashboard or via the authentication endpoints. Tokens expire after a set period and can be refreshed using the refresh endpoint.

curl -X POST https://api.sire.run/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

The response includes an access token:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": 1704067200
}

Use the token in subsequent requests:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.sire.run/api/v1/workflows

OAuth Providers

Sire also supports sign-in with Google, GitHub, Apple, and Okta. OAuth flows are initiated from the dashboard and return a Bearer token upon completion.

Rate Limits

API requests are rate-limited per client to ensure fair usage and platform stability. Limits are applied by endpoint category:

When you exceed a rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{"error": "rate limit exceeded"}

Health check endpoints (/healthz, /readyz) are exempt from rate limiting.

Request Format

• All request bodies must be JSON with a Content-Type: application/json header.
• Request bodies are limited to 1 MB.
• Path parameters use the :param convention (e.g., /api/v1/workflows/:id).

Response Format

All successful responses return JSON with an appropriate HTTP status code:

{
  "id": "wf_abc123",
  "name": "My Workflow",
  "createdAt": 1704067200
}

List endpoints return an array:

[
  { "id": "wf_abc123", "name": "My Workflow" },
  { "id": "wf_def456", "name": "Another Workflow" }
]

Error Handling

All error responses use a consistent JSON format:

{
  "error": "A human-readable error message"
}

HTTP Status Codes

Free Tier Limit Error

When free-tier organizations exceed their monthly execution limit, the API returns a 402 with upgrade information:

{
  "error": "free tier limit reached",
  "limit": 50,
  "current": 50,
  "upgrade": "/api/v1/billing/checkout"
}

Endpoint Reference

Authentication

Workflows

Executions

Credentials

Billing

Chat

Webhooks

Marketplace

Teams

Notifications

API Keys

OpenAPI Specification

The full OpenAPI 3.0 specification is available for download. Import it into Postman, Insomnia, or any OpenAPI-compatible client for an interactive API explorer.

Interactive API documentation with request/response examples is available at /docs/api-reference.

SDKs and Tools

• Chat SDK: The @sire/chat embeddable widget connects to the Chat API.
• MCP Server: Use the Sire MCP server for Claude Code and other MCP-compatible agents.
• OpenAPI Spec: Generate client libraries in any language using the OpenAPI spec above.