API Reference

API & Authentication

The Ragify REST API gives you full programmatic access to every feature available in the web UI. Available on Pro and Business plans.

Base URL

https://api.ragify.it

All endpoints use HTTPS. The API is RESTful and speaks JSON for structured responses. File uploads use multipart/form-data.

Authentication methods

The API supports two authentication methods. Both work on all endpoints.

Method 1 — API Key (recommended for automation)

Create an API key from Account → API Keys. Pass it in the X-Api-Key header on every request.

bash

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

Keys start with rg_ followed by 40 hex characters
Pro accounts: up to 3 active keys
Business accounts: up to 10 active keys
Each key shows last used timestamp in Account settings
Keys can be revoked individually at any time
Revoked keys return 401 Unauthorized immediately

⚠ Warning

API keys are shown only once at creation. Store them in a secrets manager (e.g. GitHub Secrets, AWS Secrets Manager, .env file) immediately. If you lose a key, revoke it and create a new one.

Method 2 — Session token (for browser-based clients)

If you are building a frontend application that uses Clerk for authentication, you can use the Clerk session JWT as a Bearer token.

javascript

// Get token from Clerk session
const token = await window.Clerk.session.getToken();

const response = await fetch('https://api.ragify.it/jobs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
  body: formData,
});

◆ Note

Bearer token authentication is intended for browser-based apps only. For scripts, pipelines, and server-to-server calls, always use API keys.

Managing API keys

Create a key

bash

# You can also create keys via the API itself (using an existing key or Bearer token)
curl -X POST https://api.ragify.it/api-keys \
  -H "X-Api-Key: rg_existing_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production pipeline"}'

json

{
  "id": "a1b2c3d4-...",
  "name": "Production pipeline",
  "key_prefix": "rg_4a9f1c2e",
  "raw_key": "rg_4a9f1c2e3b7d8a6f...",
  "is_active": true,
  "created_at": "2026-05-14T10:00:00Z",
  "last_used_at": null
}

⚠ Warning

The raw_key field is only present in the creation response. It is not stored and cannot be retrieved later. Copy it immediately.

List keys

bash

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

Revoke a key

bash

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

Error responses

Status	Meaning
200 OK	Request succeeded
201 Created	Resource created (POST /jobs, POST /api-keys)
204 No Content	Deletion successful
400 Bad Request	Invalid input — check the detail field
401 Unauthorized	Missing or invalid authentication
402 Payment Required	Monthly page limit reached — upgrade or wait for reset
403 Forbidden	Feature not available on your plan
404 Not Found	Job or key not found (or belongs to another user)
413 Payload Too Large	File exceeds your plan's size limit
429 Too Many Requests	Too many concurrent jobs — wait for current jobs to finish

Error responses always include a detail field:

json

{
  "detail": {
    "message": "This PDF has 15 pages but you only have 3 pages remaining this month.",
    "pdf_pages": 15,
    "pages_remaining": 3,
    "pages_used": 47,
    "pages_limit": 50,
    "tier": "free"
  }
}

Rate limiting

There is no time-based rate limit. Instead, Ragify enforces a concurrent job limit per account:

Free: max 2 simultaneous jobs
Pro: max 5 simultaneous jobs
Business: max 20 simultaneous jobs

When you exceed the limit, POST /jobs returns 429 with a message indicating how many jobs are currently active. Wait for one to complete before submitting another.

Endpoint reference →Integration examples