コンテンツにスキップ
Eazip Eazip

Jobs API

このコンテンツはまだ日本語訳がありません。

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

Create Job

Section titled “Create Job”
POST /jobs

Request Body

Section titled “Request Body”
ParameterTypeRequiredDescription
urlsstring[]YesArray of URLs to download. Min 1, max 5,000.
zip_filenamestringNoCustom filename for the ZIP (.zip extension appended automatically). Max 255 characters. Defaults to archive-{id}.zip.
expires_innumberNoSeconds until the ZIP is deleted. Min 300 (5 min), max 5184000 (60 days). Defaults to 24 hours.
fail_on_url_errorbooleanNoIf true (default), the job fails when any URL cannot be fetched. If false, failed URLs are skipped and recorded in errors.
metadataobjectNoUp to 10 key/value pairs (key ≤ 128 chars, value ≤ 1,024 chars) stored with the job.

Plan Limits

Section titled “Plan Limits”
FreePro
Max URLs per job1005,000
Max ZIP size2 GB50 GB
Max retention (expires_in)86,400 s (24 h)5,184,000 s (60 d)

Example Request

Section titled “Example Request”
Terminal window
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

Section titled “Response”

HTTP 201 Created

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

List Jobs

Section titled “List Jobs”
GET /jobs

Uses cursor-based pagination for efficient querying.

Query Parameters

Section titled “Query Parameters”
ParameterTypeDescription
limitnumberResults per page. Default 20, max 100.
cursorstringOpaque cursor from meta.next_cursor in the previous response. Omit for the first page.
statusstringFilter by status: pending, processing, completed, failed.

Example Request

Section titled “Example Request”
Terminal window
curl "https://api.eazip.io/jobs?status=completed&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Section titled “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

Section titled “Get Job”
GET /jobs/:id

Example Request

Section titled “Example Request”
Terminal window
curl https://api.eazip.io/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (completed)

Section titled “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

Section titled “Job Status Values”
StatusDescription
pendingJob created, waiting to start
processingCurrently fetching URLs and building the ZIP
completedZIP file is ready for download
failedJob failed — check errors for details

Retry Job

Section titled “Retry Job”

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

POST /jobs/:id/retry

Request Body

Section titled “Request Body”
ParameterTypeRequiredDescription
from_checkpointbooleanNoResume from the last checkpoint (default: true). Pass false to restart from scratch.

Example Request

Section titled “Example Request”
Terminal window
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

Section titled “Response”
{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

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

Download ZIP

Section titled “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

Section titled “Error Codes”
CodeHTTPDescription
INVALID_REQUEST400Missing or invalid parameters
PLAN_LIMIT_EXCEEDED403Exceeded URL count or retention limit for your plan
QUOTA_EXCEEDED403Monthly storage quota exceeded (Free plan: 60 GB-day/month)
NOT_FOUND404Job doesn’t exist or belongs to another user
INVALID_REQUEST400Only failed jobs can be retried
INVALID_TOKEN403Download token is invalid
EXPIRED_TOKEN403Download token has expired