Back to App

API Documentation

v1.0.0

OpenAPI Spec

Endpoints Reference

Complete reference for all API endpoints, including request/response schemas and examples.

Base URL

https://agentsfordata.com/api/public/v1

All endpoints are prefixed with this base URL. For example, the full URL for the convert endpoint is:

https://agentsfordata.com/api/public/v1/convert

Authentication

All endpoints require authentication. Include your API key in the Authorization header:

Authorization: Bearer tablab_api_xxxxxxxxxxxxx

See the Authentication guide for details.

File Conversion Endpoints

Generate Upload URLs

POST/convert/upload-urls

Generates signed URLs for uploading source files and downloading converted results. This is the first step in the file conversion workflow.

Request Body

{
  "source_format": "csv",           // Required: Source file format
  "destination_format": "json",     // Required: Destination format
  "filename": "my-data"             // Optional: Name for the files
}

Response (200 OK)

{
  "success": true,
  "data": {
    "source": {
      "upload_url": "https://...",    // Signed URL to upload source file
      "file_path": "2025/.../file",   // Path to reference in convert call
      "content_type": "text/csv"      // Content-Type to use when uploading
    },
    "destination": {
      "download_url": "https://...",  // Signed URL to download result
      "file_path": "2025/.../file",
      "content_type": "application/json"
    }
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}

Rate Limits

  • 30 requests per minute
  • 500 requests per hour
  • 2,000 requests per day

Possible Errors

  • 400 - Invalid format specified
  • 401 - Invalid or missing API key
  • 429 - Rate limit exceeded

Convert File

POST/convert

Converts an uploaded file from one format to another. The source file must be uploaded to the URL obtained from the /upload-urls endpoint first.

Request Body

{
  "source_url": "2025/.../source-file.csv",  // Required: file_path from upload-urls
  "source_format": "csv",                    // Required: Source format
  "destination_format": "json",              // Required: Destination format
  "filename": "my-data"                      // Optional: Name for output file
}

Response (200 OK)

{
  "success": true,
  "data": {
    "download_url": "https://...",     // Signed URL to download converted file
    "file_path": "2025/.../file.json",
    "expires_at": "2025-01-15T15:30:00Z"  // When download URL expires
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}

Rate Limits

  • 10 requests per minute
  • 100 requests per hour
  • 500 requests per day

Possible Errors

  • 400 - Invalid request (missing fields, invalid format, etc.)
  • 401 - Invalid or missing API key
  • 404 - Source file not found
  • 429 - Rate limit exceeded
  • 500 - Conversion failed

List Supported Formats

GET/convert/formats

Returns a list of all supported file formats and their conversion capabilities. This is a metadata endpoint with higher rate limits.

Response (200 OK)

{
  "success": true,
  "data": {
    "formats": [
      {
        "format": "csv",
        "display_name": "CSV",
        "mime_type": "text/csv",
        "can_read": true,
        "can_write": true
      },
      {
        "format": "json",
        "display_name": "JSON",
        "mime_type": "application/json",
        "can_read": true,
        "can_write": true
      },
      {
        "format": "xlsx",
        "display_name": "Excel",
        "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "can_read": true,
        "can_write": true
      },
      {
        "format": "parquet",
        "display_name": "Parquet",
        "mime_type": "application/vnd.apache.parquet",
        "can_read": true,
        "can_write": true
      },
      {
        "format": "tsv",
        "display_name": "TSV",
        "mime_type": "text/tab-separated-values",
        "can_read": true,
        "can_write": true
      }
    ]
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}

Rate Limits

  • 60 requests per minute
  • 1,000 requests per hour
  • 5,000 requests per day

Possible Errors

  • 401 - Invalid or missing API key
  • 429 - Rate limit exceeded

Supported File Formats

The API supports conversion between the following formats:

FormatExtensionMIME TypeDescription
CSV.csvtext/csvComma-separated values
JSON.jsonapplication/jsonJavaScript Object Notation
Excel.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheetMicrosoft Excel spreadsheet
Parquet.parquetapplication/vnd.apache.parquetApache Parquet columnar format
TSV.tsvtext/tab-separated-valuesTab-separated values

Common Response Fields

All API responses include these standard fields:

Success Response

{
  "success": true,        // Always true for successful responses
  "data": { ... },        // Endpoint-specific data
  "meta": {
    "request_id": "...",  // Unique request identifier
    "timestamp": "...",   // ISO 8601 timestamp
    "version": "v1"       // API version
  }
}

Error Response

{
  "success": false,       // Always false for errors
  "error": {
    "code": "...",        // Machine-readable error code
    "message": "...",     // Human-readable error message
    "details": { ... }    // Optional additional context
  },
  "meta": {
    "request_id": "...",
    "timestamp": "...",
    "version": "v1"
  }
}

Rate Limit Headers

All responses include rate limit information in the headers:

X-RateLimit-Limit: 30          # Maximum requests in window
X-RateLimit-Remaining: 25      # Requests remaining
X-RateLimit-Reset: 1705324200  # Unix timestamp when limit resets

See the Rate Limits guide for more details.

See It In Action

Ready to try these endpoints? Check out our code examples.

View Code Examples →