APIRaptor
Documentation

Developer Documentation

Complete guides, API references, and examples to integrate APIRaptor into your applications.

Download generated OpenAPI 3.1 contract

Quick Start

Start here

First API request

Create an API key in the dashboard, send it in the X-API-Key header from trusted server-side code, choose sync or async mode, then read the JSON result or save the returned file bytes.

1Create an API key in Dashboard -> API Keys.
2Pick a service from API Reference and copy the cURL example.
3Use mode=sync for immediate responses or mode=async for jobs.
4Use the returned file_id with the secure artifact download endpoint, or download_url when direct download is configured.
5Check tokens.consumed and request logs after the call.
Copy and run
curl -X POST "https://apiraptor.com/v1/html-to-pdf" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "sync",
    "html": "<html><body><h1>Hello APIRaptor</h1></body></html>",
    "options": {
      "format": "A4",
      "print_background": true
    }
  }'
Open in PlaygroundManage API keys

Core Concepts

Authentication

Send API calls over HTTPS with X-API-Key: YOUR_API_KEY. API keys sent as Authorization Bearer tokens are not accepted; Bearer is reserved for signed-in access tokens. Keep keys server-side, rotate compromised keys, and use separate keys for environments when possible.

Sync vs async

Use sync for short operations and immediate JSON or small file responses. Use async for heavier work: create a job, poll the job status endpoint, or receive a webhook.

Jobs and webhooks

Async create responses return request_id, job_id, queued/running status, and tokens. Completed jobs expose result metadata; webhooks send async.job.completed or async.job.failed with request_id, job_id, status, tokens, result descriptors, and public error details for failures.

Billing and tokens

APIRaptor reports tokens.consumed from backend metering. Services bill by their service event unit such as pdf_page, image_page or validation event, not by UI display text.

Errors and retries

Handle 400 validation errors before retrying, refresh credentials for 401, top up or change usage for 402, back off on 429, and retry 5xx/timeouts with client-side idempotency safeguards.

Artifacts lifecycle

Generated file artifacts are retained for a maximum of 48 hours. After expiry the secure download endpoint returns an unavailable/expired artifact response and the request should be run again if the result is still needed.

File results and downloads

Four ways to receive a result

Longer async operations return a job first. After the job succeeds, collect the result from the status response and/or webhook, then download any file through the returned delivery mechanism.

Inline structured response

Fast data

Validation, extraction and analysis services return JSON directly when the result is structured data. Read the result object, tokens.consumed and status from the same response.

{
  "status": "succeeded",
  "result": { "valid": true, "confidence": 0.98 },
  "tokens": { "consumed": 12 }
}

Inline file

Small sync file

Synchronous file services can return binary bytes in the same request/response when sync delivery is configured as inline_file. Treat the response body as the file, not JSON.

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: inline; filename="rendered.pdf"

<binary file bytes>

Direct download

Convenient link

When direct_download_link is enabled, APIRaptor returns a signed time-limited URL such as download_url or a result descriptor with delivery=direct_download_link.

{
  "download_url": "https://apiraptor.com/v1/artifacts/signed/..."
}

Secure download

Authorized file download

When secure_api_download is enabled, APIRaptor returns file_id. Download it with GET /v1/artifacts/{artifactId}/download and X-API-Key: YOUR_API_KEY.

curl -X GET "https://apiraptor.com/v1/artifacts/artifact_01HXYZ/download" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output artifact.bin

API Reference

Loading the current public API reference...
Ready to Start?

Start building with APIRaptor

Get your API keys and make your first request in minutes.

Open in PlaygroundView Dashboard