# Common API usage

## Base URL

All paths referenced for MessageBird services in the API references uses the following base URL:

{% code overflow="wrap" %}

```
https://api.bird.com/
```

{% endcode %}

## Base media URL

All paths referenced for retrieving media uses the following base URL:

```
https://media.api.bird.com
```

## Authentication

In order to authenticate HTTP requests with an access key, you must provide it in the [Authorization HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) with the following format. Replace \<access-key> with your valid access key.

```
Authorization: AccessKey <access-key>
```

## Authorization

Access key Authorization is determined by the [access roles](/api/api-access/access-roles.md) attached to your access key

## Formats and Headers

All HTTP responses are in JSON. It's advised to send the Accept HTTP header with the value application/json with each request. Both POST and PUT requests to the API must contain a JSON-formatted payload in the request body.

## Errors

MessageBird uses standard HTTP status codes to indicate success or failure of API requests.

* HTTP response codes in the 2xx range indicate the request was successfully processed
* HTTP response codes in the 4xx range indicate that there was a client error - for example: authentication error, not enough balance or wrong/missing parameters. Don't worry, the HTTP response body includes a JSON-formatted response that tells you exactly what went wrong. If you're stuck, feel free to [contact support](https://messagebird.com/en/help), we're happy to help you out
* HTTP response codes in the 5xx range indicate a server error. It's considered safe to retry the same request, preferably with a delay

## Pagination

When retrieving data via a request, the default page size is 10. This means the response will include a maximum of 10 items per page. If you need more items, you can set a custom value for the limit parameter, up to a maximum of 100.

| Name      | Description                                                                                                       | Example                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| limit     | Limits the number of results to return.                                                                           | 10                                                                       |
| pageToken | Tracks the current position in the list. Use it as the `pageToken` in the next request to continue fetching data. | WzE3MzIyMTIxNTU1NTAsIjY3MzEyNjAxLWQ4NjUtNGI1YS1hMmRmLTQ2ZGRiOWQ2NmUwOCJd |

If a response includes a `nextPageToken`, it indicates there are additional items available to fetch from the API. To retrieve the next set of items, provide the `nextPageToken` value as the `pageToken` parameter in the subsequent request.

```json
{
  "results": [],
  "nextPageToken": "WzE3MzIyMTIxNTU1NTAsIjY3MzEyNjAxLWQ4NjUtNGI1YS1hMmRmLTQ2ZGRiOWQ2NmUwOCJd"
}
```

> **Important:** Pages can occasionally be empty or contain fewer items than expected, even when more items are available. To reliably determine the end of the list, always check for the presence of the `nextPageToken` field in the response. If `nextPageToken` is present, you should perform another request using the provided token, regardless of the current page's content.

A follow-up request would look like this:

```http
GET /endpoint?limit=10&pageToken=abc123
```

In this example, the value of `abc123` from the `nextPageToken` in the previous response is passed as the `pageToken` parameter to fetch the next set of items.

## Rate Limits

50 retrieval calls per second burst or 2,000 retrieval calls per minute steady.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/api-access/common-api-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.