# Public API Reference

This customer-facing reference covers the public route families that external teams can call with documented credentials: project API keys, webhook ingest secrets, public form URLs, and signed file URLs. It deliberately leaves browser-only dashboard workflows in the product guides instead of presenting them as integration endpoints.

## Reference policy

Use this page when you need to know whether a route is public, which credential it expects, and whether the TypeScript SDK or CLI wraps it today. Use [raw HTTP examples](/docs/raw-http-examples.md) when a route is public but not wrapped by a first-party client yet.

> [!NOTE]
> If a workflow is documented as dashboard-only, use the dashboard. Do not build integrations against browser implementation details or undocumented routes.

## Available through

**Available through**

This reference is limited to customer-facing routes. Browser-only dashboard flows are documented as product workflows, not as API endpoints.

| Surface | Status | Notes |
| --- | --- | --- |
| [Public API](/docs/authentication.md) | Preferred | Use project API keys for webhook management, delivery operations, and usage; admin keys are required for alerts, audit logs, and project settings. |
| [Raw HTTP](/docs/quickstart.md#api-and-sdk-path) | Available | Use cURL or your own HTTP client for routes not yet wrapped by first-party clients. |
| [TypeScript SDK](/docs/sdks.md) | Available | Covers core resources and helpers. Check SDK coverage before assuming a route is wrapped. |
| [CLI](/docs/cli.md) | Available | Best for terminal automation, delivery operations, schedules, DLQ, and public ingest sends. |

## Public route families

### Project and API keys

Project-scoped metadata, API-key lifecycle, usage context, and Business+ audit log reads.

| Method | Route | Auth | Use | Client coverage |
| --- | --- | --- | --- | --- |
| GET | `/v1/project` | admin project key | Read the authenticated project and quota detail. | SDK projects.getCurrent(); CLI projects get |
| PATCH | `/v1/project` | admin project key | Update project metadata and supported project settings. | SDK projects.update(); raw HTTP |
| GET | `/v1/project/api-keys` | admin project key | List project API-key metadata. | Raw HTTP |
| POST | `/v1/project/api-keys` | admin project key | Create a project API key and receive its secret once. | Raw HTTP |
| GET | `/v1/project/api-keys/{keyId}` | admin project key | Read non-secret metadata for one project API key. | Raw HTTP |
| POST | `/v1/project/api-keys/{keyId}/revoke` | admin project key | Revoke a project API key. | Raw HTTP |
| POST | `/v1/project/api-keys/{keyId}/rotate` | admin project key | Rotate a project API key and receive the replacement secret once. | Raw HTTP |
| GET | `/v1/project/audit-logs` | admin project key, Business+ | List control-plane audit entries. | Raw HTTP |
| GET | `/v1/project/audit-logs/{id}` | admin project key, Business+ | Read one control-plane audit entry. | Raw HTTP |

### Webhooks

Webhook lifecycle, provider templates, destinations, routing, transforms, schedules, metrics, and security.

| Method | Route | Auth | Use | Client coverage |
| --- | --- | --- | --- | --- |
| GET | `/v1/webhooks` | project key | List webhooks with cursor pagination. | SDK webhooks.list(); CLI webhooks list |
| POST | `/v1/webhooks` | project key | Create a webhook and receive one-time secrets. | SDK webhooks.create(); CLI webhooks create |
| GET | `/v1/webhooks/http-packs` | project key | List provider-aware inbound packs. | Raw HTTP |
| GET | `/v1/webhooks/templates` | project key | List webhook templates. | SDK templates.list(); CLI templates list |
| GET | `/v1/webhooks/{id}` | project key | Read a webhook and quota detail. | SDK webhooks.get(); CLI webhooks get |
| PATCH | `/v1/webhooks/{id}` | project key | Update webhook configuration. | Raw HTTP |
| POST | `/v1/webhooks/{id}/pause` | project key | Pause public ingest for a webhook. | SDK webhooks.pause(); CLI webhooks pause |
| POST | `/v1/webhooks/{id}/resume` | project key | Resume a paused webhook. | SDK webhooks.resume(); CLI webhooks resume |
| POST | `/v1/webhooks/{id}/archive` | project key | Archive a webhook. | SDK webhooks.archive(); CLI webhooks archive |
| POST | `/v1/webhooks/{id}/restore` | project key | Restore an archived webhook. | SDK webhooks.restore(); CLI webhooks restore |
| POST | `/v1/webhooks/{id}/destroy` | project key | Destroy an archived webhook. | SDK webhooks.destroy(); CLI webhooks destroy |
| POST | `/v1/webhooks/{id}/rotate-ingest-secret` | project key | Rotate the ingest secret and receive the replacement once. | SDK webhooks.rotateIngestSecret(); CLI webhooks rotate-ingest-secret |
| POST | `/v1/webhooks/{id}/rotate-signing-secret` | project key | Rotate the signing secret and receive the replacement once. | SDK webhooks.rotateSigningSecret(); CLI webhooks rotate-signing-secret |
| GET | `/v1/webhooks/{id}/secret-versions` | project key | List non-secret version metadata for webhook secrets. | SDK webhooks.listSecretVersions(); CLI webhooks secret-versions |
| POST | `/v1/webhooks/{id}/test-delivery` | project key | Run a synchronous test delivery against the default destination. | Raw HTTP |
| GET | `/v1/webhooks/{id}/destinations` | project key | List webhook destinations. | Raw HTTP |
| POST | `/v1/webhooks/{id}/destinations` | project key | Create a named destination. | Raw HTTP |
| PATCH | `/v1/webhooks/{id}/destinations/{destinationId}` | project key | Update a destination. | Raw HTTP |
| DELETE | `/v1/webhooks/{id}/destinations/{destinationId}` | project key | Delete a non-default destination. | Raw HTTP |
| GET | `/v1/webhooks/{id}/routing` | project key | Read route-to-one rules. | Raw HTTP |
| PUT | `/v1/webhooks/{id}/routing` | project key | Replace route-to-one rules. | Raw HTTP |
| GET | `/v1/webhooks/{id}/transform` | project key | Read the saved payload transform. | Raw HTTP |
| PUT | `/v1/webhooks/{id}/transform` | project key | Replace or clear the saved payload transform. | Raw HTTP |
| GET | `/v1/webhooks/{id}/schedules` | project key | List schedules for one webhook. | SDK schedules.list(); CLI schedules list |
| POST | `/v1/webhooks/{id}/schedules` | project key, Starter+ | Create a recurring schedule. | SDK schedules.create(); CLI schedules create |
| DELETE | `/v1/webhooks/{id}/schedules/{scheduleId}` | project key | Delete a schedule. | SDK schedules.delete(); CLI schedules delete |
| POST | `/v1/webhooks/{id}/schedules/{scheduleId}/pause` | project key | Pause a schedule. | SDK schedules.pause(); CLI schedules pause |
| POST | `/v1/webhooks/{id}/schedules/{scheduleId}/resume` | project key | Resume a schedule. | SDK schedules.resume(); CLI schedules resume |
| GET | `/v1/webhooks/{id}/deliveries` | project key | List deliveries for one webhook. | Raw HTTP |
| GET | `/v1/webhooks/{id}/metrics` | project key | Read webhook delivery metrics for a time window. | Raw HTTP |
| GET | `/v1/webhooks/{id}/backlog` | project key | Read current and historical backlog shape. | Raw HTTP |
| GET | `/v1/webhooks/{id}/email-allowlist` | project key | List email sender allowlist entries. | Raw HTTP |
| POST | `/v1/webhooks/{id}/email-allowlist` | project key, Starter+ | Create an email sender allowlist entry. | Raw HTTP |
| DELETE | `/v1/webhooks/{id}/email-allowlist/{entryId}` | project key, Starter+ | Delete an email sender allowlist entry. | Raw HTTP |

### Ingest, forms, and files

Public source channels and file-download routes that produce or support delivery history.

| Method | Route | Auth | Use | Client coverage |
| --- | --- | --- | --- | --- |
| POST | `/v1/ingest/{publicId}` | webhook ingest secret | Publish an HTTP payload into one webhook. | SDK ingest helpers; CLI ingest send |
| GET | `/v1/form/{publicId}` | unguessable public ID | Render a minimal HTML form page. | Browser or raw HTTP |
| POST | `/v1/form/{publicId}` | unguessable public ID | Submit a browser form into one webhook. | Browser or raw HTTP |
| OPTIONS | `/v1/form/{publicId}` | none | Return form-ingest CORS preflight headers. | Browser |
| GET | `/v1/files/{signedToken}` | signed token | Download a file through a temporary signed URL. | Browser or raw HTTP |
| GET | `/v1/webhooks/{webhookId}/deliveries/{deliveryId}/files/{index}` | project key | Download a retained delivery file through an authenticated route. | Raw HTTP |

### Deliveries, replay, and DLQ

Delivery inspection, replay, async bulk operations, dead-letter recovery, and usage.

| Method | Route | Auth | Use | Client coverage |
| --- | --- | --- | --- | --- |
| GET | `/v1/deliveries` | project key | List project deliveries with filters and cursor pagination. | SDK deliveries.list(); CLI deliveries list |
| POST | `/v1/deliveries/bulk-replay` | project key, Starter+ | Create an async bulk replay job over a frozen delivery search. | Raw HTTP |
| GET | `/v1/deliveries/{id}` | project key | Read one delivery and its attempts. | SDK deliveries.get(); CLI deliveries get |
| POST | `/v1/deliveries/{id}/replay` | project key | Replay one retained delivery. | SDK deliveries.replay(); CLI deliveries replay |
| GET | `/v1/deliveries/{id}/replay-jobs` | project key | List replay jobs for one source delivery. | Raw HTTP |
| GET | `/v1/replay-jobs/{id}` | project key | Read one replay job. | SDK replayJobs.get(); CLI replay-jobs get |
| GET | `/v1/bulk-operations/{id}` | project key | Read one bulk replay or bulk recovery job. | Raw HTTP |
| GET | `/v1/dlq` | project key | List dead-letter entries. | SDK dlq.list(); CLI dlq list |
| GET | `/v1/dlq/export` | project key | Export dead-letter entries with retained source payload snapshots. | SDK dlq.export(); CLI dlq export |
| POST | `/v1/dlq/bulk-re-drive` | project key, Starter+ | Create an async bulk DLQ recovery job. | Raw HTTP |
| GET | `/v1/dlq/{id}` | project key | Read one dead-letter entry. | SDK dlq.get(); CLI dlq get |
| POST | `/v1/dlq/{id}/re-drive` | project key | Create a fresh replay delivery from one DLQ entry. | SDK dlq.redrive(); CLI dlq redrive |
| GET | `/v1/usage` | project key | Read project usage rollups. | SDK usage.get(); CLI usage show |

### Event drains

Project-scoped delivery lifecycle streaming sinks. Dashboard-first, not wrapped by first-party clients.

| Method | Route | Auth | Use | Client coverage |
| --- | --- | --- | --- | --- |
| GET | `/v1/app/event-drains` | project key | List event drains for the authenticated project. | Raw HTTP |
| POST | `/v1/app/event-drains` | project key, Pro+ | Create an event drain, subject to tier drain limits. | Raw HTTP |
| GET | `/v1/app/event-drains/{drainId}` | project key | Read one event drain. | Raw HTTP |
| PATCH | `/v1/app/event-drains/{drainId}` | project key, Pro+ | Update one event drain. | Raw HTTP |
| POST | `/v1/app/event-drains/{drainId}/pause` | project key | Pause one event drain. | Raw HTTP |
| POST | `/v1/app/event-drains/{drainId}/resume` | project key, Pro+ | Resume one event drain and reset its consecutive-failure counter. | Raw HTTP |
| DELETE | `/v1/app/event-drains/{drainId}` | project key | Delete one event drain. | Raw HTTP |

### Operator alerting

Project-scoped alert channels, rules, webhook-backed alert delivery, incidents, and failure clusters.

| Method | Route | Auth | Use | Client coverage |
| --- | --- | --- | --- | --- |
| GET | `/v1/project/operator-webhooks` | admin project key | List webhook-backed operator notification endpoints. | Raw HTTP |
| POST | `/v1/project/operator-webhooks` | admin project key, Pro+ | Create a webhook-backed operator notification endpoint. | Raw HTTP |
| GET | `/v1/project/operator-webhooks/{id}` | admin project key | Read one operator notification endpoint. | Raw HTTP |
| PATCH | `/v1/project/operator-webhooks/{id}` | admin project key, Pro+ | Update one operator notification endpoint. | Raw HTTP |
| POST | `/v1/project/operator-webhooks/{id}/pause` | admin project key | Pause an operator notification endpoint. | Raw HTTP |
| POST | `/v1/project/operator-webhooks/{id}/resume` | admin project key, Pro+ | Resume an operator notification endpoint. | Raw HTTP |
| POST | `/v1/project/operator-webhooks/{id}/archive` | admin project key | Archive an operator notification endpoint. | Raw HTTP |
| POST | `/v1/project/operator-webhooks/{id}/restore` | admin project key, Pro+ | Restore an archived operator notification endpoint. | Raw HTTP |
| POST | `/v1/project/operator-webhooks/{id}/rotate-signing-secret` | admin project key, Pro+ | Rotate an operator notification endpoint signing secret. | Raw HTTP |
| GET | `/v1/project/operator-webhooks/{id}/secret-versions` | admin project key | List non-secret signing-secret version metadata. | Raw HTTP |
| GET | `/v1/project/operator-webhooks/{id}/dispatches` | admin project key | List dispatch history for one operator notification endpoint. | Raw HTTP |
| GET | `/v1/project/alert-channels` | admin project key | List alert channels. | Raw HTTP |
| POST | `/v1/project/alert-channels` | admin project key, Pro+ | Create an alert channel. | Raw HTTP |
| GET | `/v1/project/alert-channels/{id}` | admin project key | Read one alert channel. | Raw HTTP |
| PATCH | `/v1/project/alert-channels/{id}` | admin project key, Pro+ | Update one alert channel. | Raw HTTP |
| GET | `/v1/project/alert-channels/{id}/dispatches` | admin project key | List dispatch history for one alert channel. | Raw HTTP |
| GET | `/v1/project/alert-rules` | admin project key | List fixed alert rules. | Raw HTTP |
| GET | `/v1/project/alert-rules/{family}` | admin project key | Read one fixed alert rule. | Raw HTTP |
| PATCH | `/v1/project/alert-rules/{family}` | admin project key, Pro+ | Update one fixed alert rule. | Raw HTTP |
| GET | `/v1/project/operator-failure-clusters` | admin project key | List recent delivery and DLQ failure clusters. | Raw HTTP |
| GET | `/v1/project/operator-incidents` | admin project key | List operator incidents. | Raw HTTP |
| GET | `/v1/project/operator-incidents/{id}` | admin project key | Read one operator incident with dispatch history. | Raw HTTP |
| POST | `/v1/project/operator-incidents/{id}/mute` | admin project key | Mute one operator incident. | Raw HTTP |
| POST | `/v1/project/operator-incidents/{id}/unmute` | admin project key | Unmute one operator incident. | Raw HTTP |
| POST | `/v1/project/operator-incidents/{id}/resolve` | admin project key | Resolve one operator incident. | Raw HTTP |
| POST | `/v1/project/operator-incidents/{id}/reopen` | admin project key | Reopen one operator incident. | Raw HTTP |

## Common mistakes

- Treating dashboard-only product workflows as integration endpoints.
- Assuming the SDK or CLI wraps every public route. Use the client coverage column before choosing an implementation path.
- Publishing raw secrets in examples, screenshots, logs, or issue reports.
- Using a write key for routes that require an admin project key.