API Reference

The HydraCore control plane is a FastAPI service. The full OpenAPI specification is exposed live in three formats — pick whichever your tooling prefers:

The raw JSON from api.hydracore.io is the source of truth — the Swagger and ReDoc views are rendered from it. The build-time snapshot is committed to the docs repo so reviewers see the contract diff at PR time; an embedded, statically-rendered reference under /docs/api (consuming that snapshot) is on the roadmap.

Authentication

Two paths, intended for different use cases:

X-Api-Key (recommended)

GET /v1/instances
Host: api.hydracore.io
X-Api-Key: hc_live_...

• Tenant-scoped. Each key belongs to one tenant; cross-tenant reads are 404.
• Scope-filtered. A key carries a scope set; endpoints check request.scope against the route's __scope_tag__. A key without instances:write cannot reach POST /v1/instances regardless of its other scopes. Scopes follow <resource>:<verb> — common ones include instances:read / instances:write / instances:delete, mcp-creds:read / mcp-creds:write, entities:*, forms:*, email:*, etc. The full list is on GET /v1/mcp/api-key-context for any live key.
• Rotatable. Mint a new key in Settings → API Keys, switch callers, revoke the old key. Both can coexist briefly.
• MCP-tool audit. MCP call_tool invocations (via the MCP setup path) land in mcp_call_log with the tool name, resolved scope, latency, and status — no raw args, no response body, no error text. Direct HTTP requests to /v1/… from curl / SDKs go through standard FastAPI logging only; if you need a "what did this assistant do?" audit trail, route through MCP.

Mint a key at platform.hydracore.io/settings/api-keys.

Bearer JWT (legacy)

GET /v1/instances
Host: api.hydracore.io
Authorization: Bearer eyJhbGciOi...

• User-scoped, not tenant-scoped. A JWT carries a user_id; the tenant comes from the user's membership. Admins in multiple tenants need to switch via /auth/switch-tenant.
• No scope filter. Every route the user's role allows is visible.
• Short-lived. Access tokens expire in minutes; refresh tokens rotate. Best for browser-driven UI, not for background workers.

Use Bearer JWT when you're driving the dashboard from a real user session. For everything else, mint an API key.

Internal endpoints

The /internal/v1/* surface is reserved for platform ops (smoke pipeline, ops bearer auth, runtime image promotion). API keys cannot reach it regardless of scope. The OpenAPI spec includes these routes for completeness but they will all 401 for any auth that isn't verify_ops_bearer_token.

Conventions

• Timestamps. ISO-8601 UTC with Z suffix; never local time, never offset.
• IDs. UUIDv4 throughout. URL params validate as UUID at the framework layer; malformed IDs are 422, not 404.
• Errors. FastAPI default JSON shape — {"detail": "..."} for most 4xx; validation errors include a structured detail array with the offending field path. A platform-wide migration to RFC 7807 problem-detail responses is on the roadmap but not shipped yet; do not depend on type/title/instance fields.
• Pagination. Inconsistent today — most list endpoints return every row in scope (no limit/cursor), a handful accept ?limit= with no opaque cursor. The OpenAPI spec is the source of truth per route. Cursor pagination is a planned cleanup; consume the live spec rather than assuming a global convention.

Rate limits

Per-API-key rate limits (PR-2b-2c) configurable from the dashboard. Limits apply to the key, not the tenant — independent keys under the same tenant rate-limit independently. Check the live OpenAPI spec + dashboard for the current per-key knobs; standard X-RateLimit-* / Retry-After headers are emitted when a limit is hit.

Need more?

• MCP Setup — drive the API from Claude Desktop, Cursor, or Goose instead of writing client code.
• Quickstart — happy path from signup to a running agent.
• Architecture — the composition model and the platform primitives the API operates on.