Content Delivery API

How to authenticate

All content delivery API methods, except /v1/access_token, require a bearer-type Authorization header containing an access token. To acquire an access token you should call /v1/access_token API method described below.

Passing Authorization header with cURL:

curl -X $HTTP_METHOD -H "Authorization: Bearer $ACCESS_TOKEN" https://api-cdn.qencode.com/v1/$OBJECT

All requests must be made over HTTPS.

Getting Access Token

POST

/v1/access_token/<api_key>

Qencode requires API keys to generate access tokens that are used to authenticate all of your live stream requests. To get an access_token, you must provide your API key in the authorization header of the request.

You can view and manage the API keys associated with your projects inside of your Qencode Account.

Access token is valid for 24 hours.

Caution

To build a secure solution we strongly recommend that you DO NOT call this method directly from any client application as you will expose your api key publicly. We recommend you first obtain an access token from your server and then pass to the client app.

For live-streaming, an API key is assigned to each Project created in your Qencode account. After logging into your account, you can manage your API keys on the Live Streaming Projects page, as well as track the usage of each Project on the Statistics page.

After API key authentication is complete, you will receive this session based token, which can be used to call all other live streaming API methods.

curl -X POST https://api-live.qencode.com/v1/access_token/your_api_key

{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyjpYXQiOjE2MjgxNTgyNJMsInN1YiI6MTMwLCJleHAiOjE2MjgyNDQ2NjN9.SxS3zLx2CZbZ9ylTpd25kj9el6_4TqqTWUA9RT2iJ9I"
}

Creating a Playback Domain

POST

/v1/domains

You can create custom domains and use them for live-streaming or media storage playback.

A custom domain can either be used for live-streaming or media-storage, so you'll need to create separate domains for live-streaming and media storage playback in case you need to support both.

You won't be able to update a live domain after it's created. For VOD domains, you can update attributes such as bucket_name. If you need to change other properties or for live domains, delete the existing domain and create a new one.

You can create up to 20 custom domains for playback. In case this does not cover your use case you can contact our support.

Input Objects Structure

Specify a fully qualified domain name (FQDN) for your domain. For example, live.mydomain.com.

Specify the type of domain you are creating. Possible values: live or vod.

Required for domains of vod type. Specify the name of the bucket in your Qencode media storage you want to expose with the domain name.

Output Objects Structure

The domain object contains all the attributes of your playback domain: id, type, domain name and creation date and time.

There are two types of domains: live and vod. Live domains are used for live-streaming and vod domains are used for media storage playback.

Specify a fully qualified domain name (FQDN) for your domain. For example, live.mydomain.com.

curl -X POST 'https://api-cdn.qencode.com/v1/domains' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN' \ 
-H 'Content-Type: application/json' \ 
--data-raw '{"name": "live.mydomain.com", "type": "live"}'

{
  "domain": {
    "created": "2023-06-07 14:17:25",
    "id": "aeac03d6-beb0-4638-a094-fbc35653f931",
    "type": "live",
    "domain_name": "live.mydomain.com"
  }
}

Getting a Playback Domain Data

GET

/v1/domains/<domain_id>

Gets a playback domain information.

Output Objects Structure

The domain object contains all the attributes of your playback domain: id, type, domain name, bucket name and creation date and time.

There are two types of domains: live and vod. Live domains are used for live-streaming and vod domains are used for media storage playback.

Specify a fully qualified domain name (FQDN) for your domain. For example, live.mydomain.com.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-cdn.qencode.com/v1/domains/$DOMAIN_ID

{
  "domain": {
    "created": "2023-06-07 14:17:25",
    "id": "aeac03d6-beb0-4638-a094-fbc35653f931",
    "type": "live",
    "domain_name": "live.mydomain.com"
  }
}

Listing Playback Domains

GET

/v1/domains

Gets a list of user domains.

In case no filter specified, contains list of all user domains.

You can optionally pass the domain type in the last URL segment. E.g. `GET /v1/domains/live` will return the list of live-streaming domains.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-cdn.qencode.com/v1/domains

{
  "domains": [
    {
      "created": "2023-06-07 14:17:25",
      "id": "aeac03d6-beb0-4638-a094-fbc35653f931",
      "type": "live",
      "domain_name": "live.mydomain.com"
    }
  ]
}

Updating a Playback Domain

PUT

/v1/domains/<domain_id>

You can update a playback domain, but only for domains associated with a Qencode storage bucket. This method is used to update the attributes of an existing domain used for media-storage playback. Live-streaming domains cannot be updated via this endpoint.

Input Objects Structure

