Skip to content
Hooks Docs

REST API

The API uses predictable resource URLs, JSON bodies, and bearer authentication. All requests must use HTTPS.

  • Base URL: https://api.hooks.events/v1
  • Authentication: Authorization: Bearer hks_...
  • Scopes: endpoints:read, endpoints:write, deliveries:read, deliveries:retry, history:purge, metrics:read, alerts:read, alerts:write.
  • Session-authenticated requests can select a workspace with X-Workspace-Id: <workspace-id>. Reads fall back to the caller’s own workspace when the id no longer belongs to them (stale localStorage); mutating requests return 403 AUTHORIZATION_DENIED instead of silently writing elsewhere.
  • Mutating requests with a body must send Content-Type: application/json.

Operations

Section titled “Operations”

Every operation below is generated from the OpenAPI 3.1 document at https://api.hooks.events/openapi.json. Browse it under OpenAPI operations or download the raw document and generate a client.

Authentication and rate limits

Section titled “Authentication and rate limits”
  • API keys carry scopes. A key without the route’s scope gets 403 AUTHORIZATION_DENIED.
  • /v1/* allows 600 requests per minute per credential. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit you get 429 RATE_LIMIT_EXCEEDED with Retry-After.
  • Inbound /in/{publicId} requests are limited per endpoint and per workspace. A Free workspace that exhausts its lifetime grant gets 429 with x-quota-limit and an upgrade_url; /t/* and /inspect/* never consume quota.

Machine-readable contract

Section titled “Machine-readable contract”

GET https://api.hooks.events/openapi.json returns the OpenAPI 3.1 document that generates the table above. The sandbox callback endpoints under /callbacks/tasks/* are token-authenticated and intentionally excluded: they are called by run sandboxes, not by API clients.

Environments and scoped values

Section titled “Environments and scoped values”

Every workspace starts with one default environment, production. Endpoints and tasks accept environmentId to bind to another environment; null or omitted means the default. Environment-scoped secrets and variables override project-level rows of the same name.

  • A test event (POST /v1/endpoints/{id}/test-events), preview, or task run may pass a one-off environmentId; it overrides the endpoint/task binding for that request.
  • Deliveries and task runs expose environmentId; task-run views also include environmentName.
  • GET /v1/environments/{id}/resolved returns { secrets: [{ name, source, lastUsedAt }], variables: [{ name, value, source }] }, where source is environment or default. Secret values and ciphertext are never returned.
  • Variables are plaintext by design. A credential-looking variable name gets a warning on create; store credentials as secrets instead.

Example

Section titled “Example”
Terminal window
curl "https://api.hooks.events/v1/endpoints" \
  -H "Authorization: Bearer $HOOKS_API_KEY"

Create an API key in Settings → API keys. Keys are scoped and can be revoked at any time.