API reference

GET /#

Redirect the bare root to the marketing site

The apex is the API's custom domain, so a browser landing on the bare root is sent to the marketing site with a permanent redirect, the query string carried across. The route is mounted only when ROOT_REDIRECT_URL is configured; when it is unset (local/dev) nothing is mounted at / and Hono's plain-text not-found answers. Nothing else on the origin is affected.

Auth: none operationId root

Responses

404 Not Found

GET /health#

Bare liveness probe

Unauthenticated, no CORS, and not the /v1 envelope beyond { ok: true }. Infrastructure checks hit this; consumers should prefer GET /v1/ping, which also reports the service name and version.

Auth: none operationId health

Responses

{
  "ok": true
}

GET /v1/ping#

Liveness probe (unauthenticated, I-205)

Deliberately unauthenticated: mounted before the /v1/* bearer guard so a liveness probe needs no key. Carries no tenant data, only the service name, version and current time.

Auth: none operationId ping

Responses

{
  "ok": true,
  "data": {
    "name": "hookchat",
    "version": "0.1.0",
    "time": "2026-09-03T00:00:00Z"
  }
}

GET /v1/conversations#

The unified inbox feed

Window state and the two "can I send" flags are computed server-side so no consumer reimplements Meta's rules. Paginated with an opaque cursor and a limit clamped to 1..100.

Auth: bearerAuth operationId listConversations

Parameters

Responses

{
  "ok": true,
  "data": {
    "conversations": [
      {
        "id": "string",
        "tenant_id": "string",
        "account_handle": "string",
        "platform": "instagram",
        "participant_id": "string",
        "participant_handle": "string",
        "last_inbound_at": "2026-09-03T00:00:00Z",
        "last_outbound_at": "2026-09-03T00:00:00Z",
        "last_message_text": "string",
        "window": {
          "state": "open_24h",
          "expires_at": "2026-09-03T00:00:00Z"
        },
        "unanswered": true,
        "can_reply": true,
        "can_send_as_human_agent": true
      }
    ],
    "next_cursor": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

GET /v1/conversations/{id}#

One conversation's detail and thread history (I-201)

Returns the same server-computed conversation projection as the list feed (window state and the two "can I send" flags) plus the conversation's thread, its messages, newest-first, as a narrow projection carrying only id, direction, text and timing (never the raw Meta payload or any credential). TIER-1 tenant isolation: an id that does not exist OR belongs to another tenant is the SAME 404 conversation_not_found, never a 403 (which would confirm the id exists elsewhere) and never another tenant's data. The path id contains # separators and must be URL-encoded.

Auth: bearerAuth operationId getConversation

Parameters

Responses

{
  "ok": true,
  "data": {
    "conversation": {
      "id": "string",
      "tenant_id": "string",
      "account_handle": "string",
      "platform": "instagram",
      "participant_id": "string",
      "participant_handle": "string",
      "last_inbound_at": "2026-09-03T00:00:00Z",
      "last_outbound_at": "2026-09-03T00:00:00Z",
      "last_message_text": "string",
      "window": {
        "state": "open_24h",
        "expires_at": "2026-09-03T00:00:00Z"
      },
      "unanswered": true,
      "can_reply": true,
      "can_send_as_human_agent": true
    },
    "messages": [
      {
        "id": "string",
        "direction": "string",
        "text": "string",
        "sent_at": "2026-09-03T00:00:00Z",
        "sent_via": "string",
        "actor_id": "string"
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "conversation_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request
• conversation_not_found

GET /v1/accounts#

The tenant's linked channel accounts (I-204)

Each account carries refresh_error, the last token-refresh failure so a silently disconnected account is visible rather than merely absent from the feed. No token or ciphertext is ever exposed.

Auth: bearerAuth operationId listAccounts

Parameters

Responses

{
  "ok": true,
  "data": {
    "accounts": [
      {
        "account_key": "string",
        "platform": "string",
        "external_id": "string",
        "handle": "string",
        "display_name": "string",
        "page_id": "string",
        "status": "active",
        "refresh_error": "string",
        "last_refreshed_at": "2026-09-03T00:00:00Z"
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

GET /v1/audit#

The tenant's audit trail (I-109)

Most-recent-first. By construction every entry carries only who did what, to which resource, and from where, never message content, tokens or secrets. Paginated with an opaque cursor and a clamped limit.

Auth: bearerAuth operationId listAudit

Parameters

Responses

{
  "ok": true,
  "data": {
    "audit": [
      {
        "id": "string",
        "action": "webhook.create",
        "resource": "string",
        "actor": "string",
        "ip": "string",
        "at": "2026-09-03T00:00:00Z"
      }
    ],
    "next_cursor": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

GET /v1/stats#

The dashboard overview counts (I-207)

Tenant-scoped counts for the §6.2 dashboard overview: messages in the last 24h, per-endpoint delivery success/failure/DLQ, and the tenant DLQ total. Every number is a BOUNDED Query, never a Scan. The delivery counts and dlq_total are measured over a recent window (window_hours, default 24) rather than all delivery history, dlq_total is the sum of the per-endpoint dlq counts within that window. Only LIVE endpoints appear (tombstoned endpoints are excluded).

Auth: bearerAuth operationId getStats

Parameters

Responses

{
  "ok": true,
  "data": {
    "messages_24h": 0,
    "dlq_total": 0,
    "window_hours": 0,
    "endpoints": [
      {
        "endpoint_id": "string",
        "delivered": 0,
        "failed": 0,
        "dlq": 0
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

GET /v1/messages#

The tenant-wide message feed (I-203)

Every message across the tenant's conversations, newest-first, on a sparse GSI that indexes messages only. Optionally narrowed by conversation_id (one conversation) and/or direction (inbound/outbound). Paginated with an opaque cursor and a limit clamped to 1..100; a filtered page may be short and still carry a next_cursor. Each message is the same narrow projection as the conversation thread, never the raw payload or a credential.

Auth: bearerAuth operationId listMessages

Parameters

Responses

{
  "ok": true,
  "data": {
    "messages": [
      {
        "id": "string",
        "direction": "string",
        "text": "string",
        "sent_at": "2026-09-03T00:00:00Z",
        "sent_via": "string",
        "actor_id": "string"
      }
    ],
    "next_cursor": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

GET /v1/messages/{id}#

One message by id (I-203)

A single message by its platform id (mid), tenant-scoped. An id that does not exist OR belongs to another tenant is the SAME 404 message_not_found, never a 403 and never another tenant's data.

Auth: bearerAuth operationId getMessage

Parameters

Responses

{
  "ok": true,
  "data": {
    "message": {
      "id": "string",
      "direction": "string",
      "text": "string",
      "sent_at": "2026-09-03T00:00:00Z",
      "sent_via": "string",
      "actor_id": "string"
    }
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "message_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request
• message_not_found

POST /v1/messages/reply#

Reply inside the 24-hour window

Sends a reply on a conversation whose 24-hour window is open. Out of that window this route refuses with window_closed (409); the human-agent route is the only remaining path. There is no ?tenant on this route the conversation id scopes the send. Body is snake_case; legacy camelCase (conversationId) is still tolerated but undocumented.

Auth: bearerAuth operationId replyInWindow

Request body

application/json, required

{
  "conversation_id": "string",
  "text": "string",
  "attachments": [
    {
      "type": "string",
      "url": "https://example.com"
    }
  ],
  "reply_to": "string"
}

Responses

{
  "ok": true,
  "data": {
    "platform_message_id": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "conversation_not_found",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "window_closed",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "send_failed",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• tenant_required
• invalid_request
• conversation_not_found
• window_closed
• rate_limited
• send_failed

POST /v1/messages/human-agent#

Send a human-typed message in the 24h–7d window

The only route out of the 24-hour window (24h–7d), human-sent. actor_id is required, the human who sent it must be named; omitting it is a 409 missing_actor policy refusal, not a 400. Past 7 days the window is human_agent_unavailable (409). Body is snake_case; legacy camelCase (conversationId/actorId) is tolerated but undocumented.

Auth: bearerAuth operationId sendAsHumanAgent

Request body

application/json, required

{
  "conversation_id": "string",
  "text": "string",
  "actor_id": "string",
  "attachments": [
    {
      "type": "string",
      "url": "https://example.com"
    }
  ],
  "reply_to": "string"
}

Responses

{
  "ok": true,
  "data": {
    "platform_message_id": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "conversation_not_found",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "missing_actor",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "send_failed",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• tenant_required
• invalid_request
• conversation_not_found
• human_agent_unavailable
• missing_actor
• rate_limited
• send_failed

GET /v1/webhooks#

List webhook endpoints (never returns a secret)

Auth: bearerAuth operationId listWebhooks

Parameters

Responses

{
  "ok": true,
  "data": {
    "endpoints": [
      {
        "id": "string",
        "url": "https://example.com",
        "events": [
          "string"
        ],
        "status": "active",
        "signing_secret_prefix": "string",
        "secondary_active": true,
        "secondary_expires_at": "2026-09-03T00:00:00Z",
        "created_at": "2026-09-03T00:00:00Z",
        "updated_at": "2026-09-03T00:00:00Z"
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

POST /v1/webhooks#

Register a webhook endpoint (secret shown once)

Creates an endpoint and mints its signing secret. The plaintext signing_secret (whs_…) is returned exactly once here; no read path ever returns it. A rejected URL (SSRF gate) is a 400 with the reason in error.detail.

Auth: bearerAuth operationId createWebhook

Parameters

Request body

application/json, required

{
  "url": "https://example.com",
  "events": [
    "string"
  ]
}

Responses

{
  "ok": true,
  "data": {
    "endpoint": {
      "id": "string",
      "url": "https://example.com",
      "events": [
        "string"
      ],
      "status": "active",
      "signing_secret_prefix": "string",
      "secondary_active": true,
      "secondary_expires_at": "2026-09-03T00:00:00Z",
      "created_at": "2026-09-03T00:00:00Z",
      "updated_at": "2026-09-03T00:00:00Z"
    },
    "signing_secret": "whs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

GET /v1/webhooks/{id}#

Fetch one endpoint (never returns a secret)

Auth: bearerAuth operationId getWebhook

Parameters

Responses

{
  "ok": true,
  "data": {
    "endpoint": {
      "id": "string",
      "url": "https://example.com",
      "events": [
        "string"
      ],
      "status": "active",
      "signing_secret_prefix": "string",
      "secondary_active": true,
      "secondary_expires_at": "2026-09-03T00:00:00Z",
      "created_at": "2026-09-03T00:00:00Z",
      "updated_at": "2026-09-03T00:00:00Z"
    }
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "endpoint_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request
• endpoint_not_found

PATCH /v1/webhooks/{id}#

Update url/events and/or pause/resume

Any subset of url, events, status. status accepts only active or paused (delete is its own route). A new url is re-validated by the SSRF gate (400 with the reason in error.detail on rejection). Returns the updated endpoint; never returns a secret.

Auth: bearerAuth operationId updateWebhook

Parameters

Request body

application/json, required

{
  "url": "https://example.com",
  "events": [
    "string"
  ],
  "status": "active"
}

Responses

{
  "ok": true,
  "data": {
    "endpoint": {
      "id": "string",
      "url": "https://example.com",
      "events": [
        "string"
      ],
      "status": "active",
      "signing_secret_prefix": "string",
      "secondary_active": true,
      "secondary_expires_at": "2026-09-03T00:00:00Z",
      "created_at": "2026-09-03T00:00:00Z",
      "updated_at": "2026-09-03T00:00:00Z"
    }
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "endpoint_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request
• endpoint_not_found

DELETE /v1/webhooks/{id}#

Tombstone an endpoint (signing material erased)

Tombstone: status becomes deleted, both signing secrets are erased, the id and history are retained.

Auth: bearerAuth operationId deleteWebhook

Parameters

Responses

{
  "ok": true,
  "data": {
    "deleted": true
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "endpoint_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request
• endpoint_not_found

POST /v1/webhooks/{id}/rotate#

Rotate the signing secret (new secret shown once)

Mints a new primary signing secret and demotes the current one to a secondary that still verifies for a 24-hour overlap. The new plaintext signing_secret is returned exactly once.

Auth: bearerAuth operationId rotateWebhookSecret

Parameters

Responses

{
  "ok": true,
  "data": {
    "endpoint": {
      "id": "string",
      "url": "https://example.com",
      "events": [
        "string"
      ],
      "status": "active",
      "signing_secret_prefix": "string",
      "secondary_active": true,
      "secondary_expires_at": "2026-09-03T00:00:00Z",
      "created_at": "2026-09-03T00:00:00Z",
      "updated_at": "2026-09-03T00:00:00Z"
    },
    "signing_secret": "whs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "endpoint_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request
• endpoint_not_found

GET /v1/webhooks/{id}/deliveries#

List an endpoint's deliveries, newest first (I-306)

One page of the endpoint's delivery ledger, newest first, over the tenant-partitioned deliveries index, so a page can only ever hold this tenant's deliveries. Each row is the consumer-safe summary view: no body, no url, never a secret. Timestamps on delivery rows are epoch milliseconds (an internal replay surface, not a customer resource shape). A read, so it is not audited. An endpoint id that does not exist under this tenant yields an empty page, not a 404. Paginated with the opaque cursor and a limit clamped to 1..100.

Auth: bearerAuth operationId listWebhookDeliveries

Parameters

Responses

{
  "ok": true,
  "data": {
    "deliveries": [
      {
        "delivery_id": "string",
        "event_id": "string",
        "event_type": "message.received",
        "status": "pending",
        "attempt_number": 0,
        "next_retry_at": 0,
        "last_response_status": 0,
        "created_at": 0,
        "updated_at": 0
      }
    ],
    "next_cursor": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

GET /v1/webhooks/{id}/deliveries/summary#

The endpoint's failing deliveries in a recent window

The endpoint's currently failing deliveries, aggregated server-side for the console's failed-in-the-last-24h view. Defaults to the last 24 hours and the statuses dlq, failed, blocked and retrying (a delivery that is backing off is failing right now, so it belongs here even though it is never a replay target). The store walks the window newest first and paginates internally, so a recent failure is never hidden behind older rows; there is no external cursor. truncated is true when the bounded examined-row cap was hit and only the most recent failures are returned. A read, so it is not audited.

Auth: bearerAuth operationId summarizeWebhookDeliveries

Parameters

Responses

{
  "ok": true,
  "data": {
    "deliveries": [
      {
        "delivery_id": "string",
        "event_id": "string",
        "event_type": "message.received",
        "status": "pending",
        "attempt_number": 0,
        "next_retry_at": 0,
        "last_response_status": 0,
        "created_at": 0,
        "updated_at": 0
      }
    ],
    "truncated": true
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

POST /v1/webhooks/{id}/deliveries/replay#

Bulk replay the deliveries in a time and status window (I-307)

A bounded, idempotent batch re-drive of the endpoint's deliveries whose creation time falls in [from, to] and whose status is in status. from, to, status and force may come from the query string or the JSON body; the query wins. from is required; to defaults to now and must not precede from; status defaults to the retryable set dlq,failed. In-flight states (pending, attempting, retrying) are never selectable, which is what keeps a re-run idempotent. Including delivered is refused with a 409 replay_conflict unless force is true, because a forced re-send makes the consumer see a duplicate event id (which is why dedupe-on-id exists). Each match is reset to a fresh attempt budget and re-enqueued; a delivery mid-attempt is counted in skipped, never double-enqueued. limit (query only) caps the rows examined per call and next_cursor resumes the next page. An endpoint that does not exist under this tenant is a 404 before any query. Audited as webhook.bulk_replay with the window, statuses and counts, never a secret, url or body.

Auth: bearerAuth operationId bulkReplayWebhookDeliveries

Parameters

Request body

application/json, optional

{
  "from": "string",
  "to": "string",
  "status": "string",
  "force": true
}

Responses

{
  "ok": true,
  "data": {
    "matched": 0,
    "enqueued": 0,
    "skipped": 0,
    "next_cursor": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "endpoint_not_found",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "replay_conflict",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request
• endpoint_not_found
• replay_conflict

POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay#

Replay one delivery with a fresh attempt budget (I-306)

Resets the delivery to attempt 0, status pending, due now, and re-enqueues it through the real signing and delivery path. A dlq, failed or blocked delivery replays freely. A delivered one is refused with a 409 replay_conflict unless ?force=true, since the consumer will then see a duplicate event id (which is why dedupe-on-id exists). A delivery that is mid-attempt is also a 409 replay_conflict; try again shortly. Tenant-scoped: an endpoint or delivery that does not exist or belongs to another tenant is a 404, never a 403. Audited as webhook.replay.

Auth: bearerAuth operationId replayWebhookDelivery

Parameters

Responses

{
  "ok": true,
  "data": {
    "delivery_id": "string",
    "status": "pending"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "endpoint_not_found",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "replay_conflict",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request
• endpoint_not_found
• delivery_not_found
• replay_conflict

POST /v1/webhooks/{id}/test#

Send a test event through the real delivery path

Mints a conforming test.event and enqueues it to this one endpoint through the real signing and delivery path, so a developer can prove their receiver verifies signatures. Returns the new delivery id; the delivery itself runs asynchronously and can be followed on the deliveries list. Audited as webhook.test.

Auth: bearerAuth operationId testWebhook

Parameters

Responses

{
  "ok": true,
  "data": {
    "delivery_id": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "endpoint_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request
• endpoint_not_found

GET /v1/keys#

List API keys (prefix only, never a secret)

The tenant's API keys. Each row carries the prefix only, the plaintext secret is never stored, so it can never appear here.

Auth: bearerAuth operationId listKeys

Parameters

Responses

{
  "ok": true,
  "data": {
    "keys": [
      {
        "id": "string",
        "prefix": "string",
        "scope": "live",
        "label": "string",
        "status": "active",
        "created_at": "2026-09-03T00:00:00Z"
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

POST /v1/keys#

Mint an API key (secret shown once)

Mints a single-tenant (bound) API key for the caller's tenant and returns its plaintext secret (hookchat_live_… / hookchat_test_…) EXACTLY ONCE, no read path ever returns it again (only its sha256 hash is stored, so a lost key is unrecoverable; rotate by creating a new key and revoking this one). The new key's scope defaults to the caller's own scope; a test-scope caller may not create a live key (a 403 forbidden). This is the same hashed-key core the key:* CLI drives. Every create writes an audit row.

Auth: bearerAuth operationId createKey

Parameters

Request body

application/json, optional

{
  "scope": "live",
  "label": "string"
}

Responses

{
  "ok": true,
  "data": {
    "id": "string",
    "prefix": "string",
    "secret": "hookchat_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "scope": "live",
    "label": "string",
    "created_at": "2026-09-03T00:00:00Z"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

DELETE /v1/keys/{id}#

Revoke an API key (idempotent)

Revokes the key. Idempotent, revoking an already-revoked key still 200s. The revoke is scoped to the caller's tenant, so a cross-tenant key id finds no key and is a 404 key_not_found, never a 403 that would confirm the id exists under another tenant. A real revoke writes an audit row.

Auth: bearerAuth operationId revokeKey

Parameters

Responses

{
  "ok": true,
  "data": {
    "revoked": true
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "key_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• key_not_found

GET /console/me#

The logged-in console operator's identity (I-604)

Returns the authenticated console operator's {actor_id, email, tenant, tenants}. Authed by the console SESSION COOKIE (I-602), NOT a bearer key an absent/invalid/expired session is a 401 unauthorized. actor_id is console:<userId>, the same stable operator identity every audited console mutation attributes to; the dashboard attaches it as a human-agent send's actor_id. tenant is the bound tenant for a single-membership operator (else null); tenants is the full membership set. A pure read of the session and membership, so no CSRF token is required and nothing is audited.

Auth: cookieAuth operationId consoleMe

Responses

{
  "ok": true,
  "data": {
    "user_id": "string",
    "actor_id": "console:01H…",
    "email": "user@example.com",
    "tenant": "string",
    "tenants": [
      "string"
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized

POST /console/session/ws-ticket#

Mint a WebSocket connect ticket for a console session (I-309)

The console-session counterpart of POST /v1/realtime/ticket. Authed by the session cookie plus the CSRF header (a POST is a mutation under the console rules; a missing or wrong header is a 403 csrf_failed). The tenant is membership-derived, never client-trusted: a single-membership user's tenant is implicit, a multi-membership user must name an allowed ?tenant (omitting it is a 400 tenant_required, naming one they do not belong to is a 403 forbidden). The ticket carries only the tenant and actor, never the session.

Auth: cookieAuth + csrfHeader operationId consoleRealtimeTicket

Parameters

Responses

{
  "ok": true,
  "data": {
    "ticket": "string",
    "expires_at": 0,
    "expires_in_ms": 0
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "csrf_failed",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• csrf_failed
• tenant_required
• invalid_request

POST /console/auth/request#

Request a magic sign-in link (I-602)

Mints a single-use, hashed, time-limited sign-in token for email and emails a link to GET /console/auth/verify. Unauthenticated. Always 200 on a well-formed request whether or not the address maps to an existing user, so the route cannot be used to enumerate accounts. Rate limited per email (5) and per attested source IP (20) over a 15 minute window; exceeding either cap is a 429 rate_limited with a Retry-After header. redirect is validated to a same-site relative path; anything else falls back to /.

Auth: none operationId consoleAuthRequest

Request body

application/json, required

{
  "email": "user@example.com",
  "redirect": "/inbox"
}

Responses

{
  "ok": true,
  "data": {
    "sent": true
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• invalid_request
• rate_limited

GET /console/auth/verify#

Consume an emailed sign-in link and start a session

The emailed link. Consumes the single-use token, upserts the console user, claims any pending team invites for the address (best effort, after the address is proven), sets the console_session (HttpOnly) and console_csrf (readable, for the double-submit header) cookies, and 302-redirects to the validated post-login path on the console origin. The token is the credential, so no other security applies. Every consume failure (expired, already used, unknown) is the same 401 invalid_token, never an oracle for which tokens exist.

Auth: none operationId consoleAuthVerifyLink

Parameters

Responses

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_token",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• invalid_token
• invalid_request

POST /console/auth/verify#

Consume a sign-in token and start a session (JSON)

The programmatic form of the emailed link, for the console SPA. The token is read from ?token first, then from the JSON body. On success the same two cookies are set and the body returns the validated redirect path and the csrf token to echo in the x-csrf-token header on later mutations. Failures are identical to the GET form.

Auth: none operationId consoleAuthVerify

Parameters

Request body

application/json, optional

{
  "token": "string"
}

Responses

{
  "ok": true,
  "data": {
    "redirect": "string",
    "csrf": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_token",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• invalid_token
• invalid_request

POST /console/auth/logout#

End the console session

Clears the console_session and console_csrf cookies. A CSRF-protected mutation: the session cookie and a matching x-csrf-token header are both required.

Auth: cookieAuth + csrfHeader operationId consoleAuthLogout

Responses

{
  "ok": true,
  "data": {
    "loggedOut": true
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "csrf_failed",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• csrf_failed

GET /console/tenants#

The caller's workspaces

The caller's memberships, one row per workspace with their role (defaulting to member).

Auth: cookieAuth operationId consoleListTenants

Responses

{
  "ok": true,
  "data": {
    "tenants": [
      {
        "slug": "string",
        "role": "owner"
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized

POST /console/tenants#

Create a workspace and become its owner

Self-serve workspace creation, the escape from the no-tenant dead end. The slug is reserved and the caller's owner membership written in one atomic transaction; an already-claimed slug is a 409 tenant_slug_taken. A slug is 3 to 40 characters of lowercase letters, digits and hyphens, starting with a letter and ending alphanumeric, and may not be a reserved word (console, admin, api, oauth, webhooks, health, v1, internal, system). This route can only ever create a new, unclaimed slug; joining an existing workspace is the invite flow.

Auth: cookieAuth + csrfHeader operationId consoleCreateTenant

Request body

application/json, required

{
  "slug": "string",
  "name": "string"
}

Responses

{
  "ok": true,
  "data": {
    "slug": "string",
    "role": "owner"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "csrf_failed",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "tenant_slug_taken",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• csrf_failed
• invalid_request
• tenant_slug_taken

GET /console/tenants/{slug}/members#

A workspace's members and pending invites

For the Team UI. Only an owner or admin of this workspace may read it; a non-member, a plain member, or a slug the caller cannot manage is the same 403 forbidden and never reveals whether the workspace exists.

Auth: cookieAuth operationId consoleListTeam

Parameters

Responses

{
  "ok": true,
  "data": {
    "members": [
      {
        "user_id": "string",
        "email": "user@example.com",
        "role": "owner",
        "status": "active"
      }
    ],
    "invites": [
      {
        "email": "user@example.com",
        "role": "admin",
        "status": "pending"
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden

DELETE /console/tenants/{slug}/members/{userId}#

Remove a member from a workspace

Owner or admin only, CSRF-protected. An owner membership cannot be removed here (it would orphan the workspace) and is a 409 owner_immutable; a user who is not a member is a 404 member_not_found.

Auth: cookieAuth + csrfHeader operationId consoleRemoveMember

Parameters

Responses

{
  "ok": true,
  "data": {
    "removed": true
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "member_not_found",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "owner_immutable",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• csrf_failed
• member_not_found
• owner_immutable

POST /console/tenants/{slug}/invites#

Invite a teammate by email

Owner or admin only, CSRF-protected. Records a pending invite that grants nothing until the invitee signs in and it is claimed at verify time, so an invite to an address that never authenticates never exposes any data. The membership gate runs before the body is read, so a non-member with a malformed body still sees the 403. role defaults to member; owner cannot be granted by invite.

Auth: cookieAuth + csrfHeader operationId consoleInviteMember

Parameters

Request body

application/json, required

{
  "email": "user@example.com",
  "role": "member"
}

Responses

{
  "ok": true,
  "data": {
    "email": "user@example.com",
    "role": "admin",
    "tenant": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• csrf_failed
• invalid_request

DELETE /console/tenants/{slug}/invites/{email}#

Revoke a pending invite

Owner or admin only, CSRF-protected. The email path segment is URL-decoded once by the router; do not double-encode it. No such pending invite is a 404 invite_not_found.

Auth: cookieAuth + csrfHeader operationId consoleRevokeInvite

Parameters

Responses

{
  "ok": true,
  "data": {
    "revoked": true
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "invite_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• csrf_failed
• invite_not_found

POST /v1/realtime/ticket#

Mint a single-use WebSocket connect ticket (I-309)

A browser cannot set an Authorization header on a WebSocket upgrade, so a short-lived, single-use, tenant-bound ticket is minted here over an authenticated call and passed in the WebSocket URL's query string; the realtime endpoint verifies and consumes it at connect. The tenant is derived server-side from the key's binding exactly like every /v1 read. The ticket carries only the tenant and actor, never the credential.

Auth: bearerAuth operationId createRealtimeTicket

Parameters

Responses

{
  "ok": true,
  "data": {
    "ticket": "string",
    "expires_at": 0,
    "expires_in_ms": 0
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required
• invalid_request

GET /oauth/meta/start#

Begin hosted Meta OAuth linking (console-session authed; not enveloped)

Starts the hosted Meta OAuth flow (I-501). Authenticated by a CONSOLE SESSION cookie, not a bearer key, the linking tenant is derived server-side from the caller's membership (a multi-membership user names ?tenant). Signs a CSRF-hardened state (tenant binding + nonce + issued-at) and 302-redirects to Meta's consent dialog. Not part of the /v1 consumer surface. 401 when no valid console session is present.

Auth: cookieAuth operationId metaOAuthStart

Parameters

Responses

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized

GET /oauth/meta/callback#

Meta OAuth redirect callback (state-verified; not enveloped)

Meta redirects the browser here after consent (I-501/I-502). VERIFIES the signed state (timing-safe HMAC, <=600s expiry, tenant binding) BEFORE anything else, a tampered/expired/missing state is a 400 oauth_state_invalid and the token exchange is never attempted. On a valid state it exchanges code for a long-lived token, DISCOVERS the granted assets (paginated /me/accounts + instagram_business_account), stashes them in a short-TTL tenant-bound pending item (page tokens encrypted context-less), and 302-redirects back to the console with status=discover and a SIGNED handle (I-502), it links NOTHING automatically. The wizard then reads GET /oauth/meta/assets and links the chosen assets via POST /oauth/meta/select. No token is ever in the URL. Not part of the /v1 consumer surface.

Auth: none operationId metaOAuthCallback

Parameters

Responses

{
  "ok": false,
  "error": {
    "code": "oauth_state_invalid",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• oauth_state_invalid

GET /oauth/meta/assets#

List the discovered Meta assets for a pending selection (I-502)

The console wizard's read of the assets discovered at the callback, for the operator to choose from. Authenticated by a CONSOLE SESSION whose membership must include the handle's tenant (else 403 forbidden) AND a valid signed handle (else 400 oauth_state_invalid). Returns asset NAMES/ids/usernames only, NEVER a token. 404 pending_link_not_found when the pending session has expired or been consumed.

Auth: cookieAuth operationId metaOAuthAssets

Parameters

Responses

{
  "ok": true,
  "data": {
    "assets": [
      {
        "page_id": "string",
        "page_name": "string",
        "instagram": {
          "id": "string",
          "username": "string"
        }
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "oauth_state_invalid",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "pending_link_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• forbidden
• oauth_state_invalid
• pending_link_not_found

POST /oauth/meta/select#

Link the operator-selected Meta assets (I-502)

Links ONLY the chosen pages (each a messenger account; its instagram_business_account, when present, an instagram account) via the idempotent linkAccount + subscribeWebhooks, re-selecting the same asset overwrites, never duplicates, then consumes the pending item (single-use). Authenticated by a CONSOLE SESSION whose membership includes the handle's tenant AND the signed handle (which doubles as the CSRF defence, so no separate double-submit token is required). Returns the linked accounts NEVER a token.

Auth: cookieAuth operationId metaOAuthSelect

Request body

application/json, required

{
  "handle": "string",
  "page_ids": [
    "string"
  ]
}

Responses

{
  "ok": true,
  "data": {
    "count": 0,
    "linked": [
      {
        "account_key": "string",
        "platform": "messenger",
        "handle": "string"
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "pending_link_not_found",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• forbidden
• invalid_request
• oauth_state_invalid
• pending_link_not_found

GET /oauth/instagram/start#

Begin hosted Instagram Login onboarding (console-session authed; not enveloped)

Starts the "Instagram API with Instagram Login" flow, a separate Meta product from the Facebook Login flow at /oauth/meta/start, with its own app id and consent host. Authenticated by a console session cookie, never a bearer; the linking tenant is derived server-side from membership (a multi-membership user names ?tenant). Seals the tenant into a signed state and 302-redirects to the Instagram consent dialog with force_reauth=true. Mounted only when an Instagram app id, a state secret and a session key are all configured.

Auth: cookieAuth operationId instagramOAuthStart

Parameters

Responses

{
  "ok": false,
  "error": {
    "code": "tenant_required",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "string",
    "detail": "string"
  }
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• unauthorized
• forbidden
• tenant_required

GET /oauth/instagram/callback#

Instagram Login redirect callback (state-verified; not enveloped)

Instagram redirects the browser here after consent. An error parameter (the user denied) is a 302 back to the console with status=denied and no exchange. Otherwise the signed state is verified before anything else; a missing, tampered or expired state is a 400 oauth_state_invalid and the exchange is never attempted. A valid state without a code is a 302 with status=error. On success the code is exchanged for a long-lived Instagram user token below the handler (encrypted, never returned), the one account is linked and subscribed, and the browser is sent back with status=linked; an exchange or link failure is status=error. No token ever appears in a URL or response.

Auth: none operationId instagramOAuthCallback

Parameters

Responses

{
  "ok": false,
  "error": {
    "code": "oauth_state_invalid",
    "message": "string",
    "detail": "string"
  }
}

Error codes

• oauth_state_invalid

GET /webhooks/meta#

Meta subscription verification handshake (not enveloped)

Meta calls this when the callback URL is saved and on re-verification. Echoes hub.challenge when hub.verify_token matches; otherwise 403. Plain text, not the /v1 envelope. Not part of the consumer surface.

Auth: none operationId metaVerify

Parameters

Responses

string

forbidden

POST /webhooks/meta#

Meta message ingest (signature-authenticated, not enveloped)

Receives Meta's webhook payloads. Authenticated by X-Hub-Signature-256 over the exact bytes, not a bearer token. Always answers 200 on a signed payload (Meta retries non-2xx), 401 on a bad signature. Plain text, not the /v1 envelope. Not part of the consumer surface.

Auth: none operationId metaIngest

Parameters

Request body

application/json, required

{}

Responses

ok

unauthorized

POST /deauthorize#

Meta deauthorize callback (signed_request authenticated; not enveloped)

Meta posts here when a user removes the app. Authenticated by the HMAC in the form field signed_request, verified against every configured app secret (Facebook and Instagram), never a bearer. Enqueues erasure of the user's linked accounts and acknowledges immediately with a plain-text ok; Meta ignores the body. A missing or badly signed signed_request is a plain-text 400 so a misconfiguration is visible rather than silently accepted. No CORS. Not part of the consumer surface.

Auth: none operationId metaDeauthorize

Request body

application/x-www-form-urlencoded, required

{
  "signed_request": "string"
}

Responses

ok

invalid signed_request

POST /data-deletion#

Meta data-deletion request callback (signed_request authenticated; not enveloped)

Meta posts here when a user requests deletion of their data. Authenticated by the signed_request HMAC exactly like /deauthorize. Records a pending deletion request keyed by a fresh confirmation code, enqueues the erasure, and returns synchronously the exact { url, confirmation_code } shape Meta requires, where url is the public status page below. The erase job flips the request to complete once the cascade finishes. No CORS. Not part of the consumer surface.

Auth: none operationId metaDataDeletion

Request body

application/x-www-form-urlencoded, required

{
  "signed_request": "string"
}

Responses

{
  "url": "https://example.com",
  "confirmation_code": "string"
}

{
  "error": "invalid signed_request"
}

GET /data-deletion/status#

Data-deletion request status (public; not enveloped)

The status page Meta's url points at. Public, no credential. Returns only the code, status and request time, never the Meta user id or any account data. complete attests that the authoriser's accounts and their durable data (accounts, tokens, conversations, messages, delivered event copies and send attempts) are erased; the shared raw ingest buffer expires on its own bounded TTL. An unknown or missing code is a 404.

Auth: none operationId metaDataDeletionStatus

Parameters

Responses

{
  "code": "string",
  "status": "pending",
  "requested_at": 0
}

{
  "error": "not_found"
}