Estratos

API Overview

The Estratos REST API is a RESTful JSON API covering authentication test endpoints and full webhook endpoint management. The memory surface Estratos is built around is exposed to AI assistants over the MCP server rather than these REST endpoints.

Interactive reference: The full API specification with request/response schemas and a built-in "Try it out" tool lives at the interactive API reference. The raw OpenAPI spec is at /api/v1/openapi.yaml. This page is a narrative overview -- use the interactive reference for endpoint-level details.

Base URL

All API endpoints are available at:

https://estratos.ai/api/v1/

Authentication

Every request must include an Authorization header with a Bearer token:

Authorization: Bearer YOUR_API_KEY

There are two ways to get a token:

  • API keys -- workspace owners create keys under API Keys in the sidebar. Pick the scopes the key needs; the key is shown once at creation and is a long-lived Bearer token — paste it directly into the Authorization header, no token exchange required. Keys can be revoked at any time.
  • OAuth 2.0 authorization code grant -- for third-party applications that act on behalf of a user. Estratos is a full OAuth 2.0 provider with authorize, token, revoke, and introspect endpoints under /oauth, dynamic client registration (RFC 7591) at POST /oauth/register, and discovery documents at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. During authorization the user picks which workspace to connect, and the issued token is scoped to it.

API access requires the api-access entitlement on the workspace's plan; without it, requests return 403 with type forbidden.

Scopes

Tokens carry scopes that limit which endpoints they can call:

Scope Grants access to
profile:read Baseline read access — request this for connections that only need to identify the workspace
webhooks:manage Full CRUD on webhook endpoints, plus test deliveries

GET /api/v1/ping and GET /api/v1/me accept any valid token, regardless of scope. Calling an endpoint without the required scope returns 403 with type insufficient_scope.

The memories:* scopes (plus the reserved hierarchy:admin, members:admin, and audit:read scopes) power the AI-assistant surface over the MCP server rather than these REST endpoints — see the MCP scopes table for the full list and what each grants.

Quick start

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://estratos.ai/api/v1/ping

{
  "status": "ok",
  "account": { "id": "…", "name": "Your Workspace" },
  "token": { "application": "My integration", "scopes": ["webhooks:manage"] }
}

Available endpoints

Endpoint Description Required scope
GET /api/v1/ping Health check; returns account and token metadata any valid token
GET /api/v1/me The authenticated workspace's id, name, slug, and token scopes any valid token
GET /api/v1/webhook_endpoints List webhook endpoints webhooks:manage
GET /api/v1/webhook_endpoints/:id Get an endpoint with its 10 most recent deliveries webhooks:manage
POST /api/v1/webhook_endpoints Create an endpoint; the response includes the signing secret (only time it's returned) webhooks:manage
PATCH /api/v1/webhook_endpoints/:id Update an endpoint webhooks:manage
DELETE /api/v1/webhook_endpoints/:id Delete an endpoint and its delivery history webhooks:manage
POST /api/v1/webhook_endpoints/:id/test Send a test ping event and return the delivery result webhooks:manage

See Webhooks for payload formats and signature verification.

Rate limits

All authenticated API requests (including the MCP server) are rate-limited per token:

  • 60 requests per minute
  • 500 requests per hour

Every API response includes:

Header Description
X-RateLimit-Limit Maximum requests in the current window
X-RateLimit-Remaining Requests remaining in the current window
X-RateLimit-Reset Unix timestamp when the window resets

When you exceed a limit you receive 429 Too Many Requests with a Retry-After header and an error envelope of type rate_limited.

Error format

All errors use a consistent JSON envelope:

{
  "error": {
    "type": "not_found",
    "message": "Couldn't find WebhookEndpoint with id=..."
  }
}
Type Status Meaning
authentication_required 401 Missing or malformed Authorization header
invalid_token 401 Token is unknown, revoked, or its application was revoked
token_expired 401 Token has expired (OAuth flows; refresh it)
insufficient_scope 403 Token lacks the required scope
forbidden 403 Plan does not include API access
not_found 404 Resource doesn't exist in this workspace
invalid_request 400 Malformed request body or missing parameter
validation_error 422 Attributes failed validation; the message lists the failures
rate_limited 429 Too many requests

Going further

  • Webhooks -- receive real-time notifications when events happen in your workspace
  • MCP server -- let AI assistants like Claude work with your workspace over the same tokens and scopes
  • Interactive API reference -- schemas, examples, and a try-it-out console