The super.AI API provides programmatic access to super.AI functionality and data. It’s an alternative to the super.AI dashboard that is particularly useful for hooking up our services to your own systems.

What is an API?

An API is a framework for two systems to communicate. The systems might speak different languages, but the API is the go-between that allows them to share meaningful information. They are request-and-response services, with a client issuing a request via the API and a server responding with relevant information back through the API.

APIs are in common use throughout the modern web. For example, flight search engines such as Skyscanner or Google Flights pull flight information from a variety of sources, and use APIs to access and display this information.

Why use an API?

Using an API allows for increased automation of your work. For example, you can write Python scripts to run operations at scale that might otherwise need to be done manually one-by-one through a dashboard. It also allows direct integration of our service with your own infrastructure. You can pull data in bulk directly from our servers and process it however you like on your side.

What is a REST API?

REST (Representational State Transfer) is a style of API architecture. The term is used loosely today, but for now we can take it very generally to mean an API that allows for JSON requests and responses, uses HTML as its protocol, and focuses on things called resources that are accessed and manipulated through different URLs in combination with a variety of HTTP methods (all of which you will learn about below).

📘

Give it a REST

REST APIs, as we’re going to use the term, very rarely follow the original guidelines of what a REST API is and how it should behave, but the term has come to mean the type of API that we offer at super.AI. If you’re curious, you can give this a read: REST isn’t what you think it is, and that’s OK.

Introduction to cURL

All the examples on this page are going to use cURL. We’ve done this because it’s the closest to what you might be familiar with using the web, and it is the easiest way to introduce the concepts behind a REST API.

📘

API reference

Once you’re familiar with what an API is and how to use one, you can explore our API reference, which documents all our available endpoints alongside code samples for cURL, Python, and our CLI.

You can use cURL via your computer’s command line. Open your terminal (on Mac, press cmd + space, then type in terminal and press enter; on Windows, press either ctrl or the windows key + r, then type cmd and press enter). In the terminal, type curl -V and press enter. You should see a response that includes the version of cURL you currently have installed. If not, you need to install cURL. Another way to test is to type curl https://super.ai in your terminal and see if it returns the raw code for the super.AI homepage.

You use flags to pass different kinds of information through cURL. We will introduce the essential flags in the example requests below. Flags take the form of a letter preceded by a dash, such as -X, -H, and -d.

When you send a multiple-line request through cURL, the end of each line—except the last line— requires a backslash (\), so that the request is read and processed as a single request. For example:

curl "https://api.super.ai/v1/jobs/{job_id}/cancel" \
-X POST \
-H "API-KEY: {api_key}"

The components of a REST API

These are the key components that you will need to use to interact with a REST API:

• Authentication method
• HTTP methods
• Objects and endpoints
• Parameters
• Response body

Authentication method

You can authenticate requests using your API key. For security, authentication is required to interact with our API in any way. You can find your account’s API keys in super.AI dashboard by heading to the profile icon at the bottom left and hitting API keys.

To make an authenticated request to the API using your API key, you’ll pass super.AI your API key through the request header using the -H flag. Here’s an example request to retrieve a project’s jobs that includes authentication:

curl "https://api.super.ai/v1/apps/{app_id}/jobs" \
-H "API-KEY: {api_key}"

You will need to replace {app_id} with a real project ID and {api_key} with a real API key for this request to work.

User permissions

The actions you can perform depend on your user role in the relevant project. For a list of the available actions associated with each user role, see our User permissions page.

HTTP methods

The super.AI API lets you take action using the following standard HTTP methods:

• POST
  • Create a new object. This is used to create jobs, submit ground truth data, and upload data to storage. Sometimes also used to act on a resource (e.g., you use a POST request to cancel and resubmit jobs).
• GET
  • Retrieve an object. No changes are made to the data itself; you only receive a copy of it as it exists on our servers.
• PATCH
  • Update an object. You only need to provide the exact data that you want to change. This can be used, e.g., to change the output of a piece of ground truth data.
• PUT
  • Update an object. Same as a PATCH request, except you need to provide the object you want to change in its entirety, including parts that remain unchanged.
