ZeroCut REST API authentication, test requests, rate limits, and versioning.
Use the ZeroCut REST API to read your creator data and automate donations, follower records, and live sessions. The OpenAPI specification describes the JSON endpoints, their operation IDs, inputs, responses, and errors.
x-api-key header. Start with GET /api/v1/profile/get to verify access.The documentation and OpenAPI specification are public. Account setup and key creation require a person to sign in; there is no anonymous key-issuance endpoint.
All API requests require an API key passed in the x-api-key header:
curl -H "x-api-key: zerocut.your_api_key_here" \
https://zerocut.gg/api/v1/profile/getYou can create and manage API keys in your dashboard settings.
Keys belong to one creator account. They grant access to that account's API reads and writes and can be disabled or revoked in settings. There are no per-key permission scopes or delegated OAuth grants. ZeroCut's provider sign-in and payment-provider connections do not authorize REST API clients.
Use /api/test/v1 in place of /api/v1 for the documented test responses. Authentication, subscription checks, input validation, and rate limits still apply. Test requests can write API usage logs. Event streaming and stream-token creation are unavailable in test mode.
For example, test donation creation with a fixture response:
curl https://zerocut.gg/api/test/v1/donation/create \
-H "x-api-key: $ZEROCUT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"amount":10,"currency":"usd","donorName":"Test Donor"}'The test donation endpoint returns sample data without recording a real donation or charging a payment method. The production donation endpoint records a donation; do not use it as a connectivity probe.
GET /api/v1/events/stream pushes donations, perk purchases, followers, and
goal completions over Server-Sent Events. Use GET /api/v1/perk/list to
discover IDs for a perk-filtered subscription. The stream returns
text/event-stream, which has no JSON
response schema, so it is absent from the OpenAPI document and from any
client generated from it — do not expect a generated method for it. It is
documented by hand in Event Stream (SSE). Its
companion POST /api/v1/events/stream-token is a normal JSON endpoint and is
in the document.
The JSON API enforces a sliding window rate limit of 60 requests per minute per user account. All API keys belonging to the same account share this limit. A separate 120 requests per minute IP limit applies before authentication. Stream-token creation also has a 30 requests per minute limit per key. The event stream has separate connection limits.
Responses from the JSON API dispatcher include the applicable rate limit headers, including authentication failures, unknown API paths, rejected HTTP methods, and throttled responses. Public documentation and OpenAPI responses do not consume this quota and do not report a remaining allowance.
RateLimit-Policy and RateLimit use the IETF HTTPAPI draft format. Existing X-RateLimit-* headers remain available.
| Header | Description |
|---|---|
RateLimit-Policy | Policy name, request quota, and window in seconds, such as "account";q=60;w=60 |
RateLimit | Remaining requests and seconds until capacity returns, such as "account";r=59;t=60 |
X-RateLimit-Limit | Maximum requests allowed for the reported policy |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp in seconds when the oldest request leaves the sliding window |
When the limit is exceeded, the API returns a 429 Too Many Requests response with an additional Retry-After header indicating how many seconds to wait:
{
"error": "Rate limit exceeded. Please try again later.",
"code": "TOO_MANY_REQUESTS"
}X-RateLimit-Remaining header and back off before hitting 0Retry-After header to schedule retries after a 429 responseThe current REST API version is v1, served at /api/v1. Breaking request or response changes require a new API version. Clients should tolerate new optional fields and new endpoints within a version.
Deprecations are announced in the ZeroCut changelog, with a replacement and a retirement date before removal. A retiring endpoint will carry Deprecation and Sunset response headers. No retirement date is currently scheduled for v1, so current responses do not include those headers.