OpenAPI specification

The complete REST API surface is described in OpenAPI 3.1.

Use it

Code generation

# TypeScript fetch client
npx openapi-typescript https://heycmo.ai/openapi.json -o heycmo.d.ts

# Python httpx client
pip install openapi-python-client
openapi-python-client generate --url https://heycmo.ai/openapi.json

View interactively

Paste the URL into any of:

• https://editor.swagger.io/
• https://stoplight.io/studio
• VS Code extension 42Crunch.vscode-openapi

LLM function-calling

Convert to function-calling tool defs:

# OpenAI function-calling shape
npx openapi-to-functions https://heycmo.ai/openapi.json --provider openai

# Anthropic tool_use shape
npx openapi-to-functions https://heycmo.ai/openapi.json --provider anthropic

What's in the spec

• Security scheme: bearerApiKey — HTTP bearer with bearerFormat: hcmo_live_*.
• All public REST endpoints with operationId, summary, parameter descriptions, and typed response schemas.
• Error responses (Unauthorized, Forbidden, NotFound, RateLimited, ServerError) are referenced from components.responses so every operation declares them consistently.
• Retry-After header declared on the 429 response.
• X-Request-ID header declared on every error response.
• Tags: Health, Customer, Content, Workflows, Social, Analytics, Settings, Scan, Chat, Webhooks, Onboarding, Billing, Public.

Drift policy

The spec is hand-written today. The canonical source for endpoints + validation is apps/api/infra/server.ts in the repo. We reconcile drift in this file before each release; long-term we'll auto-generate from the route handlers' zod schemas.

If you spot a discrepancy between the spec and live behaviour, please open an issue at https://github.com/ravidsrk/heycmo/issues with the requestId from the divergent response — that's the fastest way for us to fix it.

See also

• For AI agents
• Authentication
• Endpoints
• Quickstart