# AIDataParser

> A credit-based data-extraction API built for AI agents. POST a PDF or image
> (URL, base64, or multipart) with an optional JSON Schema and get clean,
> structured JSON back — with a confidence score and a review-needed flag.

AIDataParser is the parsing tool your AI agent calls when it hits messy data.
It is schema-first: pass the JSON Schema you want and the response is guaranteed
to match it. Pricing is by the credit (50 free on signup, no card); roughly one
credit per document.

## Getting started

- Issue an API key: `POST https://aidataparser.com/v1/keys` with `{"email":"you@example.com"}` (returns 50 free credits).
- Authenticate with `Authorization: Bearer adp_live_...`.

## Endpoints

- [Parse a document](https://aidataparser.com/v1/parse/document): POST a PDF or image (`url`, `base64`+`media_type`, or multipart `file`) with optional `schema` (or `schema_id`) and `instructions`. Returns `{ data, confidence, review_needed, notes, credits_remaining }`.
- [Parse text](https://aidataparser.com/v1/parse/text): POST raw text you already have (`text`, max 200k chars) with optional `schema` (or `schema_id`) and `instructions`. Use this when you don't have a file — scraped content, email bodies, chat logs, OCR output. Same response shape as parse-a-document. 1 credit.
- [Schema templates](https://aidataparser.com/v1/schemas): GET the built-in schema templates you can pass as `schema_id` instead of writing your own JSON Schema (invoice, receipt, resume, bank_statement, purchase_order, business_card, packing_slip, contract). Free, no auth.
- [Infer a schema](https://aidataparser.com/v1/schemas/infer): POST one sample document's `text` (with optional `doc_type`) when no built-in template fits; returns a reusable JSON `schema` + field list you can review and then reuse as `schema` across many parses. 1 credit.
- [Validate JSON](https://aidataparser.com/v1/validate): POST `{ data, schema }` (or `schema_id`) to check a JSON object against a schema; returns `{ valid, errors: [{ path, message, keyword }] }`. Verify data you already hold before acting on it. Free, no auth.
- [Issue an API key](https://aidataparser.com/v1/keys): POST `{ email }` to create an account and receive a key with 50 free credits. One key per email: an email that already has an account gets 409 `account_exists` and no key.
- [MCP server](https://aidataparser.com/v1/mcp): native Model Context Protocol server (JSON-RPC 2.0 over Streamable HTTP). Add it as a tool server with header `Authorization: Bearer adp_live_...`. Want to see real output before signing up for anything? Call the `try_parse` tool with a short text excerpt — a real extraction, no key, no email, 3 calls per caller per day. No key yet? Call the `create_api_key` tool with the user's email and you get one in-protocol with 50 free credits — no card, no website visit. Tools: `try_parse` (free, no key needed), `create_api_key` (free, no key needed), `parse_document` (1 credit), `parse_text` (1 credit), `infer_schema` (1 credit), `validate` (free), `check_credits` (free), `list_schemas` (free), and `buy_credits` (free; returns a Stripe checkout link for a credit pack to hand to the user — no HTTP call or website visit needed).

## Docs

- [API reference](https://aidataparser.com/docs): quickstart, auth, request/response fields, and error codes.
- [OpenAPI spec](https://aidataparser.com/openapi.json): machine-readable OpenAPI 3.1 definition.

## Notes for agents

- Supported inputs: application/pdf, image/png, image/jpeg, image/gif, image/webp.
- Text-first PDFs are parsed directly; scanned/image-only PDFs should be sent as images.
- Always inspect `review_needed` before trusting an extraction in an automated pipeline.
- For common document types, pass `schema_id` (e.g. `"invoice"`) instead of a full `schema`; fetch the catalog from GET /v1/schemas or the MCP `list_schemas` tool.