API reference
Data processing
The extraction stack behind our own products, exposed as an endpoint. Send a PDF, a scan, or a pile of supplier filings and get back structured data with the document's shape intact — tables reconstructed cell by cell, merged headers preserved, multi-column layouts kept in reading order, and every value traceable to the page it came from.
REST server
https://api.belumind.comMCP server
https://mcp.belumind.com/data-processingAuthentication
Every request carries a bearer token. Keys are scoped — an endpoint returns 403 if the calling key lacks the scope named in its reference entry, so an agent can be handed a key that reaches exactly one tool and nothing else.
MCP clients pass the same token as a bearer credential when connecting to the server URL above.
documents:readAuthorization: Bearer blm_live_7f3c… Content-Type: application/json
/v1/documents/parsedocuments:readParse a document into structured JSON
Reads a document and returns its content as structured blocks — paragraphs, headings, and tables — with the reading order and table geometry preserved. Scanned pages are OCR'd automatically when no text layer is present.
parse_documentBody parameters
urlstringrequired- Publicly reachable URL of the document. Use `file` instead to upload bytes directly.
mode"fast" | "accurate"optional- Accuracy/latency trade-off. Defaults to `accurate`, which runs full table reconstruction.
pagesstringoptional- Page range to process, e.g. "1-5". Omit to process the whole document.
include_provenancebooleanoptional- Return the page and bounding box each value was read from. Defaults to true.
Responses
200 OKSuccess. Body as shown in the example.400 Bad RequestThe request body failed validation. The response names the offending field.401 UnauthorizedMissing, malformed, or revoked API key.403 ForbiddenThe key is valid but lacks the scope this endpoint requires.429 Too Many RequestsRate limit exceeded. `Retry-After` carries the seconds to wait; usage is readable from /v1/usage.500 Internal Server ErrorSomething failed on our side. Requests are idempotent by `Idempotency-Key`, so a retry is safe.
Request
curl -X POST https://api.belumind.com/v1/documents/parse \ -H "Authorization: Bearer $BELUMIND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/annual-report.pdf", "mode": "accurate", "pages": "1-5", "include_provenance": true }'
Response
{
"document_id": "doc_9f2c41a7",
"page_count": 5,
"blocks": [
{
"type": "heading",
"level": 1,
"text": "Consolidated Financial Statements",
"page": 1
},
{
"type": "table",
"page": 2,
"rows": 14,
"columns": 6,
"cells": [
{
"row": 0,
"column": 0,
"text": "Segment",
"is_header": true,
"row_span": 2
},
{
"row": 0,
"column": 1,
"text": "FY2025",
"is_header": true,
"column_span": 2
}
],
"provenance": {
"page": 2,
"bbox": [
72,
310,
523,
604
]
}
}
],
"usage": {
"pages_processed": 5
}
}Try it
Send a request
Sample modePOST https://api.belumind.com/v1/documents/parseThe platform is in early access, so this console returns the documented example response rather than calling a live endpoint. Ask us for a key and the same console starts issuing real requests.
/v1/documents/extractdocuments:readExtract named fields against a schema
Pulls specific values out of a document using a JSON Schema you supply. Each field comes back with a confidence score and the location it was read from, so a low-confidence value can be routed to review rather than trusted silently.
extract_fieldsBody parameters
urlstringrequired- Publicly reachable URL of the document.
schemaobjectrequired- JSON Schema describing the fields to extract. Nested objects and arrays are supported.
min_confidencenumberoptional- Fields scoring below this are returned as null with a `needs_review` flag. Defaults to 0.
Responses
200 OKSuccess. Body as shown in the example.400 Bad RequestThe request body failed validation. The response names the offending field.401 UnauthorizedMissing, malformed, or revoked API key.403 ForbiddenThe key is valid but lacks the scope this endpoint requires.429 Too Many RequestsRate limit exceeded. `Retry-After` carries the seconds to wait; usage is readable from /v1/usage.500 Internal Server ErrorSomething failed on our side. Requests are idempotent by `Idempotency-Key`, so a retry is safe.
Request
curl -X POST https://api.belumind.com/v1/documents/extract \ -H "Authorization: Bearer $BELUMIND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/supplier-esg-report.pdf", "schema": { "type": "object", "properties": { "reporting_year": { "type": "integer" }, "scope_1_emissions": { "type": "number" }, "scope_2_emissions": { "type": "number" }, "assurance_provider": { "type": "string" } } }, "min_confidence": 0.7 }'
Response
{
"document_id": "doc_3b81ee20",
"fields": {
"reporting_year": {
"value": 2025,
"confidence": 0.99,
"page": 1
},
"scope_1_emissions": {
"value": 128450,
"confidence": 0.94,
"page": 12
},
"scope_2_emissions": {
"value": 63120.5,
"confidence": 0.91,
"page": 12
},
"assurance_provider": {
"value": null,
"confidence": 0.42,
"needs_review": true
}
},
"usage": {
"pages_processed": 34
}
}Try it
Send a request
Sample modePOST https://api.belumind.com/v1/documents/extractThe platform is in early access, so this console returns the documented example response rather than calling a live endpoint. Ask us for a key and the same console starts issuing real requests.
Errors
Errors use conventional HTTP status codes and always carry a machine-readable code alongside the human-readable message, so a client can branch on the former and log the latter. Every request is idempotent by Idempotency-Key, which makes retrying a 5xx safe.
{
"error": {
"code": "invalid_parameter",
"message": "`min_confidence` must be between 0 and 1.",
"param": "min_confidence",
"request_id": "req_4d91c0b7"
}
}Ready to call it for real?
The console returns documented examples while the platform is in early access. Tell us what you are building and we will get you a key.