API Reference

CatchHook provides a REST API for programmatic access to endpoints, webhook requests, and tunnel connections.

Base URL: https://catchhook.app/api/v1

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer <your-api-token>

Create API tokens in Account Settings. Tokens have scopes that control what they can access:

Endpoints

Verify authentication

GET /api/v1/auth/verify

Returns the current user and account information. Useful for verifying your token is valid.

Response:

{
  "user": { "id": 1, "email": "you@example.com" },
  "account": { "id": 1, "name": "Acme Corp" }
}

List endpoints

GET /api/v1/endpoints

Returns all endpoints accessible to the authenticated user.

Create an endpoint

POST /api/v1/endpoints

Body:

{
  "endpoint": {
    "name": "My Endpoint"
  }
}

Get an endpoint

GET /api/v1/endpoints/:id

Returns details for a single endpoint.

List requests for an endpoint

GET /api/v1/endpoints/:endpoint_id/requests

Returns webhook requests received by the specified endpoint.

Get a single request

GET /api/v1/endpoints/:endpoint_id/requests/:id

Returns full details for a single webhook request, including the complete body.

Tunnel

Connect (authenticated)

POST /api/v1/tunnel/connect

Scope required: tunnel

Body:

{
  "endpoint_id": "ep_abc123"
}

Exchanges your API token for a one-time WebSocket ticket (valid for 30 seconds).

Response:

{
  "ticket": "a1b2c3...",
  "expires_in": 30
}

Connect (anonymous / temporary endpoint)

POST /api/v1/tunnel/connect_anonymous

No authentication required. Uses the endpoint's tunnel_key instead.

Body:

{
  "tunnel_key": "tk_xyz789"
}

Response:

{
  "ticket": "a1b2c3...",
  "expires_in": 30,
  "endpoint_id": "ep_abc123"
}

Report delivery

POST /api/v1/tunnel/delivery_reports

Scope required: tunnel

Reports the result of a local tunnel delivery back to CatchHook. Used by the CLI to power tunnel health metrics and alerts.

Body:

{
  "endpoint_id": "ep_abc123",
  "webhook_request_id": "wr_def456",
  "target_url": "http://localhost:3000/webhooks",
  "status_code": 200,
  "response_message": "OK",
  "response_time_ms": 42
}

Rate limits

API endpoints are rate-limited to prevent abuse:

When rate-limited, the API returns 429 Too Many Requests with a retry_after field.

Error responses

All errors follow a consistent format:

{
  "error": "not_found"
}

Common status codes: