Getting Started

Learn how to convert your first file using the API in just 5 minutes.

Prerequisites

• An Agents for Data account (sign up is free)
• An API key (generate from settings)
• cURL, Node.js, or Python installed

Step 1: Generate an API Key

First, you need to generate an API key from your workspace settings:

1. Go to Settings → API Keys
2. Click "Create API Key"
3. Give it a name (e.g., "My First API Key")
4. Select permissions (for file conversion, choose "File Conversion")
5. Copy the key immediately - you won't be able to see it again!

Step 2: Get Upload URLs

Request signed URLs for uploading your source file and downloading the result:

curl -X POST https://agentsfordata.com/api/public/v1/convert/upload-urls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_format": "csv",
    "destination_format": "json",
    "filename": "my-data"
  }'

Response:

{
  "success": true,
  "data": {
    "source": {
      "upload_url": "https://storage.example.com/upload/...",
      "file_path": "2025-01-15/abc123/source-my-data.csv",
      "content_type": "text/csv"
    },
    "destination": {
      "download_url": "https://storage.example.com/download/...",
      "file_path": "2025-01-15/abc123/my-data.json",
      "content_type": "application/json"
    }
  }
}

Step 3: Upload Your File

Upload your source file to the signed URL you received:

curl -X PUT "UPLOAD_URL_FROM_STEP_2" \
  -H "Content-Type: text/csv" \
  --data-binary @your-file.csv

Step 4: Convert the File

Trigger the conversion process:

curl -X POST https://agentsfordata.com/api/public/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "FILE_PATH_FROM_STEP_2",
    "source_format": "csv",
    "destination_format": "json",
    "filename": "my-data"
  }'

Response:

{
  "success": true,
  "data": {
    "download_url": "https://storage.example.com/download/...",
    "file_path": "2025-01-15/abc123/my-data.json",
    "expires_at": "2025-01-15T15:30:00Z"
  }
}

Step 5: Download the Result

Download the converted file from the signed URL:

curl -o output.json "DOWNLOAD_URL_FROM_STEP_4"

Complete Example

Here's a complete bash script that ties all steps together:

#!/bin/bash

API_KEY="YOUR_API_KEY"
BASE_URL="https://agentsfordata.com/api/public/v1"

# Step 1: Get upload URLs
URLS_RESPONSE=$(curl -s -X POST "$BASE_URL/convert/upload-urls" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_format": "csv",
    "destination_format": "json",
    "filename": "my-data"
  }')

UPLOAD_URL=$(echo $URLS_RESPONSE | jq -r '.data.source.upload_url')
FILE_PATH=$(echo $URLS_RESPONSE | jq -r '.data.source.file_path')

# Step 2: Upload file
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: text/csv" \
  --data-binary @input.csv

# Step 3: Convert file
CONVERT_RESPONSE=$(curl -s -X POST "$BASE_URL/convert" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"source_url\": \"$FILE_PATH\",
    \"source_format\": \"csv\",
    \"destination_format\": \"json\"
  }")

DOWNLOAD_URL=$(echo $CONVERT_RESPONSE | jq -r '.data.download_url')

# Step 4: Download result
curl -o output.json "$DOWNLOAD_URL"

echo "Conversion complete! Output saved to output.json"

What's Next?

• Explore all available endpoints - Learn about format listing and other features
• View code examples - See examples in JavaScript, Python, and more
• Understand rate limits - Learn about API usage limits
• Handle errors gracefully - Learn about error codes and best practices