cURL - Relay

This guide provides cURL examples for common Relay API operations.

Setup

Set your API key as an environment variable:

export RELAY_API_KEY="your_api_key_here"

Datasets

List datasets

curl https://api.relayai.dev/api/v1/datasets \
  -H "X-API-Key: $RELAY_API_KEY"

Create dataset

curl -X POST https://api.relayai.dev/api/v1/datasets \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TTS Glitch Detection",
    "description": "Detect audio artifacts in TTS output",
    "artifact_types": [
      {"name": "glitch", "description": "Audio pop or click", "color": "#FF4444"},
      {"name": "long_pause", "description": "Silence > 500ms", "color": "#4444FF"}
    ]
  }'

Get dataset

curl https://api.relayai.dev/api/v1/datasets/$DATASET_ID \
  -H "X-API-Key: $RELAY_API_KEY"

Update dataset

curl -X PATCH https://api.relayai.dev/api/v1/datasets/$DATASET_ID \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Dataset Name"
  }'

Delete dataset

curl -X DELETE https://api.relayai.dev/api/v1/datasets/$DATASET_ID \
  -H "X-API-Key: $RELAY_API_KEY"

Audio files

Get upload URL

curl -X POST "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/audio/upload-url" \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "sample.wav",
    "content_type": "audio/wav",
    "file_size": 1048576
  }'

Upload file to presigned URL

After getting the upload URL and fields, upload using multipart form:

curl -X POST "$UPLOAD_URL" \
  -F "key=$KEY" \
  -F "policy=$POLICY" \
  -F "x-amz-signature=$SIGNATURE" \
  -F "x-amz-credential=$CREDENTIAL" \
  -F "x-amz-algorithm=AWS4-HMAC-SHA256" \
  -F "x-amz-date=$DATE" \
  -F "x-amz-security-token=$TOKEN" \
  -F "file=@sample.wav"

Confirm upload

curl -X POST "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/audio/confirm" \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "audio-uuid-here"
  }'

List audio files

curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/audio" \
  -H "X-API-Key: $RELAY_API_KEY"

# Filter by status
curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/audio?status=ready" \
  -H "X-API-Key: $RELAY_API_KEY"

Get audio file

curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/audio/$AUDIO_ID" \
  -H "X-API-Key: $RELAY_API_KEY"

Delete audio file

curl -X DELETE "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/audio/$AUDIO_ID" \
  -H "X-API-Key: $RELAY_API_KEY"

Get download URL

curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/audio/$AUDIO_ID/download-url" \
  -H "X-API-Key: $RELAY_API_KEY"

# Normalized version
curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/audio/$AUDIO_ID/download-url?normalized=true" \
  -H "X-API-Key: $RELAY_API_KEY"

Annotation sets

Create annotation set

curl -X POST "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets" \
  -H "X-API-Key: $RELAY_API_KEY"

List annotation sets

curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets" \
  -H "X-API-Key: $RELAY_API_KEY"

Get annotation set

curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets/$ANNOTATION_SET_ID" \
  -H "X-API-Key: $RELAY_API_KEY"

Publish annotation set

curl -X POST "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets/$ANNOTATION_SET_ID/publish" \
  -H "X-API-Key: $RELAY_API_KEY"

Delete annotation set

curl -X DELETE "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets/$ANNOTATION_SET_ID" \
  -H "X-API-Key: $RELAY_API_KEY"

Annotations

Create single annotation

curl -X POST "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets/$ANNOTATION_SET_ID/annotations" \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_file_id": "audio-uuid",
    "artifact_type": "glitch",
    "start_ms": 1200,
    "end_ms": 1450,
    "confidence": 1.0
  }'

Create bulk annotations

curl -X POST "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets/$ANNOTATION_SET_ID/annotations/bulk" \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "audio_file_id": "audio-uuid-1",
        "artifact_type": "glitch",
        "start_ms": 1200,
        "end_ms": 1450
      },
      {
        "audio_file_id": "audio-uuid-1",
        "artifact_type": "long_pause",
        "start_ms": 3500,
        "end_ms": 4200
      }
    ]
  }'

List annotations

curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets/$ANNOTATION_SET_ID/annotations" \
  -H "X-API-Key: $RELAY_API_KEY"

# Filter by audio file
curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets/$ANNOTATION_SET_ID/annotations?audio_file_id=$AUDIO_ID" \
  -H "X-API-Key: $RELAY_API_KEY"

Export to Label Studio

curl "https://api.relayai.dev/api/v1/datasets/$DATASET_ID/annotation-sets/$ANNOTATION_SET_ID/export/label-studio" \
  -H "X-API-Key: $RELAY_API_KEY"

Training

Create training job

curl -X POST https://api.relayai.dev/api/v1/training-jobs \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "dataset-uuid",
    "annotation_set_id": "annotation-set-uuid",
    "config": {
      "artifact_types": ["glitch", "long_pause"],
      "epochs": 20,
      "validation_split": 0.2,
      "learning_rate": 0.001,
      "batch_size": 32
    }
  }'

List training jobs

curl https://api.relayai.dev/api/v1/training-jobs \
  -H "X-API-Key: $RELAY_API_KEY"

