Planet OCR API
API Documentation

Planet OCR API

Extract text and structure from documents with a simple REST API. Upload a file, submit an OCR job, and poll for results — authenticated with API keys.

Base URL
https://devbackend.planetocr.ai
Recommended version
/api/v2

Quickstart

Four steps to extracted text

From zero to a parsed document with copy-paste curl commands.

  1. 1

    Create an API key

    Sign in and open the Dashboard to generate a key. Keys start with ocr_ and are shown only once.

    Open Dashboard
  2. 2

    Upload a document

    POST your file to /api/v2/documents/. Save the returned doc_… id.

    bash
    curl -X POST "https://devbackend.planetocr.ai/api/v2/documents/" \
  -H "x-api-key: $PLANET_OCR_API_KEY" \
  -F "file=@./invoice.pdf"
  3. 3

    Submit an OCR job

    Reference the document id and a model (asteroid, quasar, pulsar, or magnetar). Processing is asynchronous.

    bash
    curl -X POST "https://devbackend.planetocr.ai/api/v2/ocr/jobs/" \
  -H "x-api-key: $PLANET_OCR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "doc_…", "model": "quasar"}'
  4. 4

    Poll for results

    GET the job until status is completed. Results include extracted text and layout.

    bash
    curl "https://devbackend.planetocr.ai/api/v2/ocr/jobs/job_…/" \
  -H "x-api-key: $PLANET_OCR_API_KEY"

Authentication

API keys & JWT tokens

Secure every request with an API key or Bearer token.

All production endpoints use API keys. Pass your key via the x-api-key header or as a Bearer token. Create and revoke keys in the Dashboard.

http·Header
x-api-key: ocr_your_secret_key

# or
Authorization: Bearer ocr_your_secret_key

Key scopes

  • ocr:writesubmit jobs and upload documents
  • ocr:readretrieve job status and results

Dashboard account endpoints (usage, key management) require a JWT from sign-in.

Responses

Consistent envelopes, structured errors

Every v2 response wraps its payload in the same shape, with a request id.

Success envelope (v2)

json
{
  "object": "ocr_job",
  "id": "job_660e8400-e29b-41d4-a716-446655440001",
  "created_at": "2026-06-12T10:00:00+00:00",
  "request_id": "abc123def456",
  "data": {
    "status": "completed",
    "pages_processed": 2,
    "result": { "text": "…", "layout": {} }
  }
}

Error response

json
{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly page quota exceeded",
  "request_id": "abc123def456"
}

Resource ids use prefixes: doc_ for documents, job_ for OCR jobs.

API Reference

Endpoints

12 endpoints for production integrations.

Models

Discover available OCR tiers before submitting jobs.

GET/api/v2/models/API key

List models

Catalog of models for API-key OCR (`asteroid`, `quasar`, `pulsar`, `magnetar`). Not filtered by subscription tier.

bash·Example request
curl -X GET "https://devbackend.planetocr.ai/api/v2/models/" \
  -H "x-api-key: $PLANET_OCR_API_KEY"

Documents

Upload and manage source files for OCR processing.

POST/api/v2/documents/API key

Upload document

Upload a PDF or image. Returns a prefixed document id (`doc_…`).

bash·Example request
curl -X POST "https://devbackend.planetocr.ai/api/v2/documents/" \
  -H "x-api-key: $PLANET_OCR_API_KEY" \
  -F "file=@./document.pdf"
GET/api/v2/documents/API key

List documents

Paginated list of documents uploaded by your account.

bash·Example request
curl -X GET "https://devbackend.planetocr.ai/api/v2/documents/" \
  -H "x-api-key: $PLANET_OCR_API_KEY"
GET/api/v2/documents/{document_id}/API key

Retrieve document

Metadata for a single document by id or prefixed `doc_` id.

bash·Example request
curl -X GET "https://devbackend.planetocr.ai/api/v2/documents/example_id/" \
  -H "x-api-key: $PLANET_OCR_API_KEY"

OCR Jobs

Submit jobs asynchronously and poll for structured results.

POST/api/v2/ocr/jobs/API key

Create OCR job

Submit asynchronous OCR processing. API keys must pass `model` (asteroid, quasar, pulsar, or magnetar). Requires `ocr:write` scope. Returns `job_…` id.

bash·Example request
curl -X POST "https://devbackend.planetocr.ai/api/v2/ocr/jobs/" \
  -H "x-api-key: $PLANET_OCR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "doc_example", "model": "quasar"}'
GET/api/v2/ocr/jobs/{job_id}/API key

Retrieve OCR job

Poll job status and fetch results when complete. Requires `ocr:read` scope.

bash·Example request
curl -X GET "https://devbackend.planetocr.ai/api/v2/ocr/jobs/example_id/" \
  -H "x-api-key: $PLANET_OCR_API_KEY"

Account

Manage API keys, usage, and job history (dashboard / JWT).

POST/api/v1/dashboard/api-keys/Bearer token

Create API key

Generate a new API key. The full key is returned once — store it securely. JWT required.

bash·Example request
curl -X POST "https://devbackend.planetocr.ai/api/v1/dashboard/api-keys/" \
  -H "Authorization: Bearer $PLANET_OCR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
GET/api/v1/dashboard/api-keys/Bearer token

List API keys

List active and revoked keys (prefix only, never the secret). JWT required.

bash·Example request
curl -X GET "https://devbackend.planetocr.ai/api/v1/dashboard/api-keys/" \
  -H "Authorization: Bearer $PLANET_OCR_ACCESS_TOKEN"
POST/api/v1/dashboard/api-keys/{key_id}/revoke/Bearer token

Revoke API key

Immediately invalidate an API key. JWT required.

bash·Example request
curl -X POST "https://devbackend.planetocr.ai/api/v1/dashboard/api-keys/example_id/revoke/" \
  -H "Authorization: Bearer $PLANET_OCR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
GET/api/v1/dashboard/usage/Bearer token

Usage & quota

Current plan, quota consumed, and jobs this billing period. JWT required.

bash·Example request
curl -X GET "https://devbackend.planetocr.ai/api/v1/dashboard/usage/" \
  -H "Authorization: Bearer $PLANET_OCR_ACCESS_TOKEN"
GET/api/v1/dashboard/jobs/Bearer token

Job history

Recent OCR jobs for your account. JWT required.

bash·Example request
curl -X GET "https://devbackend.planetocr.ai/api/v1/dashboard/jobs/" \
  -H "Authorization: Bearer $PLANET_OCR_ACCESS_TOKEN"

Status

Platform health and availability.

GET/api/v1/status/No auth

Service status

Returns platform version, uptime, and overall health. No authentication required.

bash·Example request
curl -X GET "https://devbackend.planetocr.ai/api/v1/status/"