# Distributions

LingoHub CDN API · [all operations](https://developers.lingohub.com/reference/cdn.md)

Endpoints for distribution related operations.

The CDN API has one operation: an app asks whether a newer release of its translations is available and receives the link to download it. The API is served from `https://cdn.lingohub.com`.

The [iOS SDK](https://github.com/lingohub/ios-cdn-sdk) and the [Android SDK](https://github.com/lingohub/android-cdn-sdk) make this call for you.

## Authentication

Send a CDN key as a Bearer token:

```http
Authorization: Bearer lh-cdn_eyJhbGciOiJIUz...
```

A CDN key belongs to a project and starts with `lh-cdn_`. Copy it from the project's distribution in LingoHub. The API keys of API V1 and API V2 aren't accepted here.

## How a check works

1. LingoHub selects the distribution of the key's project that matches `distributionEnvironment` and `distributionType`. If you send `clientVersion`, it takes the distribution whose version range contains that version; otherwise, or if no range matches, it takes the fallback distribution. If no distribution matches, the answer is `404`.
2. LingoHub looks up the active release of that distribution. If there is none, the answer is `404`.
3. If `clientRelease` names the active release, the app is up to date and the answer is `204 No Content`. Otherwise the answer is `200` with the release and its download link.

So `204` means "nothing new", and `404` means "nothing to deliver".

## Request

| Field | Required | Meaning |
| --- | --- | --- |
| `distributionEnvironment` | Yes | `DEVELOPMENT`, `TEST`, `STAGING` or `PRODUCTION`. |
| `distributionType` | Yes | `NATIVE_FORMAT`, `MOBILE_SDK_ANDROID` or `MOBILE_SDK_IOS`. |
| `clientVersion` | No | Version of the app, for example `2.1.0`, with at most 50 characters. |
| `clientRelease` | No | The `distributionReleaseId` that the app received from its previous check. Omit it on the first check. |

```json
{
  "distributionEnvironment": "PRODUCTION",
  "distributionType": "MOBILE_SDK_ANDROID",
  "clientVersion": "2.1.0",
  "clientRelease": "rel_019f9d57-d0ec-7fa2-99f2-4ac2eb20e671"
}
```

## Response

A `200` response describes the release to download:

```json
{
  "distributionReleaseId": "rel_019f9d57-d0ec-7fa2-99f2-4ac2eb20e671",
  "name": "your project release",
  "createdAt": "2025-02-24T13:11:30.909+00:00",
  "filesUrl": "https://lingohub-exports.s3.amazonaws.com/distributions/rel_019f9d57-d0ec-7fa2-99f2-4ac2eb20e671.zip"
}
```

`filesUrl` is a pre-signed link to the files of the release, valid for 24 hours. Store `distributionReleaseId` and send it as `clientRelease` with the next check.

## Errors

An error body follows the problem details format. Its `errors` array holds one `CdnErrorDetail` per problem, with the area in `field` and the reasons in `infos`:

```json
{
  "type": "about:blank",
  "status": 401,
  "detail": "Unauthorized",
  "errors": [
    { "field": "AUTHORIZATION", "infos": ["CDN_KEY_NOT_FOUND"] }
  ]
}
```

| Status | `field` | `infos` | Meaning |
| --- | --- | --- | --- |
| `401` | `AUTHORIZATION` | `HEADER_INVALID` | The header isn't a Bearer token with the `lh-cdn_` prefix. |
| `401` | `AUTHORIZATION` | `JWT_INVALID` | The key can't be read. |
| `401` | `AUTHORIZATION` | `CDN_KEY_NOT_FOUND` | The key doesn't exist. |
| `401` | `AUTHORIZATION` | `CDN_KEY_EXPIRED` | The key was replaced or revoked. |
| `404` | `DISTRIBUTION` | `DISTRIBUTION_NOT_FOUND` | No distribution matches the environment, type and version. |
| `404` | `DISTRIBUTION_RELEASE` | `DISTRIBUTION_RELEASE_NOT_FOUND` | The distribution has no active release. |
| `422` | | | The body is invalid, for example `clientVersion` isn't a version number or is too long. |
| `429` | `USAGE` | `USAGE_LIMIT_EXCEEDED` | The CDN usage budget of the workspace is used up. |
| `500` | | | An unexpected error occurred. |

## Operations

- [`POST /v1/distributions/check`](https://developers.lingohub.com/reference/cdn/operations/cdncheck.md): Check status of a Distribution Release
