API Documentation

Convert files programmatically using the GuruPDF REST API.

Getting started

The GuruPDF API lets you convert files programmatically using simple HTTP requests. Here's the quickest path to your first conversion:

Create an account — it's free, no credit card required. You get daily credits immediately.
Go to your profile and generate an API key.
POST a file to /api/v1/convert/{slug} with your Bearer token.
Poll GET /api/v1/conversions/{uuid} until status is completed.
Download via GET /api/v1/conversions/{uuid}/download.

Base URL: /api/v1

Authentication

Include your API token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from the profile page.

Conversion endpoint

POST to /api/v1/convert/{slug} with your file(s) as multipart form data.

Poll the conversion status, then download via the download endpoint.

Idempotency

To retry a conversion safely, send a key you choose in the Idempotency-Key header or the idempotency_key form field. The form field takes up to 64 letters, digits, dots, underscores or hyphens. The header takes any value: one outside those characters is turned into a fixed key, the same one every time, so a retry with the same header still finds the original. A repeat with the same key, files and options returns the original conversion with HTTP 200 and meta.idempotent_replay set to true, and costs nothing. The same key with different files or options is refused with 422 IDEMPOTENCY_KEY_REUSED. If you send both the header and the field, they must match.

Idempotency-Key: invoice-1042-compress

Error codes

Code	HTTP	Description
UNAUTHENTICATED	401	Missing or invalid token
INSUFFICIENT_CREDITS	402	Not enough credits
FORBIDDEN	403	IP not allowed or resource access denied
NOT_FOUND	404	Tool or conversion not found
FILE_TOO_LARGE	413	File exceeds role max size
VALIDATION_ERROR	422	Invalid parameters
IDEMPOTENCY_KEY_REUSED	422	Key reused with different files or options
RATE_LIMIT_EXCEEDED	429	Rate limit hit
CONCURRENCY_LIMIT_EXCEEDED	429	Too many active conversions
CONVERSION_NOT_READY	409	Download before completion

Rate limits

Limits depend on your role/plan. Responses include headers:

X-RateLimit-Limit — requests per window
X-RateLimit-Remaining — remaining in window
X-RateLimit-Reset — Unix timestamp when limit resets
Retry-After — seconds to wait (on 429)

Free: 2/min, 10/day. Paid plans have higher limits. Some tools (e.g. video, OCR) may have lower per-tool limits.

Convert requests per day by plan: Free 10, Starter 200, Professional 1,000, Business 5,000. The limit depends on your plan, not on your credit balance, so buying credits does not raise it. It resets at midnight (America/Toronto).

Credits

Each conversion costs credits. Simple operations (rotate, protect) cost 1; complex ones (PDF to Word, OCR) cost 2–8.

Balance types: daily (free, resets), subscription (monthly), purchased (never expire). Deduction order: daily → subscription → purchased.

Check GET /api/v1/account/balance for your breakdown.

Endpoints reference

All endpoints are relative to /api/v1. Authenticated endpoints require a Bearer token.

Method	Endpoint	Description
POST	/api/v1/convert/{slug}	Convert a file
GET	/api/v1/conversions/{uuid}	Check conversion status
GET	/api/v1/conversions/{uuid}/download	Download converted file
GET	/api/v1/conversions	List your conversions
GET	/api/v1/tools	List all tools
GET	/api/v1/tools/{slug}	Get tool details
GET	/api/v1/account	Account info
GET	/api/v1/account/balance	Credit balance
GET	/api/v1/account/usage	Usage statistics
GET	/api/v1/account/transactions	Transaction history
GET	/api/v1/plans	Available plans
GET	/api/v1/health	API health check

Workflow example

A typical conversion follows three steps: upload, poll, and download.

Step 1 — Submit a file for conversion

POST your file as multipart form data to the conversion endpoint.

curl -X POST /api/v1/convert/compress-pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files[][email protected]"

Response:

JSON

{
  "success": true,
  "data": {
    "conversions": [
      {
        "uuid": "abc-123",
        "status": "pending"
      }
    ]
  },
  "meta": {
    "credits_remaining": 7,
    "rate_limit": { "limit": 2, "remaining": 1, "reset": 1720000000 }
  }
}

Step 2 — Poll for status

Use the UUID from Step 1 to check conversion status. Poll every few seconds until status is completed or failed.

curl /api/v1/conversions/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

JSON

{
  "success": true,
  "data": {
    "uuid": "abc-123",
    "status": "completed",
    "download_url": "/api/v1/conversions/abc-123/download"
  }
}

Step 3 — Download the result

Once the status is completed, fetch the converted file from the download URL.

curl -OJ /api/v1/conversions/abc-123/download \
  -H "Authorization: Bearer YOUR_API_KEY"

The response streams the file with appropriate Content-Disposition headers.

Available tools