Docs · API

Huddle REST API.

Authenticate, script sessions, pull usage, manage keys. The same endpoints the web app uses, open for you to hit directly.

Authentication

Every request carries a bearer token in the Authorization header:

Authorization: Bearer hdl_live_...

Generate a token from Settings → API keys. Tokens are scoped to a user account by default. Workspace admins can mint workspace-scoped tokens that expire at a set date — useful for CI jobs that should stop working automatically when a contract ends. Tokens are shown once at creation time; store them somewhere safe.

The web app itself uses an httpOnly cookie rather than a bearer token, which is why you cannot copy a session cookie out of your browser and use it against the API — they are deliberately different surfaces.

Resource surface

The REST surface is grouped by resource. All endpoints are under https://api.huddleide.com in production or http://localhost:4000 in development.

  • /auth/* — sign-in, sign-up, password reset, OAuth callbacks, active session management.
  • /users/* — current user, profile, preferences.
  • /workspaces/* — list, create, update workspaces and manage members.
  • /sessions/* — create, read, list, and close sessions; manage participants and invites.
  • /keys/* — CRUD for BYOK provider keys (encrypted server-side, never returned in plaintext).
  • /chat — the live LLM proxy. Streams provider SSE through a normalised Huddle SSE channel.
  • /billing/* — checkout sessions, portal URLs, current subscription state.
  • /admin/* — platform-admin only; tenant management, feature flags, system diagnostics.
  • /mcp — OAuth discovery and token exchange for the MCP server.
  • /waitlist, /contact — public, unauthenticated form submissions.
  • /webhooks/* — inbound webhooks (Stripe today, more later).
  • /healthz, /readyz — liveness and readiness probes.

Request and response bodies are JSON, validated server-side with Zod. Every resource returns a stable ID (ULID) that you can round-trip. Timestamps are ISO 8601 UTC.

Rate limits

Rate limits are enforced per-token and per-route-group. The current defaults are:

  • Auth endpoints: 10 requests per IP per minute.
  • Chat proxy: 60 messages per user per minute, plus a provider-imposed token-per-minute cap.
  • Session create: 30 per user per hour.
  • Everything else: 600 per token per minute.

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can back off gracefully. A 429 response means you hit the limit — retry after the Retry-After header.

Error codes

Errors are JSON with a stable code field and a human message:

{
  "error": {
    "code": "key_invalid",
    "message": "Provider rejected the key.",
    "request_id": "01J..."
  }
}
  • 400 invalid_body — the request did not match the schema.
  • 401 unauthenticated — missing or expired token.
  • 403 forbidden — token lacked the required scope.
  • 404 not_found — no resource at that ID.
  • 409 conflict — duplicate resource.
  • 422 key_invalid — BYOK key was rejected by the provider.
  • 429 rate_limited — slow down, check headers.
  • 500 internal — something blew up; include the request_id when reporting.

Webhooks

Outbound webhooks are on the roadmap. In the meantime, if you need to react to session events, either poll the sessions endpoint or connect your agent over MCP and subscribe to the huddle://events/recent resource.