Through Custom integration, you have the ability to integrate and import from any external data source of your choice. You’ll be able to access and annotate any of the items in your storage, whether it’s the entire contents of the folder or bucket, or a specific selection. Accessing your files this way will not make them public or store them on SuperAnnotate’s servers.

If you already have a custom integration set up, you can start uploading your items into your projects.

Create custom integrations

A custom integration can be created in two ways. Users with the role of Team Admin or higher can create a custom integration from the Team Setup tab within the team. Creating a custom integration from the Organization tab and choosing which teams have access to it can only be done by the Organization Owner.

Method 1: Team Setup

To create a custom integration through Team Setup:

1. In Team Setup, go to Integrations.
2. Click + New Integration.
3. Select Custom.
4. In the Integration name field, type in a unique name for your integration.
5. In the Request URL field, provide your server URL that SuperAnnotate will be making requests to. Check out the section below to learn more about server configuration.
6. Copy the secret from the Secret field and use it in your server configuration. This will allow the server to identify SuperAnnotate’s requests and approve them.
7. Click Create.

Method 2: Organization

To create a custom integration from Organization:

1. In the Organization tab, go to Integrations.
2. Click + New Integration.
3. Select Custom.
4. In the Integration name field, type in a unique name for your integration.
5. You may choose one or multiple teams who will have access to this integration (Optional, this can be done later).
6. In the Request URL field, provide your server URL that SuperAnnotate will be making requests to. Check out the section below to learn more about server configuration.
7. Copy the secret from the Secret field and use it in your server configuration. This will allow the server to identify SuperAnnotate’s requests and approve them.
8. Click Create.

Server configuration

To create the custom integration SuperAnnotate expects an HTTPS server. The server should have an endpoint that provides temporary signed URLs for items in your annotation project.

SuperAnnotate will send an HTTP POST request to the provided request URL of the server with the following structure.

Request Headers

{
   "token": "string"
}

"token": string - a string with the automatically generated secret token that identifies the SuperAnnotate requests.

Request Body

{
   "paths": [ "string" ] 
}

The request accepts the following data in JSON format:

"paths": array of strings - an array of strings with item paths in your storage for which the API generates signed URLs. These are the paths written in a CSV file that you must upload. Learn more.

📘

API connection check

• To validate the connection between your server and SuperAnnotate, we will send an empty request body to your server, which should be handled with an HTTP 200 response.
• The expected timeout should be set to 5 seconds.

Response Body

If the generation of signed URLs is successful, the server should send back an HTTP 200 response with the following syntax:

{
   "urls": [ "string" ]
}

The following data should be returned in JSON format by the service:

"urls": array of strings - an array of strings with signed URLs for the items in your storage.

Add items with custom integration

You can upload items from a custom storage integration. You must have one created and integrated in order to do this.

1. In Data, click + Add.
2. Select Upload Items (depending on your project type).
3. Go to the External storage tab.
4. From the Integration dropdown, select your custom integration.
5. Drag and drop your CSV file with your item names and URLs, or click Choose file to find it. See how to create a CSV file below.
6. Click Upload.
7. You will see the progress of your file upload. When it’s complete, click Done.

📘

This process will allow SuperAnnotate to view your files so that you can annotate them. It will not upload the files to SuperAnnotate’s servers. Those files will stay in your server.

Create CSV file

To add items, create a CSV file that contains their names and URLs. Use this template CSV file as a reference.