Jobs API

A job represents a request to fetch multiple URLs and package them into a single ZIP file.

Create Job

POST /jobs

Request Body

Parameter	Type	Required	Description
`urls`	`string[]`	Yes	Array of URLs to download. Min 1, max 5,000.
`zip_filename`	`string`	No	Custom filename for the ZIP (`.zip` extension appended automatically). Max 255 characters. Defaults to `archive-{id}.zip`.
`expires_in`	`number`	No	Seconds until the ZIP is deleted. Min `300` (5 min), max `5184000` (60 days). Defaults to 24 hours.
`fail_on_url_error`	`boolean`	No	If `true` (default), the job fails when any URL cannot be fetched. If `false`, failed URLs are skipped and recorded in `errors`.
`metadata`	`object`	No	Up to 10 key/value pairs (key ≤ 128 chars, value ≤ 1,024 chars) stored with the job.

Plan Limits

	Free	Pro
Max URLs per job	100	5,000
Max ZIP size	2 GB	50 GB
Max retention (`expires_in`)	86,400 s (24 h)	5,184,000 s (60 d)

Example Request

curl -X POST https://api.eazip.io/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/file1.pdf",
      "https://example.com/file2.pdf",
      "https://example.com/image.png"
    ],
    "zip_filename": "my-archive",
    "expires_in": 172800,
    "fail_on_url_error": false,
    "metadata": {
      "order_id": "ord_123"
    }
  }'

Response

HTTP 201 Created

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

List Jobs

GET /jobs

Uses cursor-based pagination for efficient querying.

Query Parameters

Parameter	Type	Description
`limit`	`number`	Results per page. Default `20`, max `100`.
`cursor`	`string`	Opaque cursor from `meta.next_cursor` in the previous response. Omit for the first page.
`status`	`string`	Filter by status: `pending`, `processing`, `completed`, `failed`.

Example Request

curl "https://api.eazip.io/jobs?status=completed&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "jobs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "url_count": 3,
      "file_count": 3,
      "zip_filename": "my-archive.zip",
      "zip_size": 1048576,
      "fail_on_url_error": true,
      "created_at": "2025-01-21T10:00:00.000Z",
      "completed_at": "2025-01-21T10:00:45.000Z",
      "expires_at": "2025-01-23T10:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 10,
    "total": 42,
    "next_cursor": "2025-01-20T09:00:00.000Z",
    "has_more": true
  }
}

To fetch the next page, pass meta.next_cursor as the cursor query parameter. When meta.has_more is false, you have reached the end.

Get Job

GET /jobs/:id

Example Request

curl https://api.eazip.io/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (completed)

{
  "success": true,
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "urls": [
      "https://example.com/file1.pdf",
      "https://example.com/file2.pdf",
      "https://example.com/image.png"
    ],
    "url_count": 3,
    "file_count": 3,
    "zip_filename": "my-archive.zip",
    "zip_size": 1048576,
    "fail_on_url_error": true,
    "download_url": "https://api.eazip.io/download/eyJ...",
    "metadata": { "order_id": "ord_123" },
    "created_at": "2025-01-21T10:00:00.000Z",
    "completed_at": "2025-01-21T10:00:45.000Z",
    "expires_at": "2025-01-23T10:00:00.000Z"
  }
}

download_url is only present when status is completed and the job has not yet expired.

When fail_on_url_error is false and some URLs fail, the response includes an errors array:

{
  "success": true,
  "job": {
    "id": "...",
    "status": "completed",
    "errors": [
      { "url": "https://example.com/missing.pdf", "error": "HTTP 404" }
    ]
  }
}

Job Status Values

Status	Description
`pending`	Job created, waiting to start
`processing`	Currently fetching URLs and building the ZIP
`completed`	ZIP file is ready for download
`failed`	Job failed — check `errors` for details

Retry Job

Retry a failed job. By default the job resumes from the last checkpoint.

POST /jobs/:id/retry

Request Body

Parameter	Type	Required	Description
`from_checkpoint`	`boolean`	No	Resume from the last checkpoint (default: `true`). Pass `false` to restart from scratch.

Example Request

curl -X POST https://api.eazip.io/jobs/550e8400-e29b-41d4-a716-446655440000/retry \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from_checkpoint": true }'

Response

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Only jobs with status: "failed" can be retried.

Download ZIP

Download a completed ZIP. This endpoint does not require an API key — it is protected by the signed URL embedded in download_url.

GET /download/:token

Supports HTTP range requests (Range / If-Range headers) for partial downloads and resumable transfers.

Error Codes

Code	HTTP	Description
`INVALID_REQUEST`	400	Missing or invalid parameters
`PLAN_LIMIT_EXCEEDED`	403	Exceeded URL count or retention limit for your plan
`QUOTA_EXCEEDED`	403	Monthly storage quota exceeded (Free plan: 60 GB-day/month)
`NOT_FOUND`	404	Job doesn’t exist or belongs to another user
`INVALID_REQUEST`	400	Only failed jobs can be retried
`INVALID_TOKEN`	403	Download token is invalid
`EXPIRED_TOKEN`	403	Download token has expired