← 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": "alice@example.com",
    "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=alice@example.com" \
  -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)#

To read the data from the query parameters, change two values in the Details tab of the endpoint editor, in this sequence:

  1. In Advanced, set Accepted HTTP method to GET. The editor then changes Expected payload format to None (ignore body). With that format, the query parameters do not become payload fields.
  2. Set Expected payload format to 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.