Call the Bevy public API on your community’s /api base URL. Set the optional Accept version header, send Authorization: Token with your API key when the endpoint needs it, and stay under the account rate limits.
Use this page for the shared request rules every public Bevy API call follows. Endpoint fields and paths stay in Bevy API Reference. To explore the same OpenAPI file in Postman, see Use the Bevy API spec in Postman.
Get the base URL
The public API lives under /api on your community domain. That full address is your base URL.
Example: if your site is https://events.example.com, the base URL is https://events.example.com/api.
Send each request to a path under that base (for example /search/chapters/ on that host).
Set the API version
Bevy uses Accept-header versioning. To pin a version, set the Accept header:
Accept: application/json; version=1.0
If you omit the version, Bevy uses the current default (today, 1.0).
Authenticate with your API key
Every public endpoint accepts authentication. Some require it. When credentials are required, send a Bevy API key in the Authorization header. The value is the word Token, a space, then the key:
Authorization: Token your-api-key-here
Only HQ administrators can view and reset an API key. Get or reset yours in Manage your Bevy API key. Which data that key can reach still follows the permissions on that HQ admin account.
Check Bevy API Reference for which operations require authentication.
Important: Treat the API key like a password. Do not share it or put it in public code, client-side scripts, or shared collection exports.
Read the response
Every response uses an HTTP status code. Bodies are JSON when the endpoint returns data or an error detail.
| Status | Typical body | Meaning |
|---|---|---|
| 200 | {...} |
OK |
| 201 | {...} |
Resource created |
| 204 | (empty) | Resource deleted or no content |
| 400 | {"field_name": "Error message"} |
Invalid request |
| 403 | {"detail": "Permission Denied"} |
Permission denied |
| 429 | {"detail": "Request was throttled..."} |
Rate limit exceeded — wait for Retry-After
|
| 500 | (varies) | Server error |
Know the rate limits
These account-wide ceilings apply across public API endpoints on your Bevy instance:
- Authenticated (request includes a valid API token): 10,000 requests per day per user. The limit is shared across inbound IPs for that user.
- Unauthenticated (anonymous): 5,000 requests per day per client IP.
-
Search endpoints (
/api/search/**): an extra ceiling of 50 requests per minute per user, or per IP when anonymous, in addition to the daily account limit.
Some operations publish a tighter per-endpoint ceiling in Bevy API Reference. A request must fit under both that ceiling and the account-wide limit. When you exceed a limit, Bevy returns 429 with a Retry-After header — wait at least that many seconds before retrying.
Tip: Not sure whether to call the API or subscribe to webhooks? See Choose the public API or webhooks.