# API overview

The MK.IO cloud APIs are separated by product area and share request conventions. Once you know how paths are scoped, how list responses are shaped, and how long-running resources expose state, you can move between the APIs without learning a new set of conventions each time.

## One base URL

The Media, Live, Templates, and Management APIs use this base URL:

```text
https://app.mk.io
```

The resource path is what differs between them:

<table>
  <thead>
    <tr>
      <th style="text-align: left">API</th>
      <th style="text-align: left">Path prefix</th>
      <th style="text-align: left">Scope</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">Media API</td>
      <td style="text-align: left"><code>/api/v1/projects/{project_name}/media/</code></td>
      <td style="text-align: left">Project</td>
    </tr>
    <tr>
      <td style="text-align: left">Live API</td>
      <td style="text-align: left"><code>/api/v1/projects/{project_name}/live/</code></td>
      <td style="text-align: left">Project</td>
    </tr>
    <tr>
      <td style="text-align: left">Templates API</td>
      <td style="text-align: left"><code>/api/v1/projects/{project_name}/templating/</code></td>
      <td style="text-align: left">Project</td>
    </tr>
    <tr>
      <td style="text-align: left">Management API</td>
      <td style="text-align: left"><code>/api/v1/</code></td>
      <td style="text-align: left">Organization and project</td>
    </tr>
  </tbody>
</table>

When a path includes `/projects/{project_name}/`, the request is project-scoped. When it does not, it usually targets organization-level or user-level configuration through the Management API.

## Authentication is shared

The cloud APIs above use bearer authentication:

```http
Authorization: Bearer <YOUR_TOKEN>
```

A single token works across setup and operational workflows. The same token can create a project through the Management API and then list assets through the Media API, as long as the issuing user has access to both operations. See [Authentication](/mkio/api-guides/getting-started/authentication) for how to create one.

## Requests are HTTP plus JSON

The request shape follows a small set of rules:

- `GET` reads a resource or lists a collection.
- `PUT` creates or replaces a resource whose name is part of the URL.
- `PATCH` applies a partial update where the endpoint supports it.
- `POST` runs an action, such as `start`, `stop`, `allocate`, `scale`, `backup`, or `restore`.
- `DELETE` removes a resource.

Send `Content-Type: application/json` on any request that has a JSON body.

## List responses share a shape

A `list` endpoint returns the resources in `value` and metadata in `supplemental`:

- `value`: the array of resources on the current page.
- `supplemental`: counts and pagination metadata, including `supplemental.pagination` with `start`, `end`, `records`, and `total`.

Read `value` for the current page and check the endpoint's pagination contract for the next page. Media collections can return `@odata.nextLink`; follow that link when present. See [Pagination and filtering](/mkio/api-guides/understanding/pagination) for the query parameters and the paging mechanism.

## Many resources expose a lightweight state endpoint

Several resources expose a `/state` endpoint next to the main resource, including Media API assets, content key policies, jobs, live events, live outputs, streaming endpoints, and streaming locators. These endpoints let you monitor a long-running resource without retrieving the full object each time. See [Resource states](/mkio/api-guides/understanding/resource-states).

## Long-running workflows are common

Several important workflows are not single calls:

- A **job** moves from queued work, through processing, to a terminal state.
- A **Media API live event** is created, then started, then paired with one or more live outputs.
- A **Live API resource** references sources, an asset, and template configs. Set `spec.state` to request `Running` or `Stopped`, then monitor `status.state` until the transition completes.
- A **streaming endpoint** is created and started before playback works.

Designing around these workflows means combining list or get operations with either polling on `/state` or subscribing to [webhooks](/mkio/api-guides/understanding/webhooks).

## Where to go next

- [Authentication](/mkio/api-guides/getting-started/authentication): create a token and make your first call.
- [Error handling](/mkio/api-guides/understanding/error-handling): the shared error body and status codes.
- [Pagination and filtering](/mkio/api-guides/understanding/pagination): page and narrow list responses.
- [Resource states](/mkio/api-guides/understanding/resource-states): read lifecycle state and design around it.