AIDataParser

API reference

AIDataParser extracts structured JSON from PDFs and images. Base URL: https://aidataparser.com. Machine-readable spec at /openapi.json.

Quickstart

1. Issue an API key (50 free credits, no card)

No card, no signup form beyond this line. The key is shown once, right here.

Prefer a terminal — or driving this from an agent? The same free door is one POST:

curl -X POST https://aidataparser.com/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

# => 201
# {
#   "object": "api_key",
#   "api_key": "adp_live_xxxxxxxx",   // store this now — shown once
#   "credits": 50,
#   "free_credits_granted": 50
# }

Inside an MCP client, call the keyless create_api_key tool instead — see MCP.

2. Parse a document

curl -X POST https://aidataparser.com/v1/parse/document \
  -H "Authorization: Bearer adp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/receipt.png" }'

Authentication

Pass your key as a bearer token: Authorization: Bearer adp_live_... (or the x-api-key header). Keys are shown once at creation and stored only as a hash.

GET /v1/credits

Returns the remaining credit balance for the authenticated key. This call is free — it never spends a credit — so agents can check the balance before starting a batch and top up when it runs low.

curl https://aidataparser.com/v1/credits \
  -H "Authorization: Bearer adp_live_xxxxxxxx"

# => 200
# {
#   "object": "credit_balance",
#   "email": "you@example.com",
#   "key_prefix": "adp_live_ab",
#   "credits_remaining": 50
# }

Response

emailstring

The account the key belongs to.

key_prefixstring

First characters of the key, for dashboard/display matching.

credits_remaininginteger

Credits currently available to spend.

POST /v1/parse/document

Accepts a PDF or image via a URL, base64 payload, or multipart file. Costs 1 credit per document, charged only on success. Text-first PDFs are parsed with a pure-JS reader; images are sent to the model as vision input.

Request body (JSON)

urlstring

http(s) URL to a PDF or image.

base64string

Base64-encoded file bytes (data-URI prefixes are stripped automatically).

media_typestring

MIME type for base64 input: application/pdf, image/png, image/jpeg, image/gif, or image/webp.

schemaobject · optional

A JSON Schema describing the desired output. When provided, the data field is guaranteed to match it.

schema_idstring · optional

A built-in template id (e.g. invoice, receipt, resume) used instead of writing your own schema. Ignored when schema is supplied. See schema templates.

instructionsstring · optional

Natural-language guidance for the extraction.

Multipart form upload

curl -X POST https://aidataparser.com/v1/parse/document \
  -H "Authorization: Bearer adp_live_xxxxxxxx" \
  -F "file=@/path/to/invoice.pdf" \
  -F 'schema={"type":"object","properties":{"total":{"type":"number"}}}'

Base64 upload

curl -X POST https://aidataparser.com/v1/parse/document \
  -H "Authorization: Bearer adp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "base64": "JVBERi0xLjc...", "media_type": "application/pdf" }'

Response

dataobject

The extracted structured JSON (matches your schema when supplied).

confidence"high" | "medium" | "low"

Model's self-assessed confidence in the extraction.

review_neededboolean

True when the document was ambiguous or low quality — gate on this in agent workflows.

notesstring | null

Optional note about issues encountered.

credits_charged / credits_remaininginteger

Credits used by this call and your remaining balance.

POST /v1/parse/text

Already have the text? Skip the file. Send raw or messy text — scraped web content, email bodies, chat logs, OCR output, or pasted tables — and get the same schema-guaranteed JSON back. Costs 1 credit, charged only on success. Same response shape and options as parse a document; the only difference is the input.

Request body (JSON)

textstring

The raw text to extract from. Max 200,000 characters.

schemaobject · optional

A JSON Schema describing the desired output. When provided, the data field is guaranteed to match it.

schema_idstring · optional

A built-in template id used instead of writing your own schema. See schema templates.

instructionsstring · optional

Natural-language guidance for the extraction.

redactboolean · optional

Mask PII (emails, SSNs, cards, phones) before the data leaves the server.

curl -X POST https://aidataparser.com/v1/parse/text \
  -H "Authorization: Bearer adp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "From: jane@acme.co\nSubject: PO 4471\nPlease ship 12 widgets to 500 Main St by Friday.",
    "schema_id": "purchase_order"
  }'

Schema templates /v1/schemas

For common document types you can skip writing a JSON Schema and pass a schema_id instead. GET /v1/schemas lists every built-in template with the fields it extracts — it's free and needs no API key, so an agent can discover the catalog before spending a credit.

# List the built-in templates (free, no key)
curl https://aidataparser.com/v1/schemas

# Then parse with a named template instead of a schema
curl -X POST https://aidataparser.com/v1/parse/document \
  -H "Authorization: Bearer adp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/invoice.pdf", "schema_id": "invoice" }'

Built-in ids: invoice, receipt, resume, bank_statement, purchase_order, business_card, packing_slip, and contract. An explicit schema always overrides schema_id.

POST /v1/schemas/infer

When none of the built-in templates fit your document type, hand over a single representative sample and get back a reusable JSON Schema. Infer once, review it, then pass it as schema on parse a document or parse text across every document of that type for consistent output. Costs 1 credit, charged only on success.

Request body (JSON)

textstring

One representative sample of the document, as text. Max 200,000 characters — a single example is enough.

doc_typestring · optional

A hint for the kind of document (e.g. purchase order, lab report).

instructionsstring · optional

Guidance on which fields matter or how to shape the schema.

Response

schemaobject

A JSON Schema ready to pass straight back as schema on the parse endpoints.

fieldsarray

A flat list of the proposed fields ({ name, type, description }) for quick review.

doc_typestring

The inferred snake_case document type.

# No template fits? Infer a reusable schema from one sample (1 credit)
curl -X POST https://aidataparser.com/v1/schemas/infer \
  -H "Authorization: Bearer adp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "LAB REPORT\nPatient: Jane Doe\nGlucose: 92 mg/dL\nCholesterol: 180 mg/dL",
    "doc_type": "lab report"
  }'
# -> { "schema": { ... }, "fields": [ ... ], "doc_type": "lab_report" }
# Reuse the returned schema as `schema` on /v1/parse/* for consistent output.

POST /v1/validate

Check whether a JSON object conforms to a schema (or a built-in schema_id template) and get back a valid flag plus per-field errors. Verify data you already hold — a prior parse result, your own output, or an upstream feed — before you act on it or spend a credit. Free, deterministic, and needs no API key.

Request body (JSON)

dataany · required

The JSON value to validate.

schemaobject

A JSON Schema to validate against. Takes precedence over schema_id.

schema_idstring

A built-in template id to validate against instead of a hand-written schema. One of schema or schema_id is required.

Response

validboolean

True when the data satisfies the schema.

errorsarray

Each failure as { path, message, keyword } — the dotted path to the offending value, a readable message, and the schema keyword that failed.

# Check data you already hold against a template (free, no key)
curl -X POST https://aidataparser.com/v1/validate \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "invoice",
    "data": { "invoice_number": "A-100", "total": "twelve" }
  }'
# -> {
#   "object": "validate",
#   "valid": false,
#   "error_count": 1,
#   "errors": [
#     { "path": "total", "message": "Expected type number but got string.", "keyword": "type" }
#   ]
# }

MCP server /v1/mcp

AIDataParser ships a native Model Context Protocol server so an AI agent can call it as a tool directly — no glue code. It speaks JSON-RPC 2.0 over Streamable HTTP (stateless JSON mode) and exposes six tools: parse_document (1 credit), parse_text (1 credit), infer_schema (1 credit), validate (free), check_credits (free), and list_schemas (free). Authenticate with the same Authorization: Bearer adp_live_... header.

Add it to your agent

{
  "mcpServers": {
    "aidataparser": {
      "url": "https://aidataparser.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer adp_live_xxxxxxxx"
      }
    }
  }
}

Call a tool over raw JSON-RPC

# tools/call — parse a document over MCP (JSON-RPC 2.0)
curl -X POST https://aidataparser.com/v1/mcp \
  -H "Authorization: Bearer adp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "parse_document",
      "arguments": { "url": "https://example.com/receipt.png" }
    }
  }'

Tool results are returned as MCP content plus structuredContent. Extraction failures come back with isError: true and never spend a credit.

Errors

401unauthorized

Missing, invalid, or revoked API key.

402payment required

Insufficient credits — top up to continue.

415unsupported media type

The file type is not a supported PDF or image.

422unprocessable

Scanned/image-only PDF with no embedded text — send the page as an image instead (OCR-grade PDF support is on the roadmap).

Errors return { "error": { "message": "..." } }. Failed extractions are never charged.