The TrueParser API is a REST-based service that handles document ingestion, status tracking, and result retrieval. All protected endpoints require a Bearer JWT issued by the TrueParser Dashboard.
Base URL
The TrueParser API uses a single production endpoint for all traffic.
| Environment | URL |
|---|
| Production | https://api.trueparser.com |
Authentication
Authentication is handled via the Authorization: Bearer <JWT> header.
Public Endpoints
The following endpoints do not require a security token:
GET /health/liveGET /health/readyGET /health/node-stateGET /openapi/v1.json
Document Parsing
Ingest Document
POST /api/v1/documents/parse
Submit a document for asynchronous parsing. This endpoint supports multipart/form-data.
Request Parameters
| Field | Type | Required | Description |
|---|
file | Binary | Yes | The document to be parsed. |
documentId | String | No | A custom identifier. If provided, used for idempotency/overwrites. |
documentType | String | No* | The format (e.g., Pdf, ShpZip, MapInfo, FileGdb). Required for ZIP uploads. |
csvRoute | String | No | Must be Gis or Office if the document is a CSV. |
sqlDialect | String | No | Required for SQL files (e.g., PostgreSql, TSql, Snowflake). |
pdfMode | String | No | Required for PDF (e.g., Fast, Standard, Advanced). |
customMetadataJson | JSON | No | A JSON object of key-value pairs to attach to the job. |
Response (202 Accepted)
{
"documentId": "7b1c0d8c-...",
"status": "queued"
}
Lifecycle & Results
Check Status
GET /api/v1/documents/{documentId}/status
Returns the current processing state of the job.
Status Values
queued: Waiting in the orchestration queue.processing: The engine is actively extracting data.completed: Result is ready for retrieval.failed: Extraction failed. See the error field in the response.
Response (200 OK)
{
"status": "completed",
"startedAt": "2024-03-20T10:00:00Z",
"completedAt": "2024-03-20T10:00:05Z"
}
Retrieve Result
GET /api/v1/documents/{documentId}/result
Streams the final, materialized JSON artifact directly.
Response Behaviors
- 200 OK: Returns the parsed JSON file as
application/json.
- 202 Accepted: Document is still processing. Poll the status endpoint again.
- 422 Unprocessable Entity: The extraction failed. The body contains the specific error reason.
- 404 Not Found: The document ID is invalid or the artifact has expired (3-hour default retention).
Health & Monitoring
Readiness Probe
GET /health/ready
Checks if the node is ready to accept traffic.
- Status Checks: Currently verifies Redis connectivity and registry initialization.
Node State
GET /health/node-state
Returns high-granularity telemetry for the specific node, including CPU, memory, and active request counts. Used primarily for load balancer routing decisions.
Common Error Codes
| Error Code | HTTP | Description |
|---|
missing_token | 401 | No Bearer token provided in the Authorization header. |
token_expired | 401 | The provided JWT has expired. |
domain_not_allowed | 403 | The request Origin/Referer is not in the App’s allowed domain list. |
quota_exceeded | 429 | Document unit quota reached for the current billing window. |
document_too_large | 413 | The file exceeds the maximum allowed size for your plan. |
extraction_failed | 422 | The parser engine encountered an unrecoverable error. |
Last modified on April 1, 2026
