---
title: "Document Extraction"
method: POST
path: "/v1/documents/extract"
tags: ["Suprsonic"]
---

# Document Extraction

`POST /v1/documents/extract`

## Request

- Base URL: `https://suprsonic.ai`
- URL: `https://suprsonic.ai/v1/documents/extract`
- Auth: HTTP bearer

Extract structured data from URLs or content. Returns the extracted data as JSON (shaped by your schema when you pass one), with the source URL and whether long content was truncated. Use to turn a page or a text into structured fields. For a page's full text use scrape; for invoices and receipts use invoice-parse. Pass url or content; extraction_prompt says what to extract, and schema fixes the shape of the JSON you get back. Cost: 3 credits, charged only when a call succeeds.

## Request body

- DocumentExtractRequest
  - `url` string, nullable: URL to scrape and extract from
  - `content` string, nullable: Pre-scraped content to extract from (alternative to url)
  - `extraction_prompt` string, nullable: REQUIRED unless schema is provided. Natural language description of what to extract, e.g. 'Extract all product prices and features'
  - `schema` object, nullable: REQUIRED unless extraction_prompt is provided. JSON schema defining the structure of data to extract

## Response `200`

The call's envelope: success, data (the capability's result), metadata, and credits_used (0 when the call did not succeed).

- UnifiedResponse: Standard envelope for all unified API responses.
  - `success` boolean, required
  - `data` union
    - object
    - unknown[]
      - unknown
  - `error` UnifiedError: RFC 7807 problem detail for machine-actionable errors.
    - `type` string, required
    - `title` string, required
    - `status` integer, required
    - `detail` string, nullable
    - `is_retriable` boolean
    - `retry_after_seconds` integer, nullable
    - `alternative_action` string, nullable
    - `error_category` string
    - `caller_error` string, nullable
  - `metadata` UnifiedMetadata: Metadata included in every unified API response.
    - `provider_used` string, nullable
    - `providers_tried` string[]
    - `mode_used` string, nullable
    - `response_time_ms` integer
    - `request_id` string
    - `capability` string, nullable
    - `params` object, nullable
  - `credits_used` integer

## Other responses

- `401`: No API key, or one that was not found or is revoked.
- `402`: Not enough credits for this call. The error's alternative_action says where to add them.
- `403`: The account is restricted by a billing issue.
- `422`: Validation Error
- `429`: The key's rate limit is reached. The error's retry_after_seconds says when to try again.

---

[API](https://skmtc.dev/o-mega/apis/suprsonic-api.md) - [All operations](https://skmtc.dev/o-mega/apis/suprsonic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/o-mega/apis/suprsonic-api/revisions/0eb535eb5679?raw)