API reference / Document AI
Read document → JSON
Any financial file/email → structured JSON via the structured→template→OCR→LLM ladder, with per-field confidence + provenance.
POST
/v1/read/document- Authentication
- Bearer token
- Scope
read:document
Before you integrate
- If the file cannot be read, the call fails and is refunded.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
filename | string | Yes | Name of the file, 1 to 255 characters; the extension helps identify the type. |
content_type | string | No | MIME type of the file, for example text/csv or application/pdf. Defaults to application/octet-stream. |
content_base64 | string | Yes | The file contents, base64-encoded. Must not be empty and must decode to at most 15 MiB. |
declared_type | string | No | What you expect the document to be, if you know. It guides the reader. |
Sample code
Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.
curl -sS -X POST 'https://grappi.ai/v1/read/document' \
-H "Authorization: Bearer $GRAPPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filename": "statement.csv",
"content_type": "text/csv",
"content_base64": "RGF0ZSxOYXJyYXRpb24sV2l0aGRyYXdhbCxEZXBvc2l0LENsb3NpbmcgQmFsYW5jZQowMS8wNC8yMDI0LE9wZW5pbmcsLCwxMDAwMC4wMAowMi8wNC8yMDI0LFVQSSBQYXltZW50LDE1MDAuMDAsLDg1MDAuMDAKMDMvMDQvMjAyNCxTYWxhcnkgQ3JlZGl0LCw1MDAwMC4wMCw1ODUwMC4wMAo="
}'Sample response
{
"request_id": "req_01HZY3K8M2",
"result": {
"document_type": "bank_statement",
"issuer": null,
"review_required": false,
"overall_confidence": 0.95,
"fields": {
"source_filename": {
"value": "statement.csv",
"confidence": 1
}
},
"transactions": [],
"warnings": [],
"tiers_used": [
"structured"
]
}
}Response fields
| Field | Type | Description |
|---|---|---|
document_type | string | The kind of document found, for example bank_statement. |
issuer | string | The institution that issued the document, or null when unknown. |
review_required | boolean | True when the reading is uncertain and a person should check it. |
overall_confidence | number | Confidence in the whole reading, from 0 to 1. |
fields | object | The extracted values, keyed by field name; each has a value and a confidence from 0 to 1. |
transactions | array | Transactions found in the document, in the order they appear. |
warnings | array | Plain-language notes about anything that could not be read. |
tiers_used | array | The reading methods applied to this document, in the order used. |
Errors
Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.