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

FieldTypeRequiredDescription
filenamestringYesName of the file, 1 to 255 characters; the extension helps identify the type.
content_typestringNoMIME type of the file, for example text/csv or application/pdf. Defaults to application/octet-stream.
content_base64stringYesThe file contents, base64-encoded. Must not be empty and must decode to at most 15 MiB.
declared_typestringNoWhat 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

FieldTypeDescription
document_typestringThe kind of document found, for example bank_statement.
issuerstringThe institution that issued the document, or null when unknown.
review_requiredbooleanTrue when the reading is uncertain and a person should check it.
overall_confidencenumberConfidence in the whole reading, from 0 to 1.
fieldsobjectThe extracted values, keyed by field name; each has a value and a confidence from 0 to 1.
transactionsarrayTransactions found in the document, in the order they appear.
warningsarrayPlain-language notes about anything that could not be read.
tiers_usedarrayThe 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.