# API fundamentals

This page provides a high-level overview of the core concepts you need before working with the **Distribution API**.
It covers authentication, environments, partner access, and general request behaviour. The details in this section apply across both main integration pathways (RFP and Direct booking).

## Authentication

All requests to the API must be authenticated using an **API key** provided during onboarding.
Pass your key in the request header:


```
X-API-KEY: <your-api-key>
```

The API key identifies your organisation and determines which venues you can access. Treat keys as secrets and never expose them in client-side code.

## Environments

The Distribution API is available in two environments:

### **Sandbox**


```
https://sandbox.meetingpackage.co
```

Sandbox is intended for development and early integration work.

At present, sandbox may not fully mirror production behaviour or data, and may require
additional configuration to be usable. Because of this, some partners validate parts of
their integration against production during assisted onboarding.

### **Production**


```
https://api.meetingpackage.co
```

Production hosts live venues and real operational data.

Access is provided during onboarding. In cases where sandbox is not suitable for
end-to-end testing, MeetingPackage may ask partners to validate specific flows in
production (with agreed test data and support). **Do not send test traffic to production
unless agreed during onboarding.**

> **Note:** Improving sandbox parity and providing standardised test data are planned
enhancements.


## Venue access & permissions

API keys only allow access to **venues that are explicitly configured for the partner**.
This applies in both sandbox and production environments.

You will only be able to:

* Search availability for assigned venues
* Create or manage bookings for those venues
* Retrieve data models and resources associated with those venues


Attempting to interact with unassigned venues will return an error.

## Request & response formats

The API uses standard HTTP conventions:

* **URL parameters** for path identifiers
* **Query parameters** for filtering or searching
* **JSON request bodies** for creating or updating resources
* **JSON responses** for all successful operations and errors


Because different endpoints use different parameter styles, consult the [API Reference](/openapi/distro-openapi) for the exact structure required in each operation.

## Errors

The API returns structured JSON error responses when a request cannot be processed.
Common causes include:

* Missing or invalid authentication
* Accessing venues not available to your organisation
* Invalid dates, capacities, or booking rules
* Unsupported or malformed request payloads


## Rate limits

The API may apply rate limits to ensure fair usage and platform stability.
If rate limits are exceeded, the API returns an error indicating when the client may retry.
More detailed guidance will be provided once the policy is finalised.

## Event notifications

Some integrations use a “booking update notification” model, where the API sends webhook events when bookings or orders change.
If your integration requires near-real-time visibility of updates, see [Events](/docs/guide/events) for details on subscribing to and handling these notifications.

## Next steps

- Explore the integration workflows:
  - [Venue content](/docs/workflows/venue-content)
  - [Direct booking](/docs/workflows/direct-booking)
  - [RFP workflow](/docs/workflows/rfp)
- Browse the [API Reference](/openapi/distro-openapi) for all available operations and webhooks.