API Documentation

Use the BatchGenie API to programmatically manage batch processing jobs.

Authentication

All API requests require authentication via an API key. Include your key in the Authorization header:

Authorization: Bearer bg_live_xxxxxxxxxxxxxxxx

Create API keys in your dashboard settings. Keys can be scoped to specific permissions.

Base URL

/api/v1

Rate Limits

Free Plan

10 req/min

Pro Plan

60 req/min

Team / Enterprise

200 req/min

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Quick Start

curl

curl -X GET "/api/v1/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

node

const response = await fetch("/api/v1/jobs", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
});
const data = await response.json();

python

import requests

response = requests.get(
    "/api/v1/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

Endpoints

GET/api/v1/jobs

List all your batch processing jobs with pagination and filtering.

API Key (Bearer token)jobs:read

Query Parameters

Name	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20, max: 100)
status	string	No	Filter by status: PENDING, QUEUED, PROCESSING, COMPLETED, FAILED, CANCELLED
jobType	string	No	Filter by type: CLASSIFICATION, ENRICHMENT, TRANSFORMATION, EXTRACTION, TRANSLATION, ANALYSIS, CUSTOM

Response

{
  "jobs": [
    {
      "id": "clx...",
      "name": "Product Classification",
      "status": "COMPLETED",
      "progress": 100,
      "rowsProcessed": 500,
      "rowsSucceeded": 498,
      "rowsFailed": 2,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 42 }
}

POST/api/v1/jobs

Create a new batch processing job. The job will be queued for processing.

API Key (Bearer token)jobs:write

Request Body

Field	Type	Required	Description
name	string	Yes	Job name (max 200 chars)
jobType	string	Yes	Job type (see GET /jobs for values)
prompt	string	Yes	Processing prompt for the AI model
model	string	No	AI model (default: CLAUDE_SONNET). Options: CLAUDE_OPUS, CLAUDE_SONNET, CLAUDE_HAIKU, GPT_4O, GPT_4O_MINI, GEMINI_PRO, GEMINI_FLASH
inputFileKey	string	No	S3/R2 key of uploaded input file
config	object	No	Additional configuration
tags	string[]	No	Tags for organization

Response

{
  "id": "clx...",
  "name": "Product Classification",
  "status": "PENDING",
  "createdAt": "2025-01-15T10:30:00Z"
}

GET/api/v1/jobs/:jobId

Get detailed information about a specific job including progress, metrics, and errors.

API Key (Bearer token)jobs:read

Response

{
  "id": "clx...",
  "name": "Product Classification",
  "status": "COMPLETED",
  "jobType": "CLASSIFICATION",
  "model": "CLAUDE_SONNET",
  "progress": 100,
  "inputRowCount": 500,
  "rowsProcessed": 500,
  "rowsSucceeded": 498,
  "rowsFailed": 2,
  "inputTokens": 125000,
  "outputTokens": 50000,
  "estimatedCost": 0.525,
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:35:22Z"
}

GET/api/v1/templates

List available job templates. Includes public templates and your private templates.

API Key (Bearer token)templates:read

Query Parameters

Name	Type	Required	Description
category	string	No	Filter by category
search	string	No	Search by name or description

Response

{
  "templates": [
    {
      "id": "clx...",
      "name": "Sentiment Analysis",
      "category": "SENTIMENT",
      "jobType": "CLASSIFICATION",
      "description": "Classify text sentiment..."
    }
  ]
}

Webhooks

Configure webhooks to receive real-time notifications when jobs complete, fail, or hit milestones. Set up webhooks in your dashboard settings.

Available Events

job.created

job.completed

job.failed

job.cancelled

job.progress

Signature Verification

All webhook payloads are signed with HMAC-SHA256. Verify the X-BatchGenie-Signature header against your webhook secret.

Error Codes

Code	Description
400	Bad Request - Invalid parameters or request body
401	Unauthorized - Missing or invalid API key
403	Forbidden - API key lacks required scopes
404	Not Found - Resource doesn't exist
429	Rate Limited - Too many requests
500	Internal Error - Server-side issue