Skip to main content
This page covers direct HTTP calls to the REST API.If you’re connecting an AI tool via MCP (Cursor, VS Code, Claude Desktop, Claude Code), see Connect HERO to your AI tool for the client-side setup.

​
Base URL

https://app.myhero.so
All endpoints are scoped under /api. Example: https://app.myhero.so/api/document/{documentId}.

​
Authentication

Every request requires a bearer token: 
Authorization: Bearer hero_ak_<your-key>
See Authentication for how to generate one.

​
Your first request

curl https://app.myhero.so/api/workspace/default \
  -H "Authorization: Bearer $HERO_API_KEY"

​
Conventions

  • HTTP verbs — standard GET / POST / PUT / PATCH / DELETE.
    Read endpoints are GET; mutations carry their body as JSON.
  • Content-Type — set Content-Type: application/json on every request with a body. Responses are always JSON unless the endpoint streams (text/event-stream) or returns a binary payload (e.g. exports).
  • IDs — every resource ID is a UUID string.
    Don’t assume incrementing integers.

​
Response shape

Successful responses wrap the payload in a top-level data field: 
{
  "data": { "_id": "ws_...", "name": "Acme", "isPersonal": false }
}
List endpoints return arrays the same way: 
{
  "data": [ { "_id": "doc_..." }, { "_id": "doc_..." } ]
}
A handful of streaming/binary endpoints break this pattern — they’re called out per-route in the API Reference.

​
Errors

All errors return a uniform shape: 
{
  "error": "ValidationError",
  "message": "Request failed schema validation",
  "details": [...]
}
See Errors for the full status code list and error codes.

​
Rate limiting

Requests are throttled per-IP using IETF RateLimit headers — every response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset.
When you exceed a window you get a 429 with a Retry-After header. Default budget is 600 requests per 15 minutes; specific surfaces are tighter (creation routes, export jobs, auth). Treat the headers as the authoritative source — limits get tuned over time.

​
Streaming endpoints

Some routes stream their response as Server-Sent Events (Content-Type: text/event-stream) — most notably POST /ai-agent/stream.
See the streaming demo for a full Node.js client that parses chunks event-by-event.

​
Versioning

The HERO API does not use a version prefix today.
Breaking changes are announced in the changelog and gated behind opt-in headers when introduced.