API documentation

TwinAI API Documentation

Welcome to the TwinAI API documentation. This guide provides detailed instructions on how to interact with the TwinAI API, including example cURL calls to help you get started quickly.

How to acquire an API key

Step 1: Access the API keys section

1. Log in to your Twin AI account.
2. Click on your profile icon located in the top-right corner of the screen.
3. Click on "Organization" in the menu.
4. You will be redirected to the organization settings page.

Step 2: Access the API keys section

1. Click on the "API keys" tab.

Step 3: Generate a new Key

1. Click the "+ New key" button to create a unique API key.

Base URL

All API requests should be made to the following base URL:

https://api.twinai.nl

Authentication

All requests to the TwinAI API require an Authorization header. Replace YOUR_API_KEY with your actual API key.

Running a Workflow

Start a Workflow Run

To start a workflow run, you need to make a POST request to the following endpoint:

/v1/workflows/WORKFLOW_ID/run

Replace WORKFLOW_ID with your actual workflow ID.

Example Request:

curl $API_URL/v1/workflows/WORKFLOW_ID/run \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"input": {"input": "Ate a banana"}}'

Example Response:

{
  "id": "RUN_ID",
  "status": 1
}

The response will include the run_id that you will use to poll the status of the run.

Polling the Run Status

To check the status of a workflow run, make a GET request to the following endpoint:

/v1/runs/{RUN_ID}

Replace {RUN_ID} with the run ID obtained from the previous step.

Example Request:

curl $API_URL/v1/runs/RUN_ID \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "id": "RUN_ID",
  "status": 2
}

• Status Code 2: Indicates the run is completed.

Example Script for Polling Run Status:

Below is an example Bash script to automate polling the run status until it is completed.

# Set the default API URL
API_URL="https://api.twinai.nl"
WORKFLOW_ID="YOUR_WORKFLOW_ID"
API_KEY="YOUR_API_KEY"

# Function to poll the status of a run
function poll_run_status() {
  local run_id=$1
  local status

  while true; do
    # Get the status of the run
    status=$(curl $API_URL/v1/runs/$run_id -X GET \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $API_KEY" | jq -r '.status')

    # Check if the status is 2 (completed)
    if [[ $status -eq 2 ]]; then
      break
    fi

    # Sleep for 1 second before polling again
    sleep 1
  done
}

# Start the workflow run
run_id=$(curl $API_URL/v1/workflows/$WORKFLOW_ID/run \
  -X POST \
  -d '{"input": {"input": "Ate a banana"}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" | jq -r '.id')

# Output the Run ID
echo "Run ID: $run_id"

# Poll the status of the run until completed
poll_run_status $run_id

# Fetch the final run details
curl $API_URL/v1/runs/$run_id -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" | jq

Upload a file

Creating and upload a file in the Twin AI platform is a two-step process. First, this file models needs to be created. Secondly, the file needs to be uploaded.

# Create a file model
response=$(curl $API_URL/v1/files/create-file-model \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY")

# Get the upload location & file id
upload_location=$(echo "$response" | jq -r '.uploadLocation')
file_id=$(echo "$response" | jq -r '.id')

# Upload the file
curl "$upload_location" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@audio.mp3"

Conclusion

This documentation covers the essential endpoints and steps to interact with the TwinAI API. By following the provided examples, you should be able to start workflows and monitor their status efficiently.

For any further queries, contact support@twinai.nl.