HTTP API

Clawnify exposes a public HTTP API for managing apps, organizations, deployments, credentials, and webhooks. Full endpoint reference (Scalar UI, request/response shapes, try-it-out) lives at api.clawnify.com/reference.

This page covers what the auto-generated reference doesn’t: how to get a token, how auth works, and how to deal with rate limits.

Authentication

All API endpoints require a Bearer token in the Authorization header.

Authorization: Bearer <your_token>

There are two flows for getting a token, depending on who’s calling.

Personal access token — `clawnify login`

For your own scripts, dashboards, and ad-hoc integration work. The CLI handles the OAuth 2.1 PKCE dance for you:

npm install -g clawnify
clawnify login

The browser opens, you authenticate, and the CLI stores credentials at ~/.clawnify/auth.json. From there on every CLI command — and the clawnify mcp bridge to mcp.clawnify.com — uses that token automatically.

If you need the raw token to call the API directly from a script:

cat ~/.clawnify/auth.json | jq -r .access_token

Token refreshes happen automatically in the CLI; if you cached the raw value, expect to re-fetch when it expires (~1 hour).

External MCP client — OAuth 2.1 PKCE

For integrations that aren’t shell-based (Claude Desktop, ChatGPT custom apps, embedded clients), the OAuth flow is the same standard PKCE pattern. Two paths:

Use the MCPB bundle — one-click for Claude Desktop. The bundle prompts for your personal token at install time and the bridge handles everything else.
Implement PKCE directly — start the authorization-code-with-PKCE flow at https://app.clawnify.com/oauth/consent, exchange the code for an access token. The OAuth 2.1 PKCE specification covers the full handshake; our endpoints follow it without modification.

Org selection

Your account may belong to multiple orgs. By default the API resolves the active one as the first org you joined. To override per-request, send the org’s UUID in the X-Clawnify-Org-Id header:

X-Clawnify-Org-Id: 6c9c4b21-...

The MCP gateway accepts the same header. The CLI’s clawnify org use <slug-or-id> sets a default that travels with every CLI call.

Rate limits

Endpoints are rate-limited per-org and per-route. Limits are tuned to keep the platform responsive; reasonable usage from a single integration stays well under them.

When you hit a limit:

HTTP/1.1 429 Too Many Requests
content-type: application/json

{ "error": "rate_limited" }

Back off and retry. If you have a legitimate use case that needs higher limits — bulk migration, sustained high-volume integration — talk to us.

Endpoint reference

Full spec, request/response shapes, “try it” UI:

api.clawnify.com/reference — Scalar-powered HTML reference
api.clawnify.com/openapi.json — raw OpenAPI 3.1 document
api.clawnify.com/llms.txt — LLM-optimized Markdown rendering

The OpenAPI document is the canonical source. The Scalar UI and the llms.txt are both generated from it.