API authorization set up

When on API keys page, scroll down and you will see the Region code and your Project Id. Region

To generate your Relevance API key, click on "Create new secret key", with the role "Admin". Click on "Generate API key". Copy the values shown on the modal.

  • Authorization token
  • API key
  • Region
  • Project

Authorization tokens are formed by combining Project Id:API Key.

Either directly copy the Authorization token from the API page or use the Project id and API key combination as shown in the snippet below:

project_id = "YOUR_PROJECT_ID" # Can be found in the API Keys page
authorization_token = f"{YOUR_PROJECT_ID}:{YOUR_API_KEY}"   # Both values can be found in the API Keys page
region = "YOUR_REGION"       # Can be found in the API Keys page
base_url = f"https://api-{region}.stack.tryrelevance.com/latest"
headers = {
  "Authorization": authorization_token,

Tool ID

There are different ways to find the ID of a Tool. The easiest way is to use the URL. For example when on the Tool and Use tab, the component before use/app and after project ID is the tool ID. The string below shows the URL structure:


tool_id = "YOUR_TOOL_ID"

Make async call for long running tool

Provide tool_id in the code below to trigger a task and check the progress:

import requests

body = {

response = requests.post(
  base_url + f"studios/{tool_id}/trigger_async", 

# Extract the tools job id, so we can check its progress
job = response.json()
job_id = job['job_id']

poll_url = base_url + f"/studios/{tool_id}/async_poll/{job_id}?ending_update_only=true"

done = False
# Every 3 seconds, check if the tool had finished by calling the poll endpoint
while not done:
    poll_response = requests.get(poll_url, headers=headers).json()
    if poll_response['type'] == "complete" or poll_response['type'] == 'failed':
        done = True