Introduction

The Appstrate REST API lets you manage agents, run them, and embed them in your own product. The OpenAPI document is the reference.

Quickstart

Create an API key and run an agent with curl.

Authentication

API keys, session cookies, OIDC tokens, and the context headers.

Webhooks

Subscribe to run events. Standard Webhooks spec, HMAC-signed.

Errors

RFC 9457 problem details, stable error codes, request ids.

Endpoint reference

Every operation, generated from the OpenAPI document.

Everything the dashboard does is available over HTTP: agents, runs, schedules, packages (agents, skills, MCP servers, integrations), integration connections, models and proxies, spaces and roles, end-users, API keys, webhooks, files, and realtime streams. The dashboard and the appstrate CLI are clients of this same API.

The API is described by an OpenAPI 3.1 document generated from the code. It is the source of truth for request and response schemas. This documentation covers the cross-cutting rules the schema cannot express well: authentication, context headers, errors, idempotency, pagination, rate limits, and webhooks.

Model in one paragraph

An organization contains spaces. A space is the unit that holds agents, runs, schedules, end-users, files, and API keys. An API key is created in one space and is pinned to it. End-users are your own customers, created through the API inside a space; you act on their behalf with the Appstrate-User header or let them sign in through the OIDC module. See Multi-tenancy.

Base URL

All endpoints live under /api. A local instance serves them at:

http://localhost:3000/api

Use your instance's APP_URL in production; Appstrate Cloud is https://app.appstrate.com/api. There is no version in the path. Versioning is a header, see API Reference.

OpenAPI document

Both are public and need no credentials:

GET /api/openapi.json    # OpenAPI 3.1 document, ETag-aware
GET /api/docs            # Swagger UI

The document is generated by the instance you query, so it includes the modules that instance has loaded (webhooks, OIDC, MCP, chat, billing). The pages generated in this documentation come from the same source.

Inbound MCP endpoint

With the mcp module loaded (it is in the default MODULES set), the API is also exposed to MCP clients as one Streamable HTTP endpoint per organization, /api/mcp/o/{org}. An MCP client searches, describes and invokes the same operations, under the caller's own permissions. The endpoint is an OAuth-protected resource: clients discover the authorization server through /.well-known/oauth-protected-resource/api/mcp/o/{org} (RFC 9728). To point Claude Code, Cursor, or another client at it, follow Connecting MCP clients.

Quickstart: your first calls with curl.
Authentication: keys, sessions, OIDC tokens, headers, scopes.
API Reference: versioning, rate limits, pagination, realtime streams.
Multi-tenancy: organizations, spaces, end-users, impersonation.