Making API Calls to PayloadRelay

Send payloads to PayloadRelay endpoints from any language or tool. This guide covers the most common clients and payload formats.

Purpose

This guide helps you:

• Send JSON, form-encoded, plain text, and query parameter payloads.
• Use curl, JavaScript fetch(), and Python requests.
• Read response headers for quota and rate-limit info.
• Authenticate requests when the endpoint requires it.

Prerequisites and permissions

• A PayloadRelay endpoint URL (https://api.payloadrelay.com/relay/{endpointId}).
• The endpoint's accepted method and payload format.
• Auth credentials if the endpoint requires inbound authentication.

Step-by-step workflow

1. Sending JSON payloads

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 -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"

3. Unsupported file uploads / multipart requests

PayloadRelay does not currently accept multipart/form-data or file uploads on relay endpoints.

If you send a browser-style form post or use tools like curl -F, the request will not be processed as an uploaded file payload. Use one of the supported endpoint formats instead:

• application/json
• application/x-www-form-urlencoded
• application/xml or text/xml
• text/plain
• Query parameter formats for endpoints configured to read from the URL

If you need to forward file-related data, send metadata or a file URL in JSON/form fields instead of uploading the binary file directly.

4. Sending plain text payloads

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)

Endpoints configured to accept GET read data from query parameters.

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

6. Response headers

PayloadRelay returns quota information in response headers on every relay request:

When an endpoint has a per-minute rate limit configured and your request is throttled:

Check these headers to monitor usage and handle rate limits gracefully:

curl -si https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: application/json" \
  -d '{"ping": true}' | grep -iE "x-subscription|x-monthly|retry-after"

7. Authenticated requests

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

Bearer token

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"}'

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" }),
});

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"}'

The header name is configured on the endpoint (e.g. X-Api-Key, X-Auth-Token).

Basic auth

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"}'

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 and verification checks

• Requests return HTTP 200 for accepted payloads.
• Response headers include X-Monthly-Request-Limit and X-Monthly-Requests-Used.
• Payloads appear in Request activity with outcome ACCEPTED.
• Configured targets receive the forwarded payload.

Common issues and fixes

• 401 Unauthorized: endpoint requires auth — include the correct credentials.
• 405 Method Not Allowed: use the method the endpoint is configured to accept.
• 415 Unsupported Media Type: set the correct Content-Type for the endpoint's payload format.
• 429 Too Many Requests: you hit the rate limit — check Retry-After and back off.
• 413 Payload Too Large: reduce payload size to stay within plan limits.

Related guides

• Getting Started
• Endpoint Management
• HTTP Methods
• Authentication and Secrets