Hyperoru v1 API

Contract-first · OpenAPI 3.1

The production API base is https://api.hyperoru.com/v1. Every public operation is versioned under /v1; the generated reference and typed client are built from the same public contract. Operator-only control-plane routes are intentionally excluded.

Authentication schemes

Customer browser session

The API reads the opaque hyperoru_session cookie. Mutations also require X-CSRF-Token and a trusted Origin. Customer sessions must not be accepted by operator endpoints.

Workspace token

Automation uses a scoped bearer token with the vat_ prefix:

Authorization: Bearer vat_<opaque-token>

Tokens expire, are hashed at rest, and are authorized only for their workspace and scopes.

Request IDs

Every response includes or returns a request ID for support and log correlation. Clients should surface it with typed errors and include it when reporting a failure. Never include OAuth codes, state values, cookies, tokens, or secret evidence in logs.

Idempotency

Long-running creations—audits, exports, and remediations—require an Idempotency-Key header. Repeating the same request returns the existing operation. Reusing the key with different input returns a typed conflict.

Idempotency-Key: unique-123

Long-running responses

Creation returns 202 Accepted with the resource identifier, current state, and status URL. Do not hold an HTTP request open for audit completion. Use the authenticated SSE feed or poll the status endpoint with bounded backoff.

Pagination

Collection endpoints use opaque cursor pagination. Pass the returned next_cursor unchanged; never derive or inspect its internal form.

{
  "items": [],
  "next_cursor": "opaque-or-null"
}

Typed errors

Errors include the HTTP status, stable machine code, human detail, and request ID. UI behavior branches on the stable code—not prose.

{
  "status": 409,
  "code": "source_audit_already_active",
  "detail": "This source already has an active or queued audit.",
  "request_id": "req_…",
  "existing_resource_id": "audit_…"
}

Different repositories, validated ZIP uploads, and MCP artifacts may be queued independently. A second request for the same source returns the existing audit so clients cannot accidentally create duplicate work.

SSE reconnection

Clients persist the last event ID and send it on reconnect. Event payloads are JSON and include audit ID, monotonic sequence, timestamp, type, and a typed body. Duplicate sequences are ignored client-side.