Endpoints

Overview

All endpoints are relative to the base URL https://api.offload.run/v1 and require a valid API key. See Authentication for details.

Create a job

POST /jobs enqueues a job and returns immediately with a queued status. Provide the job type, an input URL, and any type-specific options.

curl https://api.offload.run/v1/jobs \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "compress-video",
    "input": "https://example.com/video.mp4",
    "options": { "quality": "high", "format": "mp4" },
    "webhookUrl": "https://yourapp.com/api/webhooks/offload"
  }'

Response:

{
  "id": "job_abc123",
  "type": "compress-video",
  "status": "queued",
  "createdAt": "2026-07-14T10:30:00Z"
}

Retrieve a job

GET /jobs/:id returns the current state of a job. Once status is completed, the result.url holds a temporary, signed download link.

{
  "id": "job_abc123",
  "type": "compress-video",
  "status": "completed",
  "result": {
    "url": "https://storage.offload.run/compressed-video.mp4",
    "size": 1024000,
    "duration": 120
  },
  "createdAt": "2026-07-14T10:30:00Z",
  "completedAt": "2026-07-14T10:32:30Z"
}

Result URLs are signed and expire after one hour. Fetch the job again to get a fresh link, or use a webhook to be notified the moment a job finishes instead of polling.

List jobs

GET /jobs returns your most recent jobs, newest first. Paginate with the limit and cursor query parameters, or filter by status.

GET /jobs?status=completed&limit=20

Job status values

• queued — accepted and waiting for a worker.
• processing — actively being processed.
• completed — finished; result is available.
• failed — processing failed; error explains why.

Job types

Set the type field to one of:

Errors

Errors use standard HTTP status codes and return a JSON body with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "invalid_input",
    "message": "The 'input' field must be a valid URL."
  }
}