← Back to documentation

Making API Calls to PayloadRelay

Send JSON, form data, plain text, or query parameters with common HTTP clients.

3 min read

Use these examples to send data to a PayloadRelay endpoint. The examples use common clients and payload formats.

Purpose#

Use this guide to:

  • Send JSON, form data, plain text, or query parameters.
  • Use curl, JavaScript fetch(), or Python requests.
  • Handle an accepted response and a response that permits a retry.
  • Authenticate a request when the endpoint requires authentication.

Before you start#

  • Get the PayloadRelay endpoint URL: https://api.payloadrelay.com/relay/{endpointId}.
  • Make sure that you know the endpoint method and payload format.
  • If the endpoint requires inbound authentication, get the authentication credentials.

Procedure#

1. Sending JSON payloads#

curl
curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user.signup",
    "email": "[email protected]",
    "plan": "pro",
    "timestamp": "2025-01-15T10:30:00Z"
  }'

2. Sending form-encoded payloads#

curl
curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -d "name=Alice" \
  -d "[email protected]" \
  -d "message=Hello from the contact form"

With the -d option, curl sends application/x-www-form-urlencoded by default.

3. File uploads and multipart requests are not supported#

PayloadRelay does not accept multipart/form-data or a file upload on a relay endpoint.

PayloadRelay rejects a multipart submission. This includes a request that you send with curl -F. Use one of these supported formats:

  • application/json
  • application/x-www-form-urlencoded
  • application/xml or text/xml
  • text/plain
  • A query parameter format, for an endpoint that reads the data from the URL

To forward file information, send metadata or a file URL in JSON or form fields. Do not upload the binary file.

4. Sending plain text payloads#

curl
curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: text/plain" \
  -d "Server rebooted at 2025-01-15T10:30:00Z. All services healthy."

5. Sending query parameter payloads (GET)#

An endpoint that accepts GET reads the data from the query parameters.

curl
curl "https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID?event=ping&source=monitor&status=ok"

6. Response and retry headers#

An accepted relay request returns 202 Accepted with:

Code Example
{"message":"Payload received"}

A public relay response does not contain the plan, the quota usage, a reset date, the billing state, organization data, or other account metadata. An account owner or an administrator can read the current usage in Billing, or with the authenticated GET /billing/usage API.

A response that permits a retry can contain this header:

HeaderDescription
Retry-AfterSeconds to wait before you retry. Use this value when the header is present.

When the response contains Retry-After, wait for that number of seconds before you retry:

Code Example
curl -i https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: application/json" \
  -d '{"ping": true}'

7. Authenticated requests#

When an endpoint requires inbound authentication, include the credentials in every request.

Bearer token

Code Example
curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"event": "deploy", "version": "2.1.0"}'
Code Example
await fetch("https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID", {
  method: "POST",
  headers: {
    Authorization: "Bearer your-secret-token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ event: "deploy", version: "2.1.0" }),
});
API key header
curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"event": "deploy", "version": "2.1.0"}'

You configure the header name on the endpoint, for example, X-Api-Key or X-Auth-Token.

Basic authentication

Code Example
curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{"event": "deploy", "version": "2.1.0"}'
Code Example
import requests

response = requests.post(
    "https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID",
    auth=("username", "password"),
    json={"event": "deploy", "version": "2.1.0"},
)

Expected result#

  • A request with an accepted payload returns HTTP 202 Accepted.
  • An accepted response contains only the generic {"message":"Payload received"} body and operational HTTP metadata.
  • A payload appears in Request activity as Completed (ACCEPTED).
  • Each configured target receives the forwarded payload.

Common issues#

  • 401 Unauthorized: The endpoint requires authentication. Include the correct credentials.
  • 405 Method Not Allowed: The request uses a method that the endpoint does not accept.
  • 415 Unsupported Media Type: Set Content-Type to match the endpoint payload format.
  • 429 Too Many Requests: The request exceeded a rate limit. Use Retry-After and wait before you retry. This value is a retry delay, not a quota reset time. An account owner can read the current usage in Billing.
  • 413 Payload Too Large: Make the payload smaller than the plan limit.
← Back to documentation