Overview & authentication

The REST API exposes full programmatic control of the platform, every action available in the app is available here. The MCP server wraps the same operations for AI agents.

Base URL

https://usehunch.co/api/v1

Authentication

Create an API key in Settings → API & Keys or via the keys endpoint. Keys are shown once at creation, store them securely. A key grants full read/write access to the workspace it belongs to. Pass it as a Bearer token:

curl https://usehunch.co/api/v1/accounts \
  -H "Authorization: Bearer hunch_YOUR_KEY"

Response format

Single resources and actions are wrapped in a data object:

{ "data": { "id": "...", "name": "..." } }

List endpoints include a pagination block:

{
  "data": [ ... ],
  "pagination": {
    "total": 214,
    "page": 1,
    "per_page": 50,
    "has_more": true
  }
}

Errors return an error string with an appropriate HTTP status:

{ "error": "Invalid or missing API key" }

Pagination

Paginated endpoints (accounts, runs, monitor events) accept:

Status codes

• 200, success. 201, resource created. 202, run accepted and queued.
• 400, invalid request body or parameters.
• 401, missing or invalid API key.
• 402, an active subscription is required (activation, scans, and run triggers).
• 404, resource not found in your workspace.
• 500, server error.

Workspace scoping

Every request is scoped to the workspace that owns the API key. You can only read and write data within that workspace, there is no cross-workspace access.

Resources