Use the public API to send events, configure webhook routing and inspect delivery outcomes. Requests and responses use JSON. Every operation acts on the app that the API key belongs to. This page lists the conventions that hold for every operation, and links to each operation's reference page.
Base URL
Every operation is served from one origin, and every path starts with /v1/:
https://api.payloadpuffin.com/v1/eventsA path that doesn't match an operation, or a method that the path doesn't accept, returns 404 with the error code not_found.
Versioning
The major version is the first path segment, /v1/. Every operation is currently marked preview in its reference page. The machine-readable description is the OpenAPI document that the operation reference pages are generated from.
Authentication
Every operation requires an API key, sent as a Bearer token:
Authorization: Bearer $PAYLOADPUFFIN_API_KEYEach operation also requires one scope on that key. Authentication lists the failure responses.
Content types
| Direction | Content type |
|---|---|
| Request body | application/json |
| Successful response | application/json |
| Error response | application/problem+json |
Send a body as JSON, with Content-Type: application/json or another JSON type such as application/vnd.api+json. Any other Content-Type, or a body without one, fails with 415 unsupported_media_type. An operation whose body fields are all optional can be called without a body, which counts as {}. A body that isn't a JSON object fails with 400 validation_failed.
Query parameters and body fields that an operation doesn't define are refused with 400 validation_failed. Errors describes the error body.
Response body
A successful response puts what it returns in data. A list operation returns an array there, with links.next for the next page (Pagination). Every other operation returns one object. A field that has no value is null, never left out.
{ "data": { "id": "dst_01m4pa5v4wetwab7xhgrev2tag", "name": "Staging receiver" } }A list operation returns a short version of each item. The matching get operation, such as Get a destination, returns the whole item, and so does every operation that changes it. Deleting an item returns its id.
Limits
These limits are enforced by the API. Operation pages list the limits of individual fields, such as the length of an event type.
| Limit | Value | Response when exceeded |
|---|---|---|
POST /v1/events request body | 262,144 bytes (256 KiB) | 413 payload_too_large |
POST /v1/events members other than payload | 65,536 bytes | 413 payload_too_large |
POST /v1/events time to receive the whole body | 30 seconds | 400 validation_failed |
Idempotency-Key header length | 1 to 48 characters | 400 validation_failed |
Requests over a POST /v1/events size limit, per API key | 3 in a 60-second window | 429 rate_limited for a cooldown |
limit on a list operation | 1 to 100, default 100 | 400 validation_failed |
During that cooldown, POST /v1/events returns 429 for that key, with Retry-After saying how long it lasts. Other operations aren't affected.
POST /v1/events can also return 429 rate_limited when PayloadPuffin is busy, when the organization exceeds its plan's ingest rate or ingest volume, or when an app holds too many events. Retry after the number of seconds in Retry-After. Rate limiting lists each reason. There is no fixed per-key request rate limit.
Operations
Each operation has an ID, such as create_event. The OpenAPI document uses it as the operationId.
Events
| Operation | Method and path | Scope |
|---|---|---|
| Send an event | POST /v1/events | events:write |
| List events | GET /v1/events | events:read |
| Get an event | GET /v1/events/{eventId} | events:read |
| Rerun an unbuilt event | POST /v1/events/{eventId}/rerun | events:write |
Deliveries
| Operation | Method and path | Scope |
|---|---|---|
| List deliveries | GET /v1/deliveries | deliveries:read |
| Get a delivery | GET /v1/deliveries/{deliveryId} | deliveries:read |
| Resend a delivery | POST /v1/deliveries/{deliveryId}/resend | deliveries:write |
Destinations
| Operation | Method and path | Scope |
|---|---|---|
| Create a destination | POST /v1/destinations | destinations:write |
| List destinations | GET /v1/destinations | destinations:read |
| Delete a destination | DELETE /v1/destinations/{destinationId} | destinations:write |
| Get a destination | GET /v1/destinations/{destinationId} | destinations:read |
| Update a destination | PATCH /v1/destinations/{destinationId} | destinations:write |
| Set destination delivery policy | PUT /v1/destinations/{destinationId}/delivery-policy | destinations:write |
| Reset destination delivery policy | DELETE /v1/destinations/{destinationId}/delivery-policy | destinations:write |
| Expire the previous signing secret | POST /v1/destinations/{destinationId}/expire-previous-secret | destinations:write |
| Set destination record settings | PUT /v1/destinations/{destinationId}/record-settings | destinations:write |
| Reset destination record settings | DELETE /v1/destinations/{destinationId}/record-settings | destinations:write |
| Rotate a destination signing secret | POST /v1/destinations/{destinationId}/rotate-secret | destinations:write |
Sources
| Operation | Method and path | Scope |
|---|---|---|
| Create a source | POST /v1/sources | sources:write |
| List sources | GET /v1/sources | sources:read |
| Delete a source | DELETE /v1/sources/{sourceId} | sources:write |
| Get a source | GET /v1/sources/{sourceId} | sources:read |
| Update a source | PATCH /v1/sources/{sourceId} | sources:write |
| Expire the previous source signing secret | POST /v1/sources/{sourceId}/expire-previous-secret | sources:write |
| Expire the previous source token | POST /v1/sources/{sourceId}/expire-previous-token | sources:write |
| Rotate a source token | POST /v1/sources/{sourceId}/rotate-token | sources:write |
| Delete a source's signature verification | DELETE /v1/sources/{sourceId}/signature | sources:write |
| Set up signature verification for a source | PUT /v1/sources/{sourceId}/signature | sources:write |
| Set the GET URL check of a source | PUT /v1/sources/{sourceId}/query-challenge | sources:write |
| Remove the GET URL check of a source | DELETE /v1/sources/{sourceId}/query-challenge | sources:write |
| Set the POST URL check of a source | PUT /v1/sources/{sourceId}/body-challenge | sources:write |
| Remove the POST URL check of a source | DELETE /v1/sources/{sourceId}/body-challenge | sources:write |
Transforms
Each operation needs the scope of the transform's kind: destinations:* for a destination transform, sources:* for a source transform.
| Operation | Method and path | Scope |
|---|---|---|
| Create a transform | POST /v1/transforms | destinations:write or sources:write |
| List transforms | GET /v1/transforms | destinations:read or sources:read |
| Delete a transform | DELETE /v1/transforms/{transformId} | destinations:write or sources:write |
| Get a transform | GET /v1/transforms/{transformId} | destinations:read or sources:read |
| Rename a transform | PATCH /v1/transforms/{transformId} | destinations:write or sources:write |
| Save a transform's draft | PUT /v1/transforms/{transformId}/draft | destinations:write or sources:write |
| Preview a transform | POST /v1/transforms/{transformId}/preview | destinations:write or sources:write |
| Publish a transform | POST /v1/transforms/{transformId}/publish | destinations:write or sources:write |
| Upgrade a managed transform | POST /v1/transforms/{transformId}/upgrade | sources:write |
| Detach a managed transform | POST /v1/transforms/{transformId}/detach | sources:write |
Analytics
| Operation | Method and path | Scope |
|---|---|---|
| Get latency percentiles | GET /v1/analytics/latency | analytics:read |
| Get an analytics series | GET /v1/analytics/series | analytics:read |
| Get analytics totals | GET /v1/analytics/totals | analytics:read |
| Get usage | GET /v1/analytics/usage | analytics:read |
Reading a destination with include=secret or include=previous_secret needs both destinations:read and destinations:write.
API keys are created, rotated and deleted in the console. The API has no operation that manages API keys.