Skip to content

CDN API · Distributions

Check for a new Distribution Release

POST
/v1/distributions/check
curl --request POST \
--url https://cdn.lingohub.com/v1/distributions/check \
--header 'Authorization: Bearer lh-cdn_eyJhbGciOiJIUz...' \
--header 'Content-Type: application/json' \
--data '{
"clientVersion": "2.1.0",
"clientRelease": "rel_019f9d57-d0ec-7fa2-99f2-4ac2eb20e671",
"distributionEnvironment": "DEVELOPMENT",
"distributionType": "NATIVE_FORMAT"
}'

Checks whether the app should download the active release of its distribution. Send the distributionReleaseId of the release the app already has as clientRelease: the check answers 204 while that release is still the active one, and 200 with the active release otherwise, including on the first check, without clientRelease. distributionEnvironment, distributionType and clientVersion select the distribution. Requires a CDN key as a Bearer token in the Authorization header.

Media typeapplication/json

Request body for checking for a new Distribution Release. The distribution environment and type are required and, with the optional client version, select the distribution. The client release names the release the app already has.

object
clientVersion

The version of the app. Selects the distribution whose version range contains it; without it, or when no range contains it, the fallback distribution is used.

string | null
0 <= 50 characters

Example

2.1.0
clientRelease

The distributionReleaseId of the release the app already has, from the response of its previous check. The check answers 204 while it is still the active release. Omit it on the first check.

string | null
0 <= 50 characters

Example

rel_019f9d57-d0ec-7fa2-99f2-4ac2eb20e671
distributionEnvironment
required

The target distribution environment. This is a mandatory filter.

string
Allowed values: DEVELOPMENT TEST STAGING PRODUCTION

Example

PRODUCTION
distributionType
required

The target distribution type. This is a mandatory filter.

string
Allowed values: NATIVE_FORMAT MOBILE_SDK_ANDROID MOBILE_SDK_IOS

Example

MOBILE_SDK_IOS

The active release is not the one named in clientRelease, or clientRelease was not sent. Download it from filesUrl and send its distributionReleaseId as clientRelease on the next check.

Media typeapplication/json

Response containing details of a matching Distribution Release, including its identifier, name, creation timestamp, and a pre-signed download URL.

object
distributionReleaseId
required

The unique identifier of the Distribution Release.

string
name
required

The human-readable name of the Distribution Release.

string
createdAt
required

The timestamp when the Distribution Release was created.

string format: date-time
filesUrl
required

A pre-signed S3 URL to download the Distribution Release files. Valid for 24 hours.

string

Examples

ExampleNew release

The active release, which the app does not have yet

New release

{
"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"
}

The release named in clientRelease is still the active one: the app is up to date. The response has no body.

The request body is not a JSON object, distributionEnvironment or distributionType is missing or not one of their values, or clientVersion or clientRelease is not a string of at most 50 characters.

Media typeapplication/json

An error in the problem detail format of RFC 9457. errors names the area and the cause.

object
type
required
string
status
required

The HTTP status code.

integer format: int32
detail
required

The reason phrase of the status.

string
errors
required

The area and the cause of the error. Empty for an invalid request body and for server errors.

Array<object>

A structured error detail indicating which field caused the error and the specific error codes.

object
field
required

The field or area that caused the error.

string
Allowed values: AUTHORIZATION DISTRIBUTION DISTRIBUTION_RELEASE USAGE
infos
required

The list of error codes describing what went wrong for this field.

Array<string>
Allowed values: HEADER_INVALID JWT_INVALID CDN_KEY_NOT_FOUND CDN_KEY_EXPIRED DISTRIBUTION_NOT_FOUND DISTRIBUTION_RELEASE_NOT_FOUND USAGE_LIMIT_EXCEEDED

Example

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

The Authorization header is missing or malformed, or the CDN key is invalid, deleted, rotated or revoked. errors names the cause.

Media typeapplication/json

An error in the problem detail format of RFC 9457. errors names the area and the cause.

object
type
required
string
status
required

The HTTP status code.

integer format: int32
detail
required

The reason phrase of the status.

string
errors
required

The area and the cause of the error. Empty for an invalid request body and for server errors.

Array<object>

A structured error detail indicating which field caused the error and the specific error codes.

object
field
required

The field or area that caused the error.

string
Allowed values: AUTHORIZATION DISTRIBUTION DISTRIBUTION_RELEASE USAGE
infos
required

The list of error codes describing what went wrong for this field.

Array<string>
Allowed values: HEADER_INVALID JWT_INVALID CDN_KEY_NOT_FOUND CDN_KEY_EXPIRED DISTRIBUTION_NOT_FOUND DISTRIBUTION_RELEASE_NOT_FOUND USAGE_LIMIT_EXCEEDED

Examples

ExampleUnknown CDN key

The CDN key does not exist

Unknown CDN key

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

No distribution matches: the project of the CDN key has no distribution for distributionEnvironment and distributionType whose version range contains clientVersion, and no fallback distribution for them. Also answered when the matching distribution has no active release.

