DocImprint Extract API

openapi: 3.2.0
info:
  title: DocImprint Extract API
  version: 1.0.0
  description: Verifiable document intelligence for AI agents. Extract, summarize, translate, or fact-check any URL or document. Responses include cryptographic evidence bundles with on-chain attestation. Pay per call in USDC via x402 or use an API key.
servers:
- url: https://api.docimprint.com
security:
- ApiKeyAuth:
  - read
  - write
- ApiKeyHeader:
  - read
  - write
tags:
- name: Extract
paths:
  /v1/extract:
    post:
      summary: Extract, analyze, and archive any document or URL — with a verifiable evidence…
      operationId: extract
      parameters:
      - name: store
        in: query
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
        description: Canonical flag to persist an evidence bundle (default true for JSON/multipart URL flows). false returns lean { status, store, mode, result } without bundle_id.
      - name: async
        in: query
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
        description: 'Queue background processing. Returns 202 { status: queued, job_id, bundle_id, next_action }. Required when using collection_id.'
      - name: stream
        in: query
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
        description: SSE progress events (start, extracting, analyzed, complete). Ignored when async=true or webhook+store queues a job.
      - name: verbose
        in: query
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
        description: 'When true: include internal chunk artifacts and R2 storage keys on each artifact. Default artifacts are { sha256, content_type } only — use bundle_id with GET /download or GET /:id for file access.'
      - name: compat
        in: query
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
        description: Duplicate mode-specific fields at the top level for migration compatibility.
      - name: mode
        in: query
        schema:
          type: string
          enum:
          - extract
          - summarize
          - qa
          - invoice
          - translate
          - claim-check
          - compare
          - describe
          - extract-structured
        description: Overrides body mode field and auto-detection. Prefer setting mode in the request body.
      - name: ocr_type
        in: query
        schema:
          type: string
          enum:
          - text
          - tables
          - expense
          default: text
        description: OCR method for binary uploads. text uses AI vision (default). tables and expense use AWS Textract.
      - name: Idempotency-Key
        in: header
        schema:
          type: string
        description: When store=true, replays prior bundle for this wallet+key. Body idempotency_key is a fallback when header is absent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  type: string
                  description: URL (https://...) of the page or document to process
                mode:
                  type: string
                  enum:
                  - extract
                  - summarize
                  - qa
                  - invoice
                  - translate
                  - claim-check
                  - compare
                  - describe
                  - extract-structured
                  default: extract
                  description: 'Set in the request body (canonical). Auto-detected when omitted — priority order: (1) ?mode= query param wins if present, (2) schema field → extract-structured, (3) claims field → claim-check, (4) question field → qa, (5) default → extract. | extract — (default) full evidence bundle: screenshot, PDF, Markdown, OCR, AI summary, SHA-256 hashes. | summarize — URL or document → { summary, key_points, strategy }. Default include: markdown, summary (no screenshot/OCR unless requested). | qa — URL or document + question → { answer, confidence }. Default include: markdown only (add ocr/screenshot via include for image-heavy pages). | invoice — URL or file → result.invoice: { merchant, date, line_items[].{ description, amount }, subtotal, tax, total }. All fields also available with citations in result.invoice_cited. Use for receipts and invoices. | translate — URL + target_lang → { translated_text, model_used }. Default include: markdown only. | claim-check — URL or document + claims[] → { claim_results[].{ status, evidence.{ quote, paragraphs }, confidence } }. Default include: markdown only. | compare — URL + previous_bundle_id → text diff. Use to detect content drift between two captures. | describe — URL or image → { description, text_visible, objects[] }. Use to visually describe a page or image.'
                schema:
                  type: object
                  additionalProperties:
                    type: string
                  description: Typed field extraction. Auto-selects extract-structured when mode is omitted.
                store:
                  type: boolean
                  default: true
                  description: Persist evidence bundle. false = lean response (same as ?store=false).
                include:
                  type: array
                  items:
                    type: string
                    enum:
                    - screenshot
                    - pdf
                    - markdown
                    - ocr
                    - summary
                  description: 'Artifacts to capture. extract/compare: full capture. summarize/qa/translate/claim-check/extract-structured: markdown (and summary for summarize) unless overridden.'
                collection_id:
                  type: string
                  description: Auto-index into collection after async job completes. Requires ?async=true.
                idempotency_key:
                  type: string
                  description: Fallback when Idempotency-Key header is not sent. Only applies when store=true.
                question:
                  type: string
                  description: Required for qa mode.
                claims:
                  type: array
                  items:
                    type: string
                  description: Required for claim-check mode.
                target_lang:
                  type: string
                  description: Required for translate mode. ISO 639-1 code (e.g. "es", "fr").
                previous_bundle_id:
                  type: string
                  description: Required for compare mode.
                notarize:
                  type: boolean
                  default: false
                  description: Anchor the bundle hash on Base L2 immediately after creation.
                max_tokens:
                  type: integer
                  description: Token budget for AI processing. Truncated=true returned when exceeded.
                webhook:
                  type: string
                  format: uri
                  description: Webhook URL to POST the manifest to after processing.
                monitor:
                  type: object
                  description: Register ongoing monitoring for this URL. Fires webhook on each check. 48 checks at 30-min intervals (~24h).
                  properties:
                    mode:
                      type: string
                      enum:
                      - diff
                      - always
                      default: diff
                    webhook_url:
                      type: string
                      format: uri
                  required:
                  - webhook_url
                pages:
                  type: string
                  pattern: ^\d+-\d+$
                  example: 1-50
                  description: Page range to process from a PDF upload (e.g. "1-50"). Only applies to binary/multipart PDF uploads — silently ignored for URL sources and non-PDF files. Useful for processing large contracts in sections.
                source_headers:
                  type: object
                  additionalProperties:
                    type: string
                  description: 'Extra HTTP headers forwarded when fetching a URL source (e.g. {"Authorization": "Bearer <token>"}). Use to access authenticated DMS endpoints (iManage, NetDocuments, SharePoint). Forbidden hop-by-hop headers (host, content-length, etc.) are stripped automatically. Never stored in the evidence bundle or logs.'
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: PDF, image/*, or text/* file (max 4MB)
                mode:
                  type: string
                  enum:
                  - extract
                  - summarize
                  - qa
                  - invoice
                  - translate
                  - claim-check
                  - compare
                  - describe
                  - extract-structured
                ocr_type:
                  type: string
                  enum:
                  - text
                  - tables
                  - expense
                  default: text
                  description: OCR method. tables/expense use AWS Textract.
                schema:
                  type: string
                  description: JSON object schema string for extract-structured mode.
                question:
                  type: string
                  description: Required for qa mode.
                claims:
                  type: string
                  description: JSON array of claim strings. Required for claim-check mode.
                target_lang:
                  type: string
                  description: ISO 639-1 code (e.g. "es"). Required for translate mode.
                include:
                  type: string
                  description: JSON array string OR repeat include=ocr&include=summary form keys.
                store:
                  type: boolean
                  description: Persist bundle (default true for multipart).
                collection_id:
                  type: string
                  description: Requires ?async=true on POST /v1/extract.
                max_tokens:
                  type: integer
                  description: Token budget for AI processing.
                webhook:
                  type: string
                  format: uri
                  description: Webhook URL to POST the manifest to after processing.
                pages:
                  type: string
                  description: Page range to process (e.g. "1-50"). PDF uploads only.
          image/png:
            schema:
              type: string
              format: binary
            description: Raw binary OCR — returns { url, text, pages, truncated } lean response. Add ?store=true to store an evidence bundle.
          image/jpeg:
            schema:
              type: string
              format: binary
            description: Raw binary OCR — returns { url, text, pages, truncated } lean response. Add ?store=true to store an evidence bundle.
          image/webp:
            schema:
              type: string
              format: binary
            description: Raw binary OCR — returns { url, text, pages, truncated } lean response. Add ?store=true to store an evidence bundle.
          image/gif:
            schema:
              type: string
              format: binary
            description: Raw binary OCR — returns { url, text, pages, truncated } lean response. Add ?store=true to store an evidence bundle.
          application/pdf:
            schema:
              type: string
              format: binary
            description: Raw binary OCR — returns { url, text, pages, truncated } lean response. Add ?store=true to store an evidence bundle.
      responses:
        '200':
          description: 'Compact envelope: { success: true, status, store, mode, bundle_id?, url, captured_at, metadata, result, artifacts?, provenance }. Mode output is always under result — e.g. result.invoice for invoice mode, result.summary for summarize, result.answer for qa, result.claim_results for claim-check. result.text contains extracted markdown (empty when store=false). artifacts.* default: { sha256, content_type }. Download files: GET /v1/extract/{bundle_id}/download.'
        '202':
          description: '{ success: true, status: queued, store: true, mode, job_id, bundle_id, next_action: { poll_url: "/v1/jobs/{job_id}" } }'
        '400':
          description: '{ success: false, error, code: BAD_REQUEST, field?, hint? }'
        '402':
          description: Payment required (x402) or quota exceeded
        '404':
          description: '{ success: false, error, code: NOT_FOUND, field? }'
        '413':
          description: '{ success: false, error, code: FILE_TOO_LARGE, field: file }'
        '415':
          description: '{ success: false, error, code: UNSUPPORTED_TYPE, field: file }'
        '500':
          description: '{ success: false, error, code: PROCESSING_ERROR|FETCH_FAILED, retryable? }'
      tags:
      - Extract
  /v1/extract/{id}:
    get:
      summary: Retrieve an evidence bundle by ID
      operationId: getBundle
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Bundle status, manifest, and artifact references
        '401':
          $ref: '#/components/responses/WalletRequired'
        '404':
          description: Bundle not found
      tags:
      - Extract
    delete:
      summary: Delete an evidence bundle (owner-scoped purge)
      operationId: deleteBundle
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: acknowledge_notarized
        in: query
        schema:
          type: string
          enum:
          - 'true'
        description: Required when bundle has on-chain attestation; off-chain delete only — chain proof remains
      responses:
        '200':
          description: '{ bundle_id, deleted: true, on_chain_attestation_remains? }'
        '401':
          $ref: '#/components/responses/WalletRequired'
        '403':
          description: Forbidden — not bundle owner
        '404':
          description: Bundle not found
        '409':
          description: LEGAL_HOLD or BUNDLE_NOTARIZED (use acknowledge_notarized=true to force delete)
      tags:
      - Extract
  /v1/extract/{id}/verify:
    get:
      summary: Deep-verify bundle integrity from R2 storage (free, no account)
      operationId: verifyBundle
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: quick
        in: query
        schema:
          type: string
          enum:
          - 'true'
        description: Status-only check (skip R2 re-hash)
      responses:
        '200':
          description: '{ bundle_id, valid: true, checks: { manifest_hash, signature, artifacts, attestation } }'
        '404':
          description: Bundle not found
        '409':
          description: 'Tamper detected — valid: false, tampered: [...]'
      tags:
      - Extract
  /v1/extract/{id}/history:
    get:
      summary: Version chain for a document bundle
      operationId: bundleHistory
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ bundle_id, versions[] }'
      tags:
      - Extract
  /v1/extract/{id}/hold:
    put:
      summary: Place legal hold on a bundle (blocks retention GC)
      operationId: setLegalHold
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ bundle_id, legal_hold: true }'
      tags:
      - Extract
    delete:
      summary: Remove legal hold from a bundle
      operationId: removeLegalHold
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ bundle_id, legal_hold: false }'
      tags:
      - Extract
  /v1/extract/{id}/verify-citation:
    post:
      summary: Verify a citation against the bundle Merkle tree
      operationId: verifyCitation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ valid, leaf_hash, proof[], merkle_root, manifest_sha256, signature? }'
      tags:
      - Extract
  /v1/extract/{id}/revoke:
    post:
      summary: Revoke a bundle's on-chain attestation
      operationId: revokeAttestation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ bundle_id, revoked: true, tx_hash }'
      tags:
      - Extract
  /v1/extract/{id}/manifest:
    get:
      summary: Get the raw evidence manifest JSON
      operationId: getManifest
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Full manifest object
        '404':
          description: Bundle not found
      tags:
      - Extract
  /v1/extract/{id}/provenance:
    get:
      summary: Get provenance records for a bundle
      operationId: getProvenance
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ provenance: [...] }'
      tags:
      - Extract
    post:
      summary: Add a provenance record to a bundle
      operationId: addProvenance
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ success: true, provenance_id }'
      tags:
      - Extract
  /v1/extract/{id}/handoff:
    post:
      summary: Record an agent-to-agent handoff for a bundle
      operationId: agentHandoff
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ success: true, handoff_id }'
      tags:
      - Extract
  /v1/extract/{id}/chain:
    get:
      summary: Get the full version chain for a document bundle
      operationId: bundleVersionChain
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ bundle_id, chain: [{ bundle_id, version, captured_at, superseded_by }] }'
      tags:
      - Extract
  /v1/extract/{id}/receipts:
    get:
      summary: List signed action receipts for a bundle
      operationId: listActionReceipts
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: '{ bundle_id, receipts: [...], limit, offset }'
        '403':
          description: Forbidden — not bundle owner
        '404':
          description: Bundle not found
      tags:
      - Extract
  /v1/extract/receipts/{receiptId}/verify:
    get:
      summary: Verify a signed action receipt (capability token)
      description: Independently verify receipt signature and that the bound manifest_sha256 still matches the bundle. Not owner-gated — anyone with the receipt_id can verify.
      operationId: verifyActionReceipt
      parameters:
      - name: receiptId
        in: path
        required: true
        schema:
          type: string
        description: rcpt_… ID
      responses:
        '200':
          description: '{ receipt_id, valid, signature_valid, manifest_matches_current, bundle_id, agent_id, action, manifest_sha256, signer_address, signed_at, tampered[] }'
        '404':
          description: Receipt not found
      tags:
      - Extract
  /v1/extract/{id}/download:
    get:
      summary: Download all bundle artifacts as a ZIP archive
      operationId: downloadBundle
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ZIP containing screenshot, PDF, markdown, OCR text, manifest.json
          content:
            application/zip: {}
        '404':
          description: Bundle not found
      tags:
      - Extract
  /v1/extract/{id}/notarize:
    post:
      summary: Anchor bundle hash on Base L2 blockchain
      operationId: notarizeBundle
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ bundle_id, attestation: { tx_hash, network, attested_at } }'
        '402':
          description: Payment required
        '503':
          description: Attestation not configured
      tags:
      - Extract
components:
  responses:
    WalletRequired:
      description: '{ error: "Wallet identity required", code: "WALLET_REQUIRED", hint: "Pay-per-call (x402): payment-signature from your POST payment. Subscription: Authorization Bearer dr_live_..." }'
  parameters:
    PaymentSignature:
      name: payment-signature
      in: header
      required: false
      schema:
        type: string
      description: Verified x402 payment authorization (base64 JSON from the x402 protocol). Required on owner-scoped GET/DELETE when not using an API key. Must correspond to the payer that created the resource. X-Wallet-Address is deprecated and ignored.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Bearer dr_live_... (or use X-API-Key header). Scopes: read (GET), write (POST/PUT/DELETE), admin (admin endpoints). Create keys at https://docimprint.com/pricing or via admin API.'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Alternative to Authorization: Bearer header. Scopes same as ApiKeyAuth.'