Public REST API (v1)

Hydra exposes a versioned REST API at /api/v1/* for programmatic access to your workspace data. It's the same data your inbox, CRM, and ticket views are built on — same tenant scoping, same role checks, just over HTTP.

Authentication

The public API uses the same bearer-token scheme as Hydra's MCP integration. Mint a key at Settings → API Access, then send it as a Bearer token on every request:

curl -H "Authorization: Bearer hmcp_..." https://hydra-one-tau.vercel.app/api/v1/leads

Keys are tenant-scoped — every request reads and writes within the workspace that minted the key. There's no way for one key to reach another tenant's data.

Scopes

Each key is granted a set of scopes at mint time. The public API enforces them per-route:

A request with an insufficient scope returns 403 forbidden_scope:

{
  "error": "Missing required scope(s): crm:write. Your key has [crm:read].",
  "code": "forbidden_scope"
}

Rate limiting

Every API key is capped at 60 requests per minute, sliding window. Exceeding the cap returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{
  "error": "Rate limit exceeded. Limit 60 requests per minute per API key.",
  "code": "rate_limited"
}

Successful responses include X-RateLimit-Limit and X-RateLimit-Remaining headers so you can pace your traffic.

The 60/min cap is the v1 default. Per-key custom caps (e.g. higher for production keys, lower for staging keys) ship in a later wave.

Response envelopes

Success

Successful responses return the bare resource (or a list keyed by entity name):

// GET /api/v1/leads
{ "leads": [ { "id": "...", "email": "...", ... } ], "count": 1 }

// GET /api/v1/leads/[id]
{ "lead": { "id": "...", "email": "...", ... } }

// POST /api/v1/leads → 201
{ "lead": { "id": "...", "email": "...", ... } }

// DELETE /api/v1/leads/[id] → 204 No Content

Error

All errors share a single envelope with a stable code field:

{
  "error": "Human-readable message.",
  "code": "validation_error"
}

Stable error codes (branch on these, not on the message text):

Endpoints

/api/v1/leads

A lead row looks like:

{
  "id": "uuid",
  "tenant_id": "uuid",
  "email": "alice@example.com",
  "name": "Alice Example",
  "phone": null,
  "company": "Example Co",
  "source": "public_api",
  "source_bot_id": null,
  "source_conversation_id": null,
  "created_at": "2026-04-29T..."
}

/api/v1/contacts

Contacts are customers attached to an account. The customers_contact_requires_account DB CHECK means every contact MUST have an account_id — create the account first if needed.

A contact row:

{
  "id": "uuid",
  "tenant_id": "uuid",
  "account_id": "uuid",
  "email": "alice@example.com",
  "name": "Alice Example",
  "phone": null,
  "company": null,
  "source": "public_api",
  "source_bot_id": null,
  "source_conversation_id": null,
  "created_at": "2026-04-29T..."
}

/api/v1/accounts

Valid enums:

• lifecycle_stage: prospect, active, at_risk, churned
• renewal_status (nullable): upcoming, at_risk, renewed, churned

/api/v1/conversations

Read + targeted-update only. Conversations are created by widget sessions and inbound email — there's no sensible POST shape for partners.

Valid status values exposed via PATCH: resolved, escalated. The full read enum is open | assigned | waiting | resolved | escalated.

Conversation rows include rolled-up tags from the bot pipeline: intent, sentiment, language, plus resolved_at, handoff_at, handoff_reason. These fields are read-only over the public API.

/api/v1/tickets

Valid enums:

• status: open, in_progress, resolved, closed
• priority: low, normal, high, urgent

OpenAPI 3.1 spec + interactive docs

• Spec: https://hydra-one-tau.vercel.app/openapi.yaml — committed in the Hydra repo at public/openapi.yaml. Use it to generate clients (openapi-generator, hey-api, etc.) or import into Postman / Insomnia.
• Interactive explorer: hydra-help.com/docs/api — Stoplight Elements rendering of the same spec, with try-it-now requests against your tenant key.

How this differs from /api/mcp/v1/*

Hydra also exposes an MCP-shaped surface at /api/mcp/v1/* for AI tool integrations (Claude, Cursor, custom MCP clients). It uses the same bearer keys but a two-step preview/confirm flow for writes — better suited to LLM agents that should ask the user before committing a change.

The public REST API at /api/v1/* is direct: POST creates, PATCH updates, DELETE deletes — no nonce dance. This is the right shape for Zapier, n8n, custom workflows, and any partner integration that's already gating writes upstream.

Both surfaces share the same tenant scoping, the same audit log, and the same rate-limit infrastructure.