Overview

The Arcalotl public API gives your own systems programmatic access to the same subscriptions, plans, members, and analytics your dashboard shows: read resources, check entitlements, cancel a subscription, generate a checkout link, and subscribe to webhooks for the events that matter to you.

Base URL

https://api.arcalotl.com/v1

Every resource is scoped to the community that owns the API key used to call it. An id that belongs to another community answers 404, never 403, so responses cannot be used to probe another community's data.

Authentication

Every request needs a bearer API key:

Authorization: Bearer arclt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create and revoke keys from the dashboard: Developers -> API Keys. The full key is shown exactly once at creation time; only a display prefix (arclt_live_xxxxxxxx) is stored and shown afterward. Treat a key like a password: do not commit it, and rotate it if it leaks.

Scopes

A key carries one or more scopes chosen at creation time. A request without the scope a route requires gets a 403 with code missing_scope.

Endpoints

Pagination

List endpoints take an opaque cursor and a limit (max 100, default 25) and return a next_cursor:

{
  "data": [ ... ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNy0wMVQxMjowMDowMFoiLCJpZCI6IjEyMyJ9"
}

next_cursor is null (or omitted) on the last page. Pass it back as cursor to fetch the next page; do not construct or parse cursor values yourself, since their internal shape is not part of the contract.

Errors

Errors are RFC 9457 application/problem+json bodies with a stable code extension member for programmatic handling:

{
  "type": "https://docs.arcalotl.com/api/errors#not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource was not found.",
  "code": "not_found"
}

Match on code, not on title or detail, which may change wording without notice.

Rate limits

The API is rate-limited per key, in addition to a lighter pre-authentication limit per client IP:

Every response carries rate limit headers:

RateLimit-Limit: 300
RateLimit-Remaining: 299
RateLimit-Reset: 12

A 429 additionally carries Retry-After (seconds). Back off and retry after that interval rather than polling faster.

Idempotency

POST /v1/subscriptions/{id}/cancel and POST /v1/checkout-links accept an Idempotency-Key header so a network retry cannot double-cancel a subscription or double-create a checkout session:

Idempotency-Key: a-client-generated-unique-string

• The same key with the same request body within 24 hours replays the original response and adds Idempotent-Replayed: true.
• The same key with a different request body returns 422 idempotency_key_reuse.
• The same key while the first request is still being processed returns 409 request_in_flight.
• Keys are scoped per community and per endpoint, and expire after 24 hours.

Use a fresh key per logical operation (for example a UUID you generate once per cancel button click), not a constant value.

Versioning

The API and the webhook event envelope share one version string, currently 2026-07. Within a version, changes are additive only: new fields, new optional request parameters, new event types, and new endpoints. Existing fields and endpoints do not change shape or meaning without a new version. Ignore fields you do not recognize so additive changes never break your integration.

OpenAPI spec

The full request and response contract is published as an OpenAPI 3.1 document: arcalotl-public-api.yaml.

Next steps

• Webhooks: event envelope, the full event catalog, and signature verification.
• Events: polling GET /v1/events for reconciliation.
• Checkout links: sell a plan from your own systems.
• MCP: connect an AI agent to the same API.