Media typeapplication/json

An error in the problem detail format of RFC 9457. errors names the area and the cause.

object
type
required
string
status
required

The HTTP status code.

integer format: int32
detail
required

The reason phrase of the status.

string
errors
required

The area and the cause of the error. Empty for an invalid request body and for server errors.

Array<object>

A structured error detail indicating which field caused the error and the specific error codes.

object
field
required

The field or area that caused the error.

string
Allowed values: AUTHORIZATION DISTRIBUTION DISTRIBUTION_RELEASE USAGE
infos
required

The list of error codes describing what went wrong for this field.

Array<string>
Allowed values: HEADER_INVALID JWT_INVALID CDN_KEY_NOT_FOUND CDN_KEY_EXPIRED DISTRIBUTION_NOT_FOUND DISTRIBUTION_RELEASE_NOT_FOUND USAGE_LIMIT_EXCEEDED

Examples

ExampleDistribution not found

No matching distribution exists

Distribution not found

{
"type": "about:blank",
"status": 404,
"detail": "Not Found",
"errors": [
{
"field": "DISTRIBUTION",
"infos": [
"DISTRIBUTION_NOT_FOUND"
]
}
]
}

The workspace has used up its CDN budget. Checks are answered again once more budget is available; wait the number of seconds in the Retry-After header.

Media typeapplication/json

An error in the problem detail format of RFC 9457. errors names the area and the cause.

object
type
required
string
status
required

The HTTP status code.

integer format: int32
detail
required

The reason phrase of the status.

string
errors
required

The area and the cause of the error. Empty for an invalid request body and for server errors.

Array<object>

A structured error detail indicating which field caused the error and the specific error codes.

object
field
required

The field or area that caused the error.

string
Allowed values: AUTHORIZATION DISTRIBUTION DISTRIBUTION_RELEASE USAGE
infos
required

The list of error codes describing what went wrong for this field.

Array<string>
Allowed values: HEADER_INVALID JWT_INVALID CDN_KEY_NOT_FOUND CDN_KEY_EXPIRED DISTRIBUTION_NOT_FOUND DISTRIBUTION_RELEASE_NOT_FOUND USAGE_LIMIT_EXCEEDED

Examples

ExampleUsage limit exceeded

CDN budget exhausted

Usage limit exceeded

{
"type": "about:blank",
"status": 429,
"detail": "Too Many Requests",
"errors": [
{
"field": "USAGE",
"infos": [
"USAGE_LIMIT_EXCEEDED"
]
}
]
}
Retry-After
integer

Seconds to wait before checking again.

An unexpected error occurred. Retry after the number of seconds in the Retry-After header.

Media typeapplication/json

An error in the problem detail format of RFC 9457. errors names the area and the cause.

object
type
required
string
status
required

The HTTP status code.

integer format: int32
detail
required

The reason phrase of the status.

string
errors
required

The area and the cause of the error. Empty for an invalid request body and for server errors.

Array<object>

A structured error detail indicating which field caused the error and the specific error codes.

object
field
required

The field or area that caused the error.

string
Allowed values: AUTHORIZATION DISTRIBUTION DISTRIBUTION_RELEASE USAGE
infos
required

The list of error codes describing what went wrong for this field.

Array<string>
Allowed values: HEADER_INVALID JWT_INVALID CDN_KEY_NOT_FOUND CDN_KEY_EXPIRED DISTRIBUTION_NOT_FOUND DISTRIBUTION_RELEASE_NOT_FOUND USAGE_LIMIT_EXCEEDED

Example

{
"type": "about:blank",
"status": 401,
"detail": "Unauthorized",
"errors": [
{
"field": "AUTHORIZATION",
"infos": [
"HEADER_INVALID"
]
}
]
}
Retry-After
integer

Seconds to wait before retrying.

The CDN is temporarily unavailable. Retry after the number of seconds in the Retry-After header.

Media typeapplication/json

An error in the problem detail format of RFC 9457. errors names the area and the cause.

object
type
required
string
status
required

The HTTP status code.

integer format: int32
detail
required

The reason phrase of the status.

string
errors
required

The area and the cause of the error. Empty for an invalid request body and for server errors.

Array<object>

A structured error detail indicating which field caused the error and the specific error codes.

object
field
required

The field or area that caused the error.

string
Allowed values: AUTHORIZATION DISTRIBUTION DISTRIBUTION_RELEASE USAGE
infos
required

The list of error codes describing what went wrong for this field.

Array<string>
Allowed values: HEADER_INVALID JWT_INVALID CDN_KEY_NOT_FOUND CDN_KEY_EXPIRED DISTRIBUTION_NOT_FOUND DISTRIBUTION_RELEASE_NOT_FOUND USAGE_LIMIT_EXCEEDED

Example

{
"type": "about:blank",
"status": 401,
"detail": "Unauthorized",
"errors": [
{
"field": "AUTHORIZATION",
"infos": [
"HEADER_INVALID"
]
}
]
}
Retry-After
integer

Seconds to wait before retrying.