Required for domains of vod type. Specify the name of the bucket in your Qencode media storage you want to expose with the domain name.

Output Objects Structure

The domain object contains all the attributes of your playback domain: id, type, domain name, bucket name and creation date and time.

There are two types of domains: live and vod. Live domains are used for live-streaming and vod domains are used for media storage playback.

Specify a fully qualified domain name (FQDN) for your domain. For example, live.mydomain.com.

curl -X PUT 'https://api-cdn.qencode.com/v1/domains/$DOMAIN_ID' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN' \ 
-H 'Content-Type: application/json' \ 
--data-raw '{"bucket_name": "new-bucket-name"}'

{
  "domain": {
    "bucket_name": "new-bucket-name",
    "created": "2023-06-07 14:17:25",
    "id": "aeac03d6-beb0-4638-a094-fbc35653f931",
    "type": "vod",
    "domain_name": "vod.mydomain.com"
  }
}

Deleting a Playback Domain

DELETE

/v1/domains/<domain_id>

Deletes a playback domain.

Status is 'ok' in case domain was successfully deleted or 'failed' in case there was an error.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X DELETE https://api-cdn.qencode.com/v1/domains/$DOMAIN_ID

{
  "status": "ok"
}

Creating a TLS Subscription

POST

/v1/tls/subscriptions

You can create automatically managed TLS subscriptions for custom domains and use them for live-streaming or media storage playback.

TLS subscription is a Let's Encrypt TLS certificate automatically issued and renewed for a playback domain.

Use this as a quick and easy way to setup TLS/HTTPS for your domain.

TLS subscription is a quick and easy way to setup TLS for your custom playback domain.

Input Objects Structure

Specify an ID of the existing Playback domain. You should create a Playback domain before creating a TLS subscription for it.

Output Objects Structure

The TLS subscription object contains all the attributes of your TLS subscription: id, domain ID, status, instructions for domain ownership verification and creation date and time.

The status can be one of the following: pending, processing, issued, renewing, failed.

You should follow the instructions provided to verify your TLS subscription.

curl -X POST 'https://api-cdn.qencode.com/v1/tls/subscriptions' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN' \ 
-H 'Content-Type: application/json' \ 
--data-raw '{"domain_id": "aeac03d6-beb0-4638-a094-fbc35653f931"}'

{
  "tls_subscription": {
    "status": "pending",
    "created": "2023-06-12 15:10:48",
    "domain_id": "aeac03d6-beb0-4638-a094-fbc35653f931",
    "message": "TLS subscription created. You should verify your domain ownership. Create a CNAME for 'live.mydomain.com' and point it to 'j.sni.global.fastly.net.'.",
    "id": "7d819560-6220-4b76-bf9a-3784a64ac7ff"
  }
}

Getting a TLS subscription Data

GET

/v1/tls/subscriptions/<tls_subscription_id>

Gets a TLS subscription information.

Output Objects Structure

The TLS subscription object contains all the attributes of your TLS subscription: id, domain ID, status, instructions for domain ownership verification and creation date and time.

The status can be one of the following: pending, processing, issued, renewing, failed.

You should follow the instructions provided to verify your TLS subscription.

 Request Example 
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-cdn.qencode.com/v1/tls/subscriptions/$TLS_SUBSCRIPTION_ID

{
  "tls_subscription": {
    "status": "pending",
    "created": "2023-06-12 15:10:48",
    "domain_id": "aeac03d6-beb0-4638-a094-fbc35653f931",
    "id": "7d819560-6220-4b76-bf9a-3784a64ac7ff"
  }
}

Listing TLS subscriptions

GET

/v1/tls/subscriptions

Gets a list of user TLS subscriptions.

In case no filter specified, contains list of all user TLS subscriptions.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-cdn.qencode.com/v1/tls/subscriptions

{
  "tls_subscriptions": [
      {
          "status": "pending",
          "created": "2023-06-12 15:10:48",
          "id": "7d819560-6220-4b76-bf9a-3784a64ac7ff",
          "domain_id": "aeac03d6-beb0-4638-a094-fbc35653f931"
      }
  ]
}

Deleting a TLS subscription

DELETE

/v1/tls/subscriptions/<tls_subscription_id>

Deletes a TLS subscription.

Status is 'ok' in case TLS subscription was successfully deleted or 'failed' in case there was an error.

 Request Example 
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X DELETE https://api-cdn.qencode.com/v1/tls/subscriptions/$TLS_SUBSCRIPTION_ID

{
  "status": "ok"
}

Creating a Signing key

POST

/v1/signing-keys

You can create signing keys and use them for live-streaming or media storage playback authentication.

