Skip to content
PayloadPuffin.
Join the waitlist

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/:

TEXT
https://api.payloadpuffin.com/v1/events

A 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:

TEXT
Authorization: Bearer $PAYLOADPUFFIN_API_KEY

Each operation also requires one scope on that key. Authentication lists the failure responses.

Content types

DirectionContent type
Request bodyapplication/json
Successful responseapplication/json
Error responseapplication/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.

JSON
{ "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.

LimitValueResponse when exceeded
POST /v1/events request body262,144 bytes (256 KiB)413 payload_too_large
POST /v1/events members other than payload65,536 bytes413 payload_too_large
POST /v1/events time to receive the whole body30 seconds400 validation_failed
Idempotency-Key header length1 to 48 characters400 validation_failed
Requests over a POST /v1/events size limit, per API key3 in a 60-second window429 rate_limited for a cooldown
limit on a list operation1 to 100, default 100400 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

OperationMethod and pathScope
Send an eventPOST /v1/eventsevents:write
List eventsGET /v1/eventsevents:read
Get an eventGET /v1/events/{eventId}events:read
Rerun an unbuilt eventPOST /v1/events/{eventId}/rerunevents:write

Deliveries

OperationMethod and pathScope
List deliveriesGET /v1/deliveriesdeliveries:read
Get a deliveryGET /v1/deliveries/{deliveryId}deliveries:read
Resend a deliveryPOST /v1/deliveries/{deliveryId}/resenddeliveries:write

Destinations

OperationMethod and pathScope
Create a destinationPOST /v1/destinationsdestinations:write
List destinationsGET /v1/destinationsdestinations:read
Delete a destinationDELETE /v1/destinations/{destinationId}destinations:write
Get a destinationGET /v1/destinations/{destinationId}destinations:read
Update a destinationPATCH /v1/destinations/{destinationId}destinations:write
Set destination delivery policyPUT /v1/destinations/{destinationId}/delivery-policydestinations:write
Reset destination delivery policyDELETE /v1/destinations/{destinationId}/delivery-policydestinations:write
Expire the previous signing secretPOST /v1/destinations/{destinationId}/expire-previous-secretdestinations:write
Set destination record settingsPUT /v1/destinations/{destinationId}/record-settingsdestinations:write
Reset destination record settingsDELETE /v1/destinations/{destinationId}/record-settingsdestinations:write
Rotate a destination signing secretPOST /v1/destinations/{destinationId}/rotate-secretdestinations:write

Sources

OperationMethod and pathScope
Create a sourcePOST /v1/sourcessources:write
List sourcesGET /v1/sourcessources:read
Delete a sourceDELETE /v1/sources/{sourceId}sources:write
Get a sourceGET /v1/sources/{sourceId}sources:read
Update a sourcePATCH /v1/sources/{sourceId}sources:write
Expire the previous source signing secretPOST /v1/sources/{sourceId}/expire-previous-secretsources:write
Expire the previous source tokenPOST /v1/sources/{sourceId}/expire-previous-tokensources:write
Rotate a source tokenPOST /v1/sources/{sourceId}/rotate-tokensources:write
Delete a source's signature verificationDELETE /v1/sources/{sourceId}/signaturesources:write
Set up signature verification for a sourcePUT /v1/sources/{sourceId}/signaturesources:write
Set the GET URL check of a sourcePUT /v1/sources/{sourceId}/query-challengesources:write
Remove the GET URL check of a sourceDELETE /v1/sources/{sourceId}/query-challengesources:write
Set the POST URL check of a sourcePUT /v1/sources/{sourceId}/body-challengesources:write
Remove the POST URL check of a sourceDELETE /v1/sources/{sourceId}/body-challengesources:write

Transforms

Each operation needs the scope of the transform's kind: destinations:* for a destination transform, sources:* for a source transform.

OperationMethod and pathScope
Create a transformPOST /v1/transformsdestinations:write or sources:write
List transformsGET /v1/transformsdestinations:read or sources:read
Delete a transformDELETE /v1/transforms/{transformId}destinations:write or sources:write
Get a transformGET /v1/transforms/{transformId}destinations:read or sources:read
Rename a transformPATCH /v1/transforms/{transformId}destinations:write or sources:write
Save a transform's draftPUT /v1/transforms/{transformId}/draftdestinations:write or sources:write
Preview a transformPOST /v1/transforms/{transformId}/previewdestinations:write or sources:write
Publish a transformPOST /v1/transforms/{transformId}/publishdestinations:write or sources:write
Upgrade a managed transformPOST /v1/transforms/{transformId}/upgradesources:write
Detach a managed transformPOST /v1/transforms/{transformId}/detachsources:write

Analytics

OperationMethod and pathScope
Get latency percentilesGET /v1/analytics/latencyanalytics:read
Get an analytics seriesGET /v1/analytics/seriesanalytics:read
Get analytics totalsGET /v1/analytics/totalsanalytics:read
Get usageGET /v1/analytics/usageanalytics: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.