# API overview

The MK.IO APIs are separated by product area, but they share one operating model. 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

All MK.IO APIs share the same base URL:

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

The resource path is what differs between them:

| API                | Path prefix                              | Scope                    |
| :----------------- | :--------------------------------------- | :----------------------- |
| Media API          | `/api/v1/projects/{project_name}/media/` | Project                  |
| Management API     | `/api/v1/`                               | Organization and project |
| Fleets API         | `/api/v1/projects/{project_name}/fleet/` | Project                  |
| Infrastructure API | `/api/v1/projects/{project_name}/infra/` | Project                  |

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 APIs 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.

## 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`.

That shared shape gives you one client pattern for every collection: read `value`, then use `supplemental.pagination` to decide whether to request the next page.

## Many resources expose a lightweight state endpoint

Several resources expose a `/state` endpoint next to the main resource, including 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.

## 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 **live event** is created, then started, then paired with one or more live outputs.
- 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.