Files & Jobs

Overview

The Files API lets you stage files before processing, list your output files, and download results. The Jobs API lets you poll the status of asynchronous operations.

Auth required: All endpoints require authentication.

---

File Staging

Upload a file to temporary storage for use in subsequent operations. Staged files expire after 30 minutes.

POST /api/v1/files/stage
Content-Type: multipart/form-data

Parameter	Type	Required	Description
file	binary	Yes	PDF, JPEG, PNG, or WebP file

Example

curl -X POST https://api.pdflys.com/api/v1/files/stage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"

Response

{
  "success": true,
  "data": {
    "fileId": "staging/abc123.pdf",
    "expiresAt": "2026-02-25T10:30:00.000Z"
  }
}

---

Output Files

List Your Files

Get a paginated list of your processed output files.

GET /api/v1/files/mine

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Items per page (max 100)

Example

curl "https://api.pdflys.com/api/v1/files/mine?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "files": [
      {
        "id": 1,
        "fileKey": "output/user/1/abc123.pdf",
        "contentType": "application/pdf",
        "sizeBytes": 1048576,
        "createdAt": "2026-02-25T10:00:00.000Z",
        "expiresAt": "2026-02-25T11:00:00.000Z"
      }
    ],
    "page": 1,
    "limit": 10,
    "hasMore": true
  }
}

Get Download URL

Generate a fresh presigned download URL for one of your files.

POST /api/v1/files/mine/download
Content-Type: application/json

Parameter	Type	Required	Description
fileKey	string	Yes	The fileKey from the file listing

Example

curl -X POST https://api.pdflys.com/api/v1/files/mine/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileKey":"output/user/1/abc123.pdf"}'

Response

{
  "success": true,
  "data": {
    "fileKey": "output/user/1/abc123.pdf",
    "url": "https://storage.pdflys.com/output/..."
  }
}

Direct File Download

Download a file directly by its file key. Returns the raw file with appropriate Content-Type and Content-Disposition headers.

GET /api/v1/files/{fileKey}

curl https://api.pdflys.com/api/v1/files/output/user/1/abc123.pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o result.pdf

---

Job Status

When a PDF operation runs asynchronously (file >= 5 MB), it returns a jobId. Use this endpoint to poll for completion.

GET /api/v1/jobs/:jobId

Example

curl https://api.pdflys.com/api/v1/jobs/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (Completed — Single File)

{
  "success": true,
  "data": {
    "jobId": "abc-123",
    "status": "completed",
    "result": {
      "fileId": "output/user/1/result.pdf",
      "url": "https://storage.pdflys.com/output/..."
    }
  }
}

Response (Completed — Multiple Files)

For operations like split or pdf-to-image that produce multiple outputs:

{
  "success": true,
  "data": {
    "jobId": "abc-123",
    "status": "completed",
    "result": {
      "files": [
        {
          "fileId": "output/user/1/split-1.pdf",
          "name": "split-1.pdf",
          "url": "https://storage.pdflys.com/output/..."
        },
        {
          "fileId": "output/user/1/split-2.pdf",
          "name": "split-2.pdf",
          "url": "https://storage.pdflys.com/output/..."
        }
      ]
    }
  }
}

Response (Failed)

{
  "success": true,
  "data": {
    "jobId": "abc-123",
    "status": "failed",
    "error": "PDF is password-protected"
  }
}

Job Status Values

Status	Description
queued	Job accepted, waiting to start
active	Job is being processed
completed	Processing finished — result field contains output
failed	Processing failed — error field contains reason

---

Health Check

Check API service availability. No authentication required.

GET /health

Response

{
  "status": "healthy",
  "timestamp": "2026-02-25T10:00:00.000Z"
}

Returns 200 when healthy, 503 when degraded.