---
title: "Extract structured data from a document"
method: POST
path: "/v1/extract"
tags: ["Public API"]
---

# Extract structured data from a document

`POST /v1/extract`

## Request

- Base URL: `https://api.clichefactory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.clichefactory.com/v1/extract`
- Auth: none declared

Single-call extraction: upload a document file and a JSON schema, get structured data back. No presign dance, no SDK required.

## Headers

- `Idempotency-Key` string, nullable
- `X-API-KEY` string, nullable

## Response `200`

Successful Response

- PublicExtractResponse: Simplified extraction response for the public API.
  - `status` string, required: 'success' (schema-valid) or 'partial' (validation failed; credits still consumed)
  - `result` object, required: Extracted structured data matching the provided schema
  - `cost` PublicCostInfo: Credits-based cost info returned to public API callers.
    - `credits_used` integer, required: Credits consumed for this extraction. Partial results (schema validation failed but raw data was returned with validation_errors) still consume OCR + LLM work and are billed identically to successful extractions.
    - `pages` integer, required: Number of document pages processed
    - `balance_remaining` integer, nullable: Tenant credit balance remaining after this extraction was billed. Null for admin/service callers that bypass billing. Poll this to build client-side low-balance safety guards without a separate call to GET /v1/billing/balance/{tenant_id}.
  - `validation_errors` object[], nullable: Per-field validation errors when extraction is partial

## Other responses

- `400`: Bad request (missing/invalid schema or file)
- `401`: Invalid or missing API key
- `403`: Insufficient credits
- `422`: Validation Error
- `500`: Extraction failed
- `502`: Storage failure

---

[API](https://skmtc.dev/clichefactory/apis/aio-server.md) · [All operations](https://skmtc.dev/clichefactory/apis/aio-server/llms.txt) · [OpenAPI document](https://skmtc.dev/clichefactory/apis/aio-server/revisions/9bd59f9bbb31?raw)