A signing key can either be used for a Live stream, a Live stream Playback domain or a Media storage bucket.

You won't be able to get the private key data using the /v1/signing-keys after the signing key created.

You should save private key data you get from the response of /v1/signing-keys and store it in a secure place.

Input Objects Structure

Specify an existing Playback domain ID in case you want using the signing key to authenticate playback for Live streams sharing the same custom Playback domain.

Specify an existing Live stream ID in case you want using the signing key to authenticate playback for a Live stream that does not have a custom Playback domain.

Specify an existing Media storage bucket name in case you want to use the signing key to authenticate an access to a media storage bucket.

You can specify a name for a signing key for the ease of identification.

Output Objects Structure

The signing key object contains all the attributes of your signing key: id, domain_id or stream_id or bucket_name, private key and creation date and time.

This field is returned in case you specified a Playback domain ID when creating the signing key.

This field is returned in case you specified a Live stream ID when creating the signing key.

This field is returned in case you specified a Media storage bucket name when creating the signing key.

Private key data is only returned in the response of the /v1/signing-keys method. You won't be able to get the private key data using the /v1/signing-keys after the signing key created. You should save private key data you get from the response of /v1/signing-keys and store it in a secure place.

curl -X POST 'https://api-cdn.qencode.com/v1/signing-keys' \ 
-H 'Authorization: Bearer $ACCESS_TOKEN' \ 
-H 'Content-Type: application/json' \ 
--data-raw '{"stream_id": "1f1ab6a3-d867-4787-b882-7f2fb1203634"}'

{
  "signing_key": {
      "stream_id": "1f1ab6a3-d867-4787-b882-7f2fb1203634",
      "private_key": "-----BEGIN RSA PRIVATE KEY-----
MIIJKgIBAAKCAgEA4DAKSi4F8yQTt1L4N9s9Wt+3hBoHt5KMs14jy37YNnqxaIzJ
...
1c4v1P/wPr2sqepof19dbacmGcxplhHJ4d3BXAdInxYuGrgerShJXy5icFWf8A==
-----END RSA PRIVATE KEY-----
",
      "created": "2023-06-12 15:00:40",
      "id": "ec25a6a6-b31e-4ac9-af01-711460421c6b",
      "name": null
      }
}

Getting a Signing key data

GET

/v1/signing-keys/<signing_key_id>

Gets a signing key information.

Output Objects Structure

The signing key object contains all the attributes of your signing key: id, domain_id or stream_id or bucket_name, private key and creation date and time.

This field is returned in case you specified a Playback domain ID when creating the signing key.

This field is returned in case you specified a Live stream ID when creating the signing key.

This field is returned in case you specified a Media storage bucket name when creating the signing key.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-cdn.qencode.com/v1/signing-keys/$SIGNING_KEY_ID

{
  "signing_key": {
      "stream_id": "1f1ab6a3-d867-4787-b882-7f2fb1203634",
      "created": "2023-06-12 15:00:40",
      "name": "My Signing Key",
      "id": "ec25a6a6-b31e-4ac9-af01-711460421c6b"
  }
}

Listing Signing keys

GET

/v1/signing-keys

Gets a list of user signing keys.

In case no filter specified, contains list of all user signing keys.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-cdn.qencode.com/v1/signing-keys

{
  "signing_keys": [
      {
          "created": "2023-06-07 14:17:25",
          "id": "e52f59d7-e65c-4036-81c6-0163403a1a88",
          "domain_id": "aeac03d6-beb0-4638-a094-fbc35653f931"
      },
      {
          "stream_id": "1f1ab6a3-d867-4787-b882-7f2fb1203634",
          "created": "2023-06-12 15:00:40",
          "id": "ec25a6a6-b31e-4ac9-af01-711460421c6b",
      "name": null
      }
  ]
}

Updating a Signing key

PUT

/v1/signing-keys/<signing_key_id>

Updates the signing key name.

Input Objects Structure

Specify a name for the signing key for the ease of identification.

Output Objects Structure

The signing key object contains all the attributes of your signing key: id, domain_id or stream_id or bucket_name, private key and creation date and time.

This field is returned in case you specified a Playback domain ID when creating the signing key.

This field is returned in case you specified a Live stream ID when creating the signing key.

This field is returned in case you specified a Media storage bucket name when creating the signing key.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X PUT https://api-cdn.qencode.com/v1/signing-keys/$SIGNING_KEY_ID  \ 
-H 'Content-Type: application/json' \ 
--data-raw '{"name": "My signing key"}'

