> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mottostreaming.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> A highly scalable API for end-users to access Motto resources

## What for?

The Content Delivery API is the API that allows your website or app to show content to end-users.
It is (mostly) a read-only API built for high scalability, though it does support various write operations.

If you are looking for an API to integrate into your management tooling, have a look at our [Studio API](/reference/studio-api/introduction).

## Get Started

Unlike the Studio API, the Content Delivery API does not offer a REST interface in the traditional sense, as it uses a protocol called [Connect](/reference/deep-dive/connect-protocol). But do not worry!
The API still works with standard `GET` and `POST` requests, and will return standard JSON.
The primary difference with REST is that the API routes look a little different than you may be used to.

<Tip>
  If you would like to use a code-generated client in the language of your choice, please have a look at our [SDKs](https://buf.build/motto/cda/sdks). We believe it's great time-saver (after a bit of initial setup effort)!
</Tip>

### GET requests

To understand how to use Motto's Content Delivery API using standard HTTP `GET` requests for read-only operations, please follow along with a basic example.

Let's say we want to get a list of all events in the project, you would send a `GET` request to the following URL:

`https://cda.mottostreaming.com/motto.cda.cms.event.v1.EventService/ListEvents?encoding=json&message=%7B%22pageSize%22%3A%2225%22%7D`

This URL is broken down as follows:

1. `https://cda.mottostreaming.com` -> This is the base URL of the API. Should look familiar, so far!
2. `motto.cda.cms.event.v1.EventService` -> This is the "package" and "service" of the API. It tells Motto servers which part of the API you are trying to access. You can find all available packages [here](https://buf.build/motto/cda).
3. `ListEvents` -> This is the "method" of the API. It tells the API which specific operation you are trying to perform. You can find all available methods on page linked in step (2), after selecting a package.
4. `?encoding=json&message=%7B%22pageSize%22%3A%2225%22%7D` -> This is the query string of the API. It tells the API which parameters you are trying to pass to the method. In this case, we are passing a JSON object with a `pageSize` of 25, since that's what this example endpoint requires. Please note that the JSON should always be *URL-encoded*, and should be included in the `message` parameter (you should not change the `encoding` parameter)!
   To know which parameters are needed for each method, you can click into a method's `Request`, e.g. for [list events](https://buf.build/motto/cda/docs/main:motto.cda.cms.event.v1#motto.cda.cms.event.v1.ListEventsRequest).

Putting this together, such a request would look like this using `curl`:

```bash theme={null}
curl -X GET 'https://cda.mottostreaming.com/motto.cda.cms.event.v1.EventService/ListEvents?encoding=json&message=%7B%22pageSize%22%3A%2225%22%7D' \
  -H 'Authorization: Bearer <PUBLIC_KEY>'
```

To understand more about the `Authorization` header, please see the [authentication](/reference/content-delivery-api/authentication) section.

You now know how to perform `GET` requests to the Content Delivery API. However, some operations require `POST` requests, which we will cover in the next section.

### POST requests

To understand how to use Motto's Content Delivery API using standard HTTP `POST` requests for write operations, please follow along with a basic example.

Let's say we want to obtain a Motto JWT for a user that has signed in using Userfront (a third party user management service).
From the above section, we know how to navigate to the necessary API endpoint, which in this case can be found [here](https://buf.build/motto/cda/docs/main:motto.cda.iam.auth.v1#motto.cda.iam.auth.v1.AuthService.ExchangeToken).

As we can see in the documentation for this endpoint, this is not marked with `NO_SIDE_EFFECTS`, which means it is not a cacheable request. Therefore, we need to use a `POST` request. Such a request would look like this using `curl`:

```bash theme={null}
curl -X POST 'https://cda.mottostreaming.com/motto.cda.iam.auth.v1.AuthService/ExchangeToken' \
  -H 'authorization: Bearer <PUBLIC_KEY>' \
  -H 'connect-protocol-version: 1' \
  -H 'content-type: application/json' \
  --data-raw '{"userfrontIdToken":"eyJhb....nEa-V8"}'
```

Note that now, as with normal REST `POST` requests, the parameters are no longer included in the URL, but in the body of the request. The body should always be a JSON object.

<Warning>Do not forget the `connect-protocol-version: 1` header, as this is required for all POST requests!</Warning>

If you still have questions about how to use the Content Delivery API, please do not hesitate to [contact us](mailto:info@mottostreaming.com).

## Full API documentation

For a full list of all available methods and services, please visit our [API documentation](https://buf.build/motto/cda/docs/main).

If you are unsure about how to use this API documentation, please follow the examples above.