API overview

The MK.IO cloud APIs are separated by product area and share request conventions. The device-local Beam Channels API has its own connection requirements. 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, Management, Fleets, and Infrastructure APIs use this base URL:

https://app.mk.io

The resource path is what differs between them:

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. The Channels API is served by a Beam device under /ui/connectors/channels-api/latest. Use its guide for the device URL and connection requirements.

Authentication is shared

The cloud APIs above use bearer authentication:

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

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.

Where to go next

• Authentication: create a token and make your first call.

• Error handling: the shared error body and status codes.

• Pagination and filtering: page and narrow list responses.

• Resource states: read lifecycle state and design around it.