{
  "signing_key": {
      "stream_id": "1f1ab6a3-d867-4787-b882-7f2fb1203634",
      "created": "2023-06-12 15:00:40",
      "id": "ec25a6a6-b31e-4ac9-af01-711460421c6b",
      "name": "My signing key"
      }
}

Deleting a Signing key

DELETE

/v1/signing-keys/<signing_key_id>

Deletes a signing key.

Status is 'ok' in case signing key was successfully deleted or 'failed' in case there was an error.

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X DELETE https://api-cdn.qencode.com/v1/signing-keys/$SIGNING_KEY_ID

{
  "status": "ok"
}

Setting a media storage bucket access policy

PUT

/v1/buckets/<bucket_name>/policy/<policy_name>

Sets bucket access policy.

Policy name can either be 'public' or 'authenticated'. Buckets are set to public access policy by default.

In case authenticated policy is set for a bucket all content inside the bucket can be accessed with a signed token passed in the URL.

See Signed tokens for more information.

Status is 'ok' in case the bucket policy was successfully updated or 'failed' in case there was an error.

 Request Example 
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X PUT https://api-cdn.qencode.com/v1/buckets/$BUCKET_NAME/policy/$POLICY_NAME

{
  "status": "ok"
}

Setting a media storage bucket CORS policy

POST

/v1/buckets/<bucket_name>/cors

Sets bucket CORS policy.

Accepts an object where attribute names are CORS headers and values a corresponding CORS header values

Supported CORS headers are listed below

Status is 'ok' in case the bucket CORS policy was successfully updated or 'failed' in case there was an error.

Input Objects Structure

Specify * or a particular origin as a value, for example https://mydomain.com

Please note, in case you specify true as a value for this header, you should also specify a particular origin for the Access-Control-Allow-Origin header

Supported methods are GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH

Indicates how long the results of a preflight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.

 Request Example 
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X POST https://api-cdn.qencode.com/v1/buckets/$BUCKET_NAME/cors -H 'Content-Type: application/json' --data '{"Access-Control-Allow-Origin": "*"}'

{
  "status": "ok"
}

Getting a media storage bucket CORS policy

GET

/v1/buckets/<bucket_name>/cors

Gets bucket CORS policy.

Specifies the domain allowed to access resources from the bucket

Indicates whether the browser should include credentials, like cookies, when making requests to the bucket

Lists the HTTP methods permitted when accessing the bucket. Supported methods are GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH

Defines the duration (in seconds) for which the browser can cache the CORS response

 Request Example 
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X GET https://api-cdn.qencode.com/v1/buckets/$BUCKET_NAME/cors

{
  "Access-Control-Allow-Origin": "https://media-storage.us-west.qencode.com",
  "Access-Control-Allow-Methods": "GET, PUT, POST, DELETE",
  "Access-Control-Max-Age": "1600",
  "Access-Control-Allow-Credentials": "true"
}

Deleting a media storage bucket CORS policy

DELETE

/v1/buckets/<bucket_name>/cors

Deletes bucket CORS policy.

Status is 'ok' in case the bucket CORS policy was successfully deleted or 'failed' in case there was an error.

 Request Example 
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X DELETE https://api-cdn.qencode.com/v1/buckets/$BUCKET_NAME/cors

{
  "status": "ok"
}

Deleting a media storage bucket CORS header

DELETE

/v1/buckets/<bucket_name>/cors/<header_name>

Removes a header from the bucket CORS policy.

Status is 'ok' in case the bucket CORS header was successfully deleted or 'failed' in case there was an error.

 Request Example 
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X DELETE https://api-cdn.qencode.com/v1/buckets/$BUCKET_NAME/cors/Access-Control-Allow-Origin

{
  "status": "ok"
}

Purging CDN cache for a bucket

POST

/v1/buckets/<bucket_name>/cache/purge_all

Purges CDN cache for all objects in a bucket.

Status is 'ok' in case cache for all objects in the bucket was successfully purged or 'failed' in case there was an error.

 Request Example 
curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 -X POST https://api-cdn.qencode.com/v1/buckets/my-bucket/cache/purge_all

{
  "status": "ok"
}

Purging CDN cache for an object in a bucket

POST

/v1/buckets/<bucket_name>/cache/purge

Purges CDN cache for a single object in a bucket.

Status is 'ok' in case cache for the object in the bucket was successfully purged or 'failed' in case there was an error.

Input Objects Structure

curl -H "Authorization: Bearer $ACCESS_TOKEN" 
 --location "https://api-cdn.qencode.com/v1/buckets/my-bucket/cache/purge" -H 'Content-Type: application/json' 
 --data '{"path": "path/to/object"}'

{
  "status": "ok"
}