API Basics
This page covers everything you need before writing your first API call — environments, authentication, error handling, pagination, and translations.
Environments
| Environment | Base URL | Purpose |
|---|---|---|
| Sandbox | https://api-sandbox.mozrest.com/ | Development and integration testing |
| Production | https://api.mozrest.com/ | Live operations |
All examples in this documentation use the Sandbox base URL. Replace it with the Production URL when going live.
Authentication
All requests must be authenticated with a Bearer token in the Authorization header. Your API key will be provided by the Mozrest team during onboarding.
- Only HTTPS requests are accepted.
- No password is required — the API key is the sole credential.
curl "https://api-sandbox.mozrest.com/v1/bc" \
-H "Authorization: Bearer {api_key}"
Keep your API key secret. Do not expose it in client-side code or public repositories.
Errors
Mozrest uses standard HTTP response codes to indicate request success or failure.
| Code | State | Description |
|---|---|---|
| 200 | OK | Everything worked as expected |
| 400 | Bad Request | Missing or invalid required parameter |
| 401 | Unauthorized | API key is missing or not valid |
| 402 | Request Failed | Parameters were valid but the request could not be processed |
| 403 | Forbidden | Access forbidden for this resource |
| 404 | Not Found | The requested resource does not exist |
| 5xx | Server Error | Something went wrong on Mozrest's server |
Versioning
The current API version is v1, included in the URL path (/v1/bc/...). Mozrest releases new versions only when introducing breaking changes. Non-breaking additions (new fields, new endpoints) are added to the current version without a version bump.
Forward Compatibility
Mozrest may add new fields to request and response payloads at any time. These additions are not considered breaking changes.
Your integration must:
- Ignore unknown fields — do not reject or fail when receiving properties that are not in your current implementation.
- Use lenient deserialization — avoid strict schema validation that would break on new fields.
Mozrest will never make backward-incompatible changes (removing fields, changing types, or altering semantics of existing fields) without prior notice and a migration plan.
Pagination
Mozrest uses offset-based pagination. Include offset and limit as query parameters to control the result window.
| Parameter | Constraints | Default | Description |
|---|---|---|---|
offset | 0 or greater | 0 | Index of the first element to return |
limit | 1 to 50 | 10 | Number of elements to return |
Translations
Mozrest supports translations for certain entities (venues, areas, etc.). To request data in a specific language, include the x-locale header in your request using ISO 639-1 format.
curl "https://api-sandbox.mozrest.com/v1/bc/venues/{venueId}" \
-H "Authorization: Bearer {api_key}" \
-H "x-locale: es"
If the requested translation is not available, data is returned in the venue's default locale.