Introduction
The ParseGrid API converts unstructured documents — PDFs, scans, screenshots — into structured JSON.
All requests must be made over HTTPS. Calls to plain HTTP are rejected.
The API is versioned by URL prefix (/v1). Breaking
changes are released under a new prefix; non-breaking additions ship inside the current
version with backward compatibility.
Authentication
Authenticate every request with a bearer token. Your API key is issued the moment you purchase a plan — it's emailed to you and available any time in your customer portal. Treat it as a secret.
Requests missing or carrying an invalid token return 401 Unauthorized. Rotate tokens regularly; the dashboard supports overlapping active tokens to enable
zero-downtime rotation.
| Scope | Access | Description |
|---|---|---|
| extract | read/write | Submit documents and retrieve results. |
| admin | read/write | Manage project settings, models, and usage. |
| readonly | read | Retrieve results and metrics; cannot submit jobs. |
Errors
ParseGrid uses standard HTTP status codes. Successful requests return 2xx; client mistakes return 4xx; server issues return 5xx. Every error response includes a machine-readable code and
a human-readable message.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request payload is malformed or missing required fields. |
| 401 | unauthorized | The Authorization header is absent or the token is invalid. |
| 404 | not_found | The referenced job, document, or project does not exist. |
| 413 | payload_too_large | The document exceeds the 25MB upload limit. |
| 429 | rate_limited | You have exceeded your plan's per-second rate limit. |
| 500 | internal_error | An unexpected server-side failure. Please retry with backoff. |
Parse Document
Submit an unstructured document (PDF, PNG, or JPG) to the extraction engine. ParseGrid will perform layout analysis, OCR, and table reconstruction to return structured JSON data.
| Parameter | Type | Description |
|---|---|---|
| file | binary | The document file to be parsed. Max size 25MB. |
| model_id | string | Optional. Specify a custom-trained model for extraction. |
| ocr_engine | string | Choose between standard or high_res. |
Our engine supports complex grid detection and nested data hierarchies. By default, the engine attempts to classify the document type and apply relevant schema mapping.