• DELETE
  • Remove an object from our servers

Objects and endpoints

Objects (sometimes called resources) are the data that your API requests return and the data that you can use the API to alter or delete.

Objects are accessed via endpoints, which are the URL for that object. Endpoints are usually grouped thematically. For example, all objects related to job batches in the super.AI API are found under the /v1/apps/{app_id}/batches/ endpoint.

There are exceptions. Sometimes it is possible to access the same object through more than one endpoint, or more than one endpoint might be required to access all information related to, e.g., ground truth data.

An object comes in JSON format. When you submit a job, you create a job object, which you can retrieve at any time. If you submit more than one job, you also create a job batch object. When you upload data to storage or submit ground truth data, you likewise create a data object and a ground truth object.

Let’s say you want to retrieve a job batch object.

This the base URL of the super.AI API:

https://api.super.ai

Appended to the base URL is the relevant endpoint:

/v1/apps/{app_id}/jobs

So the complete URL for a request to this object would look like this:

https://api.super.ai/v1/apps/{app_id}/jobs

Replacing the variable {app_id} and making this into a cURL request gives us this:

curl "https://api.super.ai/v1/apps/123abc45-6789-01de-f2g3-45h67ijk8901/jobs" \
-H "API-KEY: live_1Ab23cdEFGH4iJ5K67Lmnop8qR10STulWX_2y3Za4_B"

This request contains dummy values for the app_id and api_key. You will need to replace the variables with actual values from your super.AI account if you want this request to work.

📘

GET is the default

GET requests are the default HTTP method, so you don’t have to specify the request type when making a GET request.

When we submit this request, we get an array of job objects in the response:

{
  "jobs": [
    {
      "id": "1234567",
      "completed": "2020-02-14T09:34:29.968000+00:00",
      "created": "2020-02-14T09:34:21+00:00",
      "callbackUrl": null,
      "appId": "123abc45-6789-01de-f2g3-45h67ijk8901",
      "status": "COMPLETED",
      "input": {
        "image_url": "data://1234/default/hotel-pool-03.jpeg"
      },
      "metadata": null,
      "uuid": "1a23bc4d-ef56-7g89-0h12-i23456jk78l7",
      "correct": null,
      "baselineId": null,
      "jobType": "CALIBRATION"
    },
    {
      "id": "2345678",
      "completed": "2020-03-12T11:10:56.464000+00:00",
      "created": "2020-03-12T11:10:39.690000+00:00",
      "callbackUrl": null,
      "appId": "123abc45-6789-01de-f2g3-45h67ijk8901",
      "status": "CANCELED",
      "input": {
        "image_url": "data://1234/default/hotel-pool-04.jpeg"
      },
      "metadata": null,
      "uuid": "1a23bc4d-ef56-7g89-0h12-i23456jk78l8",
      "correct": null,
      "baselineId": null,
      "jobType": "CALIBRATION"
    },
    {
      "id": "3456789",
      "completed": "2020-03-12T11:12:14.939000+00:00",
      "created": "2020-03-12T11:12:10.035000+00:00",
      "callbackUrl": null,
      "appId": "123abc45-6789-01de-f2g3-45h67ijk8901",
      "status": "CANCELED",
      "input": {
        "image_url": "data://1234/default/hotel-pool-05.jpeg"
      },
      "metadata": null,
      "uuid": "1a23bc4d-ef56-7g89-0h12-i23456jk78l9",
      "correct": null,
      "baselineId": null,
      "jobType": "CALIBRATION"
    }
  ],
  "total": 3,
  "pageSize": 10,
  "pageNumber": 0,
  "pages": 1
}

Parameters

There are 4 parameters when it comes to REST APIs:

• Header parameters
• Path parameters
• Query string parameters
• Request body parameters

You will send these parameters (in various combinations) in your request. In return, you will receive the relevant object in the response body.

Header parameters

These go in the request header. At super.AI, you use header parameters to pass us your API key, as mentioned in the authentication method section above. You use the -H flag in a cURL request to pass information as a header parameter, as in this example:

