Articles on: Getting Started

Getting started with the API

Quortex I/O comes with a fully documented API that allows you to fully automate the platform. The API relies on the same concept as the User Interface, making it very easy to integrate. Follow the guide!

API Keys in a nutshell


There are two types of API keys:

Organization API keys can be created by admin and allow to make any operation on the platform. They have to be used carefully as they give you a complete control on the platform
Pool API Keys pertain only to a pool and allow to make operations on this pool only.
Pool API keys have different access levels. Please refer to Managing API keys for more information

Different types of API


There are six distinct API that can be used:
The OTT API is the one used to create Quortex Play inputs, pools, processing, rules, etc. It contains streaming related routes.
The LINK API is the one used to create Quortex Link pools, sources, destinations, scheduling,...
The Analytics API gives you access input statistics, output metrics and usage metrics.
The User API is used to retrieve users in an organization, create access tokens, invite users, ...
The Billing API relates to payment methods, invoices, ...
The Upload API is used to upload images (for slate inputs or user profile)

All these APIs can only be used with an access token; please read below!

Generate your API key


In this example, we are going too use an Organization API key; the concept also applies to Pool API keys.

The first API key needs to be generated through the application web interface, in the "Organization" menu. Each API key is associated to an "api_secret", than is used to generate a token that is then passed as an authentication bearer to all subsequent API calls.



Make your first API calls


Once you copied the secret, it can be used to generate a token. Let's curl it!

We assume that the variable my_secret holds the API key secret that you've copied from the application.
curl -s -XPOST https://api.quortex.io/1.0/token/ -H 'Content-Type: application/json' -d "{\"api_key_secret\": \"$my_secret\"}" | jq .
{
  "access_token": "eyJhbG[...]0cg",
  "expires_at": "2021-10-13T14:43:20.978369Z"
}


We assume that the variable access_token holds the access token you've just retrieved.

The access token you are getting needs to be passed to any subsequent API calls. For instance, you want to list your organization members :

curl -s -XGET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" https://api.quortex.io/1.0/organization/members/ | jq .
{
  "count": 5,
  "results": [
    {
      "uuid": "user_1BfAiXqd",
      "name": "Marco Polo",
      "email": "marcopolo@quortex.io",
      "profile_picture_url": "https://storage.googleapis.com/quortex-saas-images-prod/f8ac26e5-1ee3-4013-8ea8-ccec1d4744d5/profile",
      "role": "admin",
      "member_since": null,
      "invitation": "accepted",
      "inviter": null,
      "pools": []
    },
    {
      "uuid": "user_9WtMSyTF",
      "name": "John James Rambo",
      "email": "jjr@quortex.io",
      "profile_picture_url": "https://storage.googleapis.com/quortex-saas-images-prod/ddd91fcc-866b-40ae-9112-1812ae3bcffc/profile",
      "role": "captain",
      "member_since": "2021-09-27",
      "invitation": "accepted",
      "inviter": {
        "uuid": "user_1BfAiXqd",
        "name": "Marco Polo"
      },
      "pools": []
    },
    {
      "uuid": "user_gbzDhmaB",
      "name": "Mr Bean",
      "email": "rowan@quortex.io",
      "profile_picture_url": "https://storage.googleapis.com/quortex-saas-images-prod/b57dff16-08e9-4077-9ccb-b8262eda8368/profile",
      "role": "user",
      "member_since": "2021-09-27",
      "invitation": "accepted",
      "inviter": {
        "uuid": "user_1BfAiXqd",
        "name": "Marco Polo"
      },
      "pools": []
    },
    {
      "uuid": "user_t5ECXtOW",
      "name": "The Fall Guy",
      "email": "colt@quortex.io",
      "profile_picture_url": "https://storage.googleapis.com/quortex-saas-images-prod/5eade481-233c-4eb8-980b-0b48a04aa391/profile",
      "role": "admin",
      "member_since": "2021-10-06",
      "invitation": "accepted",
      "inviter": {
        "uuid": "user_1BfAiXqd",
        "name": "Marco Polo"
      },
      "pools": []
    },
    {
      "uuid": "user_TnMBS84h",
      "name": "",
      "email": "johndoe@acme.inc",
      "profile_picture_url": null,
      "role": "user",
      "member_since": "2021-10-06",
      "invitation": "sent",
      "inviter": {
        "uuid": "user_t5ECXtOW",
        "name": "The Fall Guy"
      },
      "pools": []
    }
  ]
}


Please note that access tokens have an expiration date; you have to renew it periodically for security reasons.

Example 1: Create a pool



Pool creation is simply made by posting a configuration to this route

curl -s -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" -d '{"name": "My API Pool", "input_region": "france", "published": true, "streaming_countries": ["FRA"]}' https://api.quortex.io/1.0/pools/ | jq .
{
  "name": "My API Pool",
  "uuid": "pool_1eltuzev",
  "created_at": "2021-10-13T14:20:27.176396Z",
  "modified_at": "2021-10-13T14:20:27.176481Z",
  "domain": "1eltuzev",
  "input_region": "france",
  "published": true,
  "inputs": [],
  "processings": [],
  "targets": [],
  "rules": {
    "input": [],
    "processing": [],
    "target_hls": [],
    "target_dash": []
  },
  "streaming_countries": [
    "FRA"
  ],
  "status": {
    "pool_state": "Invalid",
    "publish_state": "publishing"
  }
}


One can see that the API answered with a uuid; this uuid is used for all subsequent calls on this pool.

Example 2: Create an input



Let's declare a SRT input using this route

curl -s -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" -d '{"name": "My API Input", "identifier": "my_api_input", "published": true, "enabled": true, "type": "srt", "srt": {"connection_type": "caller", "caller": {"address":"srt://1.2.3.4:5678", "passphrase":"willyoureadthis"}, "latency": 1.25}}' https://api.quortex.io/1.0/pools/pool_1eltuzev/inputs/ | jq .
{
  "name": "My API Input",
  "uuid": "inpu_nluA4ocz",
  "identifier": "my_api_input",
  "created_at": "2021-10-13T14:30:53.544728Z",
  "modified_at": "2021-10-13T14:30:53.544772Z",
  "published": true,
  "enabled": true,
  "type": "srt",
  "pool_uuid": "pool_1eltuzev",
  "srt": {
    "connection_type": "caller",
    "latency": 1.25,
    "caller": {
      "address": "srt://1.2.3.4:5678",
      "passphrase": "willyoureadthis",
      "our_ip": ""
    }
  },
  "status": {
    "thumbnail_url": "",
    "thumbnail_created_at": null,
    "state": "Configuring",
    "last_error": ""
  }
}

Updated on: 04/03/2024

Was this article helpful?

Share your feedback

Cancel

Thank you!