Skip to content
Hyperresearch docs

Overview

hyperresearch Cloud API 1.0.0

Section titled “hyperresearch Cloud API 1.0.0”

REST v1 for hosted hyperresearch runs, vault access, verification, and billing. Times are RFC 3339 UTC; ids are prefixed ULIDs.

Authentication. Send an API key as Authorization: Bearer hr_live_…. Each operation lists the scope it needs (x-hr-scope, and in its security requirement). OAuth 2.1 (authorization code + PKCE, oauth2 scheme) issues tokens for the hosted MCP server at https://mcp.hyperresearch.ai/mcp; REST calls use an API key.

Errors. Every 4xx/5xx body is the ErrorEnvelope: error.type, a stable error.code, a human message, the offending param when there is one, and the request_id to quote to support. Branch on code, never on message.

Rate limits. Responses carry RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers) alongside the older X-RateLimit-* headers. A 429 always carries Retry-After (seconds) and error.retry_after.

Versioning. The version is in the path. /v1 is stable: within it, changes are additive only (new operations, new optional request fields, new response fields, new enum values a client must tolerate). A breaking change ships only under a new path version. A deprecated operation is marked deprecated: true here and answers with Deprecation (RFC 9745) and Sunset (RFC 8594) headers and Link: rel="deprecation" at least six months before it is removed, and is listed under Deprecations on the policy page: https://hyperresearch.ai/docs/versioning

hyperresearch API documentation

Information

  • OpenAPI version: 3.1.0

Operations

Section titled “ Operations ”
GET
/v1/runs
POST
/v1/runs
POST
/v1/runs/{id}/clarify
GET
/v1/runs/{id}
PATCH
/v1/runs/{id}
GET
/v1/runs/{id}/result
GET
/v1/runs/{id}/artifacts/{name}
GET
/v1/artifacts/download
POST
/v1/runs/{id}/pause
POST
/v1/runs/{id}/resume
POST
/v1/runs/{id}/abort
POST
/v1/runs/{id}/rerun-from
POST
/v1/runs/{id}/resume-finish
GET
/v1/runs/{id}/events
GET
/v1/runs/{id}/result.pdf
GET
/v1/projects
POST
/v1/projects
GET
/v1/projects/{id}
PATCH
/v1/projects/{id}
GET
/v1/keys
POST
/v1/keys
POST
/v1/keys/{id}/rotate
DELETE
/v1/keys/{id}
PATCH
/v1/keys/{id}
GET
/v1/workspaces/{id}/deletion-writers
POST
/v1/workspaces/{id}/deletion-writers/reconcile
GET
/v1/workspaces
POST
/v1/workspaces
GET
/v1/workspaces/robots-modes
GET
/v1/workspaces/{id}
DELETE
/v1/workspaces/{id}
PATCH
/v1/workspaces/{id}
GET
/v1/workspaces/{id}/members
POST
/v1/workspaces/{id}/members
DELETE
/v1/workspaces/{id}/members/{userId}
PATCH
/v1/workspaces/{id}/members/{userId}
GET
/v1/workspaces/{id}/members/invitations
POST
/v1/workspaces/{id}/members/invitations
DELETE
/v1/workspaces/{id}/members/invitations/{invitationId}
POST
/v1/invitations/accept
GET
/v1/workspaces/{id}/audit
GET
/v1/webhooks
POST
/v1/webhooks
GET
/v1/webhooks/{id}/deliveries
GET
/v1/webhooks/events
POST
/v1/webhooks/{id}/test
DELETE
/v1/webhooks/{id}
GET
/v1/usage
GET
/v1/answers
POST
/v1/answers
POST
/v1/answers/search
GET
/v1/answers/{id}
GET
/v1/meta
GET
/v1/health
GET
/v1/tiers
GET
/v1/sources
POST
/v1/vault/fetch
GET
/v1/vault/status
GET
/v1/vault/notes
POST
/v1/vault/notes
POST
/v1/vault/notes/batch
GET
/v1/vault/notes/{id}
DELETE
/v1/vault/notes/{id}
PATCH
/v1/vault/notes/{id}
GET
/v1/vault/search
GET
/v1/vault/notes/{id}/backlinks
GET
/v1/vault/hubs
GET
/v1/vault/tags
POST
/v1/vault/sources/check
GET
/v1/vault/sources
GET
/v1/vault/claims
POST
/v1/vault/claims
GET
/v1/vault/claims/search
GET
/v1/vault/run-notes
POST
/v1/vault/export
POST
/v1/vault/import
POST
/v1/vault/import-uploads
PUT
/v1/vault/import-uploads/{id}/parts/{part}
POST
/v1/vault/import-uploads/{id}/complete
DELETE
/v1/vault/import-uploads/{id}
GET
/v1/jobs/{id}
GET
/v1/escalations
POST
/v1/escalations/{id}/claim
POST
/v1/escalations/{id}/raw/{filename}
POST
/v1/escalations/{id}/resolve
POST
/v1/escalations/{id}/abandon
POST
/v1/verify/citations
POST
/v1/verify/quotes
POST
/v1/verify/retractions
POST
/v1/verify/independence
POST
/v1/verify/report
GET
/v1/verify/{id}
GET
/v1/verify/{id}/result
POST
/v1/scholar/lookup
POST
/v1/scholar/oa
POST
/v1/scholar/{provider}
GET
/v1/billing/status
PATCH
/v1/billing/spend-cap
POST
/v1/billing/portal
POST
/v1/billing/setup-session
GET
/v1/invoices
GET
/v1/account/email-preferences
PATCH
/v1/account/email-preferences
POST
/v1/email/unsubscribe
GET
/v1/account/export
POST
/v1/account/export
GET
/v1/account/export/download
GET
/v1/account/deletion
POST
/v1/account/delete
POST
/v1/account/delete/cancel
GET
/v1/agent-connections
DELETE
/v1/agent-connections/{id}
GET
/v1/auth/me
POST
/v1/auth/csrf
POST
/v1/auth/workspace
POST
/v1/auth/logout
POST
/v1/auth/billing/setup-intent
POST
/v1/auth/terms

Authentication

Section titled “ Authentication ”

bearerAuth

Section titled “bearerAuth”

An API key: hr_live_… (billed), hr_test_… (fixture mode, free), or hr_chat_… (vault chat only).

Security scheme type: http

sessionCookie

Section titled “sessionCookie”

Console session cookie (HttpOnly, set by POST /v1/auth/clerk/exchange). Mutations also require an allowlisted Origin and the X-CSRF-Token header. The requirement list names the workspace-role scope the session must carry.

Security scheme type: apiKey

Cookie parameter name: hr_session