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 won't 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'll 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'll allow the server to identify SuperAnnotate’s requests and approve them.
8. Click Create.

🚧

• Only Organization Owners can set up an integration from the Organization tab.
• Team Admins can set up an integration for the team they’re a part of, from the Team Setup tab.

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'll 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'll 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 won't upload the files to SuperAnnotate’s servers. Those files will stay in your server.

🚧

Folder paths

• Note that when you type in a folder path, all items within that folder will be uploaded. You won't be able to select and choose specific files from the folder.
• SuperAnnotate supports a two-level folder structure. This means that you can have items and folders in a project, but you can’t create or upload subfolders. For example, let’s say you want to upload a folder from your cloud storage to the root folder of your project. If that folder has several items and a subfolder, the subfolder will be excluded. If you want to upload items from that subfolder, you’ll have to specify its location path: FOLDER 1 / SUBFOLDER

🚧

Enable CORS for Text Projects

You’ll need to enable CORS in your storage to be able to make use of your items in the Text Editor. Learn more.

Attach URLs

There are two ways to prepare your CSV files in order to import your items from a custom integration by attaching URLs.

Upload CSV file

You can create a CSV file that contains the item names and URLs (using this template), and upload the file from your computer.

Import with SDK

In the case of attaching your URLs or dictionaries with SDK. You can use the following function: attach_items()

client = SAClient()
client.attach_items(
    project = "Medical Annotations",
    attachments =  [
        {
            "name": "item",
            "url": "https://bucket-name.s3.us-east-2.amazonaws.com/medical/example.png"
            "integration": "custom-integration-name"
            }
        ]
)

Then you need to use the following format when creating your CSV file or list of dictionaries:

Now paste the CSV path into the function:

client = SAClient()
client.attach_items(
    project = "Medical Annotations",
    attachments = "data.csv"