API Reference

Base URL

http://localhost:3000/api

Submit Render Job

POST /api/render

Submit a new video render job.

Request Body

{
  provider: "rendley" | "unified";
  composition: object;          // Provider-specific composition data
  assetUrls?: Record<string, string>;  // Map sourceId → URL
  webhook?: string;             // URL to call on completion
}

Response (202 Accepted)

{
  "jobId": "abc123xyz",
  "status": "queued",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Example

curl -X POST http://localhost:3000/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "rendley",
    "composition": {
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "layers": [...]
    },
    "assetUrls": {
      "media-abc": "https://example.com/video.mp4"
    },
    "webhook": "https://your-app.com/webhook"
  }'

Get Job Status

GET /api/render/:jobId

Get the current status of a render job.

Response (200 OK)

{
  jobId: string;
  status: "queued" | "processing" | "completed" | "failed" | "cancelled";
  progress?: number;           // 0-100 percentage
  outputUrl?: string;          // Available when completed
  error?: {
    code: string;
    message: string;
  };
  createdAt: string;
  updatedAt: string;
}

Example

curl http://localhost:3000/api/render/abc123xyz

Response

{
  "jobId": "abc123xyz",
  "status": "completed",
  "progress": 100,
  "outputUrl": "https://storage.example.com/renders/abc123xyz.mp4",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:05:00.000Z"
}

Cancel Job

DELETE /api/render/:jobId

Cancel a queued or processing job.

Response (200 OK)

{
  "jobId": "abc123xyz",
  "status": "cancelled"
}

Error Response (400 Bad Request)

{
  "error": {
    "code": "JOB_NOT_CANCELLABLE",
    "message": "Job is already in terminal state: completed"
  }
}

Health Check

GET /api/health

Check if the API is running.

Response (200 OK)

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Error Responses

All endpoints return errors in this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Common Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request body
`JOB_NOT_FOUND`	404	Job ID does not exist
`JOB_NOT_CANCELLABLE`	400	Job is in terminal state
`TRIGGER_SUBMIT_FAILED`	500	Failed to queue job
`INTERNAL_ERROR`	500	Unexpected server error

Job Status Flow

queued → processing → completed
                   ↘ failed

queued → cancelled

queued: Job is waiting in the queue
processing: Job is currently rendering
completed: Render finished successfully, outputUrl available
failed: Render failed, error contains details
cancelled: Job was cancelled by user

Webhook Payload

When a webhook URL is provided, it receives a POST request on completion:

{
  "jobId": "abc123xyz",
  "status": "completed",
  "outputUrl": "https://storage.example.com/renders/abc123xyz.mp4",
  "duration": 10.5,
  "format": "mp4",
  "resolution": {
    "width": 1920,
    "height": 1080
  }
}

API Reference

On this page