# Filter by dataset
curl "https://api.relayai.dev/api/v1/training-jobs?dataset_id=$DATASET_ID" \
  -H "X-API-Key: $RELAY_API_KEY"

Get training job

curl https://api.relayai.dev/api/v1/training-jobs/$JOB_ID \
  -H "X-API-Key: $RELAY_API_KEY"

Cancel training job

curl -X DELETE https://api.relayai.dev/api/v1/training-jobs/$JOB_ID \
  -H "X-API-Key: $RELAY_API_KEY"

Models

List models

curl https://api.relayai.dev/api/v1/models \
  -H "X-API-Key: $RELAY_API_KEY"

# Only active models
curl "https://api.relayai.dev/api/v1/models?is_active=true" \
  -H "X-API-Key: $RELAY_API_KEY"

Get model

curl https://api.relayai.dev/api/v1/models/$MODEL_ID \
  -H "X-API-Key: $RELAY_API_KEY"

Update model

curl -X PATCH https://api.relayai.dev/api/v1/models/$MODEL_ID \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TTS Glitch Detector v2",
    "description": "Improved model with more training data"
  }'

Delete model

curl -X DELETE https://api.relayai.dev/api/v1/models/$MODEL_ID \
  -H "X-API-Key: $RELAY_API_KEY"

Inference

Create inference job

curl -X POST https://api.relayai.dev/api/v1/inference-jobs \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "model-uuid",
    "config": {
      "threshold": 0.5,
      "merge_window_ms": 200,
      "min_duration_ms": 50
    }
  }'

List inference jobs

curl https://api.relayai.dev/api/v1/inference-jobs \
  -H "X-API-Key: $RELAY_API_KEY"

Get inference job

curl https://api.relayai.dev/api/v1/inference-jobs/$JOB_ID \
  -H "X-API-Key: $RELAY_API_KEY"

Get upload URL for inference

curl -X POST "https://api.relayai.dev/api/v1/inference-jobs/$JOB_ID/files/upload-url" \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "test.wav",
    "content_type": "audio/wav",
    "file_size_bytes": 2097152
  }'

Confirm inference file upload

curl -X POST "https://api.relayai.dev/api/v1/inference-jobs/$JOB_ID/files/confirm" \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file-uuid"
  }'

List inference files

curl "https://api.relayai.dev/api/v1/inference-jobs/$JOB_ID/files" \
  -H "X-API-Key: $RELAY_API_KEY"

Get inference file

curl "https://api.relayai.dev/api/v1/inference-jobs/$JOB_ID/files/$FILE_ID" \
  -H "X-API-Key: $RELAY_API_KEY"

API keys

List API keys

curl https://api.relayai.dev/api/v1/auth/api-keys \
  -H "X-API-Key: $RELAY_API_KEY"

Create API key

curl -X POST https://api.relayai.dev/api/v1/auth/api-keys \
  -H "X-API-Key: $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server"
  }'

Revoke API key

curl -X DELETE https://api.relayai.dev/api/v1/auth/api-keys/$KEY_ID \
  -H "X-API-Key: $RELAY_API_KEY"

Shell script example

Complete workflow script:

#!/bin/bash
set -e

# Configuration
API_KEY="${RELAY_API_KEY}"
BASE_URL="https://api.relayai.dev"

# Create dataset
echo "Creating dataset..."
DATASET=$(curl -s -X POST "$BASE_URL/api/v1/datasets" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Dataset",
    "artifact_types": [{"name": "glitch"}]
  }')
DATASET_ID=$(echo $DATASET | jq -r '.id')
echo "Created dataset: $DATASET_ID"

# Create annotation set
echo "Creating annotation set..."
ANNOTATION_SET=$(curl -s -X POST "$BASE_URL/api/v1/datasets/$DATASET_ID/annotation-sets" \
  -H "X-API-Key: $API_KEY")
ANNOTATION_SET_ID=$(echo $ANNOTATION_SET | jq -r '.id')
echo "Created annotation set: $ANNOTATION_SET_ID"

# Publish annotation set
echo "Publishing annotation set..."
curl -s -X POST "$BASE_URL/api/v1/datasets/$DATASET_ID/annotation-sets/$ANNOTATION_SET_ID/publish" \
  -H "X-API-Key: $API_KEY" > /dev/null

echo "Done!"

​Setup

​Datasets

​List datasets

​Create dataset

​Get dataset

​Update dataset

​Delete dataset

​Audio files

​Get upload URL

​Upload file to presigned URL

​Confirm upload

​List audio files

​Get audio file

​Delete audio file

​Get download URL

​Annotation sets

​Create annotation set

​List annotation sets

​Get annotation set

​Publish annotation set

​Delete annotation set

​Annotations

​Create single annotation

​Create bulk annotations

​List annotations

​Export to Label Studio

​Training

​Create training job

​List training jobs

​Get training job

​Cancel training job

​Models

​List models

​Get model

​Update model

​Delete model

​Inference

​Create inference job

​List inference jobs

​Get inference job

​Get upload URL for inference

​Confirm inference file upload

​List inference files

​Get inference file

​API keys

​List API keys

​Create API key

​Revoke API key

​Shell script example