API Reference

Everything you need to integrate document processing into your application. The REST API uses JSON for request/response bodies and standard HTTP status codes.

Base URLhttps://your-domain.com/api/v1

Authentication

Most endpoints require an API key. Generate one from Settings → API Keys in your organization dashboard.

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-domain.com/api/v1/credits/balance

Templates

Browse available document templates.

GET/api/v1/templatesNone

List all active document templates. Optionally filter by category.

Parameters

Name	Type	Required	Description
`category`	string	Optional	Filter by template category

Response

{
  "categories": ["Legal", "Finance", "Marketing"],
  "templates": [
    {
      "id": "clx...",
      "name": "Invoice Template",
      "description": "Professional invoice template",
      "category": "Finance",
      "pageCount": 2,
      "creditCost": 2,
      "thumbnailKey": "templates/thumb-123.png"
    }
  ]
}

Jobs

Submit and manage document processing jobs.

POST/api/v1/jobsAPI Key

Submit a new document processing job. Deducts credits automatically.

Request Body

Field	Type	Required	Description
`templateId`	string	Required	The template to use (CUID2 format)
`editPrompt`	string	Required	Instructions for document editing (10-2000 chars)
`targetPages`	number[]	Optional	Specific pages to edit (defaults to all)

Response

{
  "job": {
    "id": "clx...",
    "status": "pending"
  }
}

GET/api/v1/jobsAPI Key

List jobs for the authenticated organization with cursor-based pagination.

Parameters

Name	Type	Required	Description
`cursor`	string	Optional	Cursor for pagination (job ID)
`limit`	number	Optional	Results per page (default: 20, max: 100)

Response

{
  "jobs": [
    {
      "id": "clx...",
      "status": "completed",
      "createdAt": "2025-01-15T10:30:00Z",
      "templateName": "Invoice Template",
      "creditsCharged": 2,
      "errorMessage": null
    }
  ],
  "nextCursor": "clx..."
}

GET/api/v1/jobs/:jobIdAPI Key

Get detailed information about a specific job, including download URL if completed.

Parameters

Name	Type	Required	Description
`jobId`	string	Required	The job ID

Response

{
  "job": {
    "id": "clx...",
    "status": "completed",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:31:00Z",
    "templateName": "Invoice Template",
    "creditsCharged": 2,
    "downloadUrl": "https://...",
    "errorMessage": null
  }
}

Credits

Check balance and purchase credit packs.

GET/api/v1/credits/balanceAPI Key

Get the current credit balance for the authenticated organization.

Parameters

Name	Type	Required	Description
`includeTransactions`	boolean	Optional	Include recent transactions in response

Response

{
  "balance": 47,
  "transactions": [
    {
      "id": "clx...",
      "amount": 50,
      "description": "Purchased 50 credits",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

POST/api/v1/credits/purchaseAPI Key

Create a Stripe checkout session to purchase a credit pack.

Request Body

Field	Type	Required	Description
`packId`	string	Required	Credit pack ID: "pack10", "pack50", or "pack100"

Response

{
  "checkoutUrl": "https://checkout.stripe.com/..."
}

Crypto Payments

Purchase credits using cryptocurrency.

POST/api/v1/crypto/checkoutAPI Key

Create a crypto payment checkout for credit purchase.

Request Body

Field	Type	Required	Description
`packId`	string	Required	Credit pack ID
`chain`	string	Required	Blockchain (e.g., "ethereum", "polygon")
`token`	string	Required	Token symbol (e.g., "USDC", "USDT")

Response

{
  "paymentId": "clx...",
  "depositAddress": "0x...",
  "amount": "10.00",
  "token": "USDC",
  "chain": "polygon",
  "expiresAt": "2025-01-15T11:00:00Z"
}

Files

Access template thumbnails and job output files.

GET/api/v1/files/:bucket/:keySigned URL

Download a file. Template files are public. Output files require a signed URL (provided in job detail response).

Parameters

Name	Type	Required	Description
`bucket`	string	Required	Bucket name: "templates" or "outputs"
`key`	string	Required	File key (URL-encoded)
`download`	boolean	Optional	Force download instead of inline display

Response

Binary file content with appropriate Content-Type header

Webhooks

Configure webhook endpoints in Settings → Webhooks to receive real-time notifications when job status changes. All payloads are signed with HMAC-SHA256.

Events

Event	Description
`job.processing`	Fired when a job begins processing.
`job.completed`	Fired when a job finishes successfully. Includes output key.
`job.failed`	Fired when a job fails. Includes error message.

Payload Example

{
  "event": "job.completed",
  "timestamp": "2025-01-15T10:31:00Z",
  "data": {
    "id": "clx...",
    "organizationId": "clx...",
    "templateId": "clx...",
    "status": "completed",
    "outputKey": "outputs/clx...pdf",
    "creditsCharged": 2,
    "processingTimeSeconds": 12.5
  }
}

Signature Verification

Each webhook includes an X-Webhook-Signature header. Verify it using HMAC-SHA256 with your webhook secret:

import { createHmac } from "crypto";

function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return signature === expected;
}

Error Codes

All errors return a JSON body with an error field describing the issue.

Code	Description
400	Bad Request - Invalid parameters or request body
401	Unauthorized - Missing or invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
409	Conflict - Duplicate request (idempotency)
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error