Accessing

The Bevy Public API is accessible on /api.

For example, if your Bevy site is at https://events.bevy.com, then the API is accessible below https://events.bevy.com/api. That is your Base URL.

Versioning

The Bevy API is a versioned API. To specify the API version, set the version via the Accept header.‌
Example:

GET /api/search/chapters HTTP 1.1
Host: bevy.example.com
Accept: application/json; version=1.0

This is optional. If you do not specify a version in the Accept header, then the current version will be used by default.

Authentication

All API endpoints accept authentication. Some require it. For the endpoints that require credentials, you must use a Bevy API Key.

Obtaining Your API Key

Please note: API keys are exclusively granted to HQ Administrators (with access to Admin Dashboard).

Every HQ Administrator account is provisioned with an API key. (Check this article to see how to manage your key.) To locate yours:

1. Visit your account profile settings.
2. Navigate to the API Key tab.
3. Click the padlock icon to reveal or hide your API key.

Critical Security Reminder: Safeguarding Your API Key Your API key is a sensitive credential, much like your account password. Never share your API key with unauthorized individuals or embed it directly in publicly accessible code.

Resetting Your API Key and Its Impact

You can reset your API key at any time. However, it is crucial to understand that resetting your key will immediately invalidate the old key, causing any applications or integrations currently using it to fail. Ensure all services relying on your API key are updated with the new key after a reset.

Using the API key

To use the API key on an API request, you should specify an Authorization header.

The string must include the word "Token" followed by a space and the actual token.

Example:

Authorization: Token 99d4b091990fN314f9418ad846dd0e4bXpfc6ee4b

See the reference of individual API endpoints to learn which ones require authentication.

Responses

The outcome of API requests are communicated by both an HTTP status code and (where applicable) a detail string. The API detail string (or result body) is always a JSON-formatted string representing structured data, e.g., representing a single data record or a list of data records.
The following table shows the different types of response that can be expected.

Rate Limits

• Authorized users: 10,000 requests per day per user (requests with an authentication token). The limit is shared for all inbound IPs.  
• When the request is not authorized, in other words coming from Anonymous users, the limit is 5,000 requests per day per IP when the request is not authorized. 
• The search endpoints (/api/search/**) has a special rate limit of 50 requests per minute, per user or per IP (for anonymous users)