API Reference

Endpoint reference

Complete reference for all Ragify API endpoints. Base URL: https://api.ragify.it

Jobs

Submit a job

POST/jobs

Submit a PDF for parsing. The job is queued and processed asynchronously. Returns the job object immediately with status: pending.

Content-Type: multipart/form-data

Parameter	Type	Default	Description
file*	file	—	The PDF file to parse. Must be a valid PDF (magic bytes %PDF-). Size limits: Free 25 MB, Pro 150 MB, Business unlimited.
options	string (JSON)	{}	JSON-encoded parser options. See the Parser options page for all available fields.

bash

curl -X POST https://api.ragify.it/jobs \
  -H "X-Api-Key: rg_..." \
  -F "file=@document.pdf" \
  -F 'options={"format":["markdown","json"],"reading_order":"xycut"}'

json

// Response — 201 Created
{
  "id": "3f8a1c2d-4b5e-6f7a-8b9c-0d1e2f3a4b5c",
  "user_id": "usr_abc123",
  "status": "pending",
  "options": {
    "format": ["markdown", "json"],
    "reading_order": "xycut",
    "table_method": "default",
    ...
  },
  "page_count": null,
  "error_message": null,
  "created_at": "2026-05-14T10:00:00Z",
  "updated_at": "2026-05-14T10:00:00Z",
  "download_urls": {}
}

List jobs

GET/jobs

Return a paginated list of your jobs, most recent first.

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed).
page_size	integer	20	Jobs per page. Maximum 100.

bash

curl "https://api.ragify.it/jobs?page=1&page_size=10" \
  -H "X-Api-Key: rg_..."

json

{
  "items": [ { "id": "...", "status": "done", ... } ],
  "total": 42,
  "page": 1,
  "page_size": 10
}

Get a job

GET/jobs/{id}

Return a single job by ID. Poll this endpoint until status is done or failed.

bash

curl "https://api.ragify.it/jobs/3f8a1c2d-..." \
  -H "X-Api-Key: rg_..."

json

{
  "id": "3f8a1c2d-...",
  "status": "done",
  "page_count": 12,
  "error_message": null,
  "download_urls": {
    "markdown": "https://signed-url.r2.example/...",
    "json":     "https://signed-url.r2.example/..."
  },
  "created_at": "2026-05-14T10:00:00Z",
  "updated_at": "2026-05-14T10:00:05Z"
}

Job status values

Status	Meaning
pending	Job is queued, waiting for a worker
processing	Worker is actively converting the PDF
done	Conversion complete. download_urls populated.
failed	Conversion failed. Check error_message for details.

Delete a job

DELETE/jobs/{id}

Delete a job and all associated files from R2 storage immediately. Returns 204 No Content.

bash

curl -X DELETE "https://api.ragify.it/jobs/3f8a1c2d-..." \
  -H "X-Api-Key: rg_..."

Download output

GET/jobs/{id}/download/{fmt}

Stream an output file directly. The file is proxied from R2 — no separate signed URL handling required.

Parameter	Type	Default	Description
fmt*	string	—	Format to download. One of: "markdown", "json", "html", "text", "tagged-pdf", "annotated-pdf", "images". Must be in the job's output_keys.

bash

# Download and save to file
curl -o output.md "https://api.ragify.it/jobs/3f8a1c2d-.../download/markdown" \
  -H "X-Api-Key: rg_..."

# Pipe directly into another command
curl -s "https://api.ragify.it/jobs/3f8a1c2d-.../download/json" \
  -H "X-Api-Key: rg_..." | jq '.kids[] | select(.type=="table")'

Auth

Get current user

GET/auth/me

Return your account details: tier, pages used, and billing status.

bash

curl https://api.ragify.it/auth/me \
  -H "X-Api-Key: rg_..."

json

{
  "id": "usr_internal_uuid",
  "email": "you@example.com",
  "tier": "pro",
  "pages_used": 127,
  "pages_limit": 500,
  "created_at": "2026-01-01T00:00:00Z"
}

API Keys

List API keys

GET/api-keys

bash

curl https://api.ragify.it/api-keys \
  -H "X-Api-Key: rg_..."

json

[
  {
    "id": "a1b2c3...",
    "name": "n8n workflow",
    "key_prefix": "rg_4a9f1c2e",
    "is_active": true,
    "created_at": "2026-05-01T09:00:00Z",
    "last_used_at": "2026-05-14T08:32:10Z"
  }
]

Create an API key

POST/api-keys

Parameter	Type	Default	Description
name*	string	—	Human-readable label for this key. 1–64 characters.

bash

curl -X POST https://api.ragify.it/api-keys \
  -H "X-Api-Key: rg_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"My automation script"}'

Revoke an API key

DELETE/api-keys/{key_id}

bash

curl -X DELETE "https://api.ragify.it/api-keys/a1b2c3..." \
  -H "X-Api-Key: rg_..."

Health check

GET/health

Returns {"status":"ok"} if the API is operational. No authentication required. Suitable for uptime monitoring.