curl "https://api.super.ai/v1/apps/{app_id}/jobs" \
-H "API-KEY: {api_key}"

Path parameters

These parameters go within the endpoint path, before the query string (i.e., before the ?). Often, path parameters are variables that you need to replace with a real value from your super.AI account.

In the example below, {app_id} is a path parameter that needs to be swapped out with your project ID from the super.AI dashboard.

curl "https://api.super.ai/v1/apps/{app_id}/jobs"
-H "API-KEY: {api_key}"

Query string parameters

These go in the query string of the endpoint. The query string in a URL is any information that comes after the ?. In general, super.AI uses query string parameters to filter the data that you receive in your response, e.g., by start and end date. Each parameter is a key-value pair. There is an = between the key and value, and pairs need to be separated by an ampersand. The order of query string parameters is not important.

Here’s a request URL with some query string parameters appended:

curl "https://api.super.ai/v1/apps/{app_id}/job_responses?createdStartDate=2020-02-12T12%3A00%3A00&statusIn=COMPLETED&statusIn=CANCELED"
-H "API-KEY: {api_key}"

🚧

Encode your query string

Everything in your query string needs to be URL encoded. You can do this by pasting your raw query string into an online encoder and pressing Encode, then copy and pasting the encoded query string into your request.

Request body parameters

Often, POST requests require you to submit a JSON object, which will go in the request body. The structure of request body parameters is usually a little more complicated.

For example, when you submit new ground truth data, you will need to provide the following information:

• Input
• Label

Both of these go in JSON format that matches the Data Program schemas, creating something like this:

{
  "input":{
    "image_url":"data://1234/images/dogs/poodles/pink-poodle.jpeg"
  },
  "label":{
    "label":{
      "choices":[
        {
          "tag":"0",
          "value":"bulldog"
        },
        {
          "tag":"1",
          "value":"poodle"
        },
        {
          "tag":"2",
          "value":"not sure"
        }
      ],
      "selection":{
        "tag":"1",
        "value":"poodle"
      }
    }
  }
}

When you send your request, it will look like this:

curl "https://api.super.ai/v1/apis/{app_id}/baselineData" \
-X POST \
-H "API-KEY: {api_key}" \
-H "Content-Type: application/json" \
-d '{ "input\": {"image_url":"data://1234/images/dogs/poodles/pink-poodle.jpeg"}, "label": {"label":{"choices":[{"tag":"0","value":"bulldog"},{"tag":"1","value":"poodle"},{"tag":"2","value":"not sure"}],"selection":{"tag":"1","value":"poodle"}}}}'

A few things to note here:

• Because this is not a GET request, we need to specify the request type (POST) using the -X flag
• Because we’re sending a JSON body parameter, we need to let the server know that by adding ”Content-Type: application/json” to the request header using the -H flag
• To send JSON data as a request body parameter, we use the -d flag

Response body

When you submit a request, you will receive a response that includes a JSON object in the response body. In most instances, this will be an object or series of objects relevant to your request.

Error glossary

These error codes are returned by endpoints in the response body.

400

Bad request. Your request could not be processed. This could be for a number of reasons. If you have submitted a JSON body parameter, your JSON might not fit our schema or it might be invalid or incomplete JSON. Otherwise, you might have attempted an action on an endpoint that does not allow it, e.g., a PATCH request to the jobs endpoint.

401

API key invalid. Check in your super.AI dashboard that you are using the correct API key in your request. Hover over the profile icon in the bottom left and click on API keys. You might also be attempting an action that your user permission level does not allow. Contact the project owner if you require additional permissions.

402

Payment method invalid. If you’re the project owner, head to the super.AI dashboard and update your payment method by hovering over the profile icon in the lower left and heading to Billing.

404

Resource not found. You are trying to access or alter a resource that cannot be found on our server. The resource may have moved or been deleted. There might also be a typo in your request. Check any variables (e.g., app IDs and job IDs) against the information in your dashboard to make sure they’re correct.

500

Internal server error. Our servers have experienced a problem. If the problem occurs multiple times, contact us.