Extract

Path parameters

None.

Query parameters

None.Serves a fixed document and takes no input at all.

Body parameters

None.GET requests carry no body.

Response

{
  "status": "ok",
  "version": "0.1.0",
  "checks": { "extract": "ok" }
}

Status codes

curl

curl -X GET 'https://api.dev.oprag.ai/extract/health' \
  -H 'X-Oprag-Key: sk_live_...'

Before you call it

• Uploading straight to S3 is what keeps large files clear of API Gateway's request body limit.
• Supported formats: PDF, PNG, JPEG, GIF, and WebP (max 10 MB per file). PDFs may be up to 100 MB; the ceiling is enforced by content-length-range on the presigned POST and re-checked on confirm.
• POST the file to uploadUrl as multipart/form-data — every entry of uploadFields first, then the file — and then call POST /v1/extract/jobs/{jobId}/confirm. The URL is valid for expiresIn seconds.
• The response is a CreateExtractUploadUrlResponse: jobId, status: "upload_pending", uploadUrl, uploadFields, expiresIn, and pollUrl.
• Integration keys only, scoped to the workspace. Each call counts toward EXTRACT_DAILY_JOB_LIMIT.
• Available in dev only until enable_extract is turned on in staging and production.

Path parameters

None.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Request

{
  "filename": "annual-contract.pdf",
  "contentType": "application/pdf",
  "schemaId": "contract",
  "clientRef": "erp-sync-8842"
}

Response

{
  "jobId": "ext_a1b2c3d4e5f6789012345678abcdef01",
  "status": "upload_pending",
  "uploadUrl": "https://extract-inbox.s3.amazonaws.com/",
  "uploadFields": {
    "key": "inbox/co_abc/ext_a1b2…/annual-contract.pdf",
    "Policy": "…",
    "X-Amz-Signature": "…",
    "Content-Type": "application/pdf"
  },
  "expiresIn": 900,
  "pollUrl": "/v1/extract/jobs/ext_a1b2c3d4e5f6789012345678abcdef01"
}

Status codes

curl

curl -X POST 'https://api.dev.oprag.ai/v1/extract/upload-urls' \
  -H 'X-Oprag-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"filename": "annual-contract.pdf","contentType": "application/pdf","schemaId": "contract","clientRef": "erp-sync-8842"}'

Before you call it

• Use POST /v1/extract/upload-urls, POST the file to S3 with uploadFields, then POST /v1/extract/jobs/{jobId}/confirm. GET /v1/extract/jobs/{jobId} polls status from there.
• Integration keys only, scoped to the workspace. Available in dev only until enable_extract is turned on in staging and production.

Path parameters

None.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Defined by the caller.Deprecated for file submission — always returns 400 pointing at the upload-url flow.

Request

# Direct multipart/fileUrl submit removed — use presigned upload:
curl -X POST "$API_URL/v1/extract/upload-urls" \
  -H "X-Oprag-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"invoice.pdf","contentType":"application/pdf","schemaId":"invoice"}'

Response

{
  "error": "Use POST /v1/extract/upload-urls, POST the file to S3 with uploadFields, then POST /v1/extract/jobs/{jobId}/confirm",
  "code": "VALIDATION_ERROR"
}

Status codes

curl

curl -X POST 'https://api.dev.oprag.ai/v1/extract/jobs' \
  -H 'X-Oprag-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '# Direct multipart/fileUrl submit removed — use presigned upload:curl -X POST "$API_URL/v1/extract/upload-urls" \-H "X-Oprag-Key: sk_live_YOUR_KEY" \-H "Content-Type: application/json" \-d '{"filename":"invoice.pdf","contentType":"application/pdf","schemaId":"invoice"}''

Before you call it

• Call it after the file has been POSTed to uploadUrl. The object is checked for existence, non-emptiness, size (100 MB for PDFs, 10 MB for images), and a supported format by both MIME type and magic bytes.
• On success the job moves from upload_pending to queued and { jobId, companyId, schemaId } is enqueued for the worker.
• The response is a ConfirmExtractJobResponse: jobId, status: "queued", and pollUrl.
• Confirming a job that is already queued returns the same 202 again, so retrying is safe.

Path parameters

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.Confirms the object already uploaded for this job id.

Request

# No body — jobId in path only
curl -X POST "$API_URL/v1/extract/jobs/ext_a1b2c3d4e5f6789012345678abcdef01/confirm" \
  -H "X-Oprag-Key: sk_live_YOUR_KEY"

Response

{
  "jobId": "ext_a1b2c3d4e5f6789012345678abcdef01",
  "status": "queued",
  "pollUrl": "/v1/extract/jobs/ext_a1b2c3d4e5f6789012345678abcdef01"
}

Status codes

curl

curl -X POST 'https://api.dev.oprag.ai/v1/extract/jobs/{jobId}/confirm' \
  -H 'X-Oprag-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '# No body — jobId in path onlycurl -X POST "$API_URL/v1/extract/jobs/ext_a1b2c3d4e5f6789012345678abcdef01/confirm" \-H "X-Oprag-Key: sk_live_YOUR_KEY"'

Before you call it

• status runs upload_pending → queued → processing → completed or failed. A failed job carries error.code.
• The shape of data follows schemaId (or detectedSchemaId): one of InvoiceExtractData, ReceiptExtractData, PurchaseOrderExtractData, CreditNoteExtractData, DeliveryNoteExtractData, BankStatementExtractData, PayslipExtractData, UtilityBillExtractData, TicketExtractData, TaxFormExtractData, ContractExtractData, GstInvoiceExtractData, or IdDocumentExtractData — alongside confidence, provenance, and billing.
• Auto-detected jobs set schemaId to the detected type and add classificationMode, requestedSchemaId, detectedSchemaId, and classification { schemaId, confidence, reason? }, where reason appears only when the model supplies one.
• Scanned documents that go through OCR add processingTier: "ocr", documentConfidence, validationIssues, provenance.bbox from Textract geometry, and sometimes ocrQualityWarning.
• Large PDFs — 21 pages or more, over 10 MB, or a bank statement of 4 pages or more — run a chunked pipeline in 20-page chunks. While processing they add jobTier: "large", phase (preprocess, extracting, or merging), totalPages, and progress { chunksCompleted, chunksTotal }.
• provenance may carry an excerpt, for any schema.
• Typical latency on dev is 5–15 s for an explicit schema and 10–30 s for auto-detect. Chunked PDFs take minutes — poll and watch progress.

Path parameters

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

Body parameters

None.GET requests carry no body.

Responses

{
  "jobId": "ext_a1b2c3d4e5f6789012345678abcdef01",
  "status": "completed",
  "schemaId": "invoice",
  "extractedAt": "2026-07-11T21:20:46.573Z",
  "data": {
    "vendorName": "Contoso Ltd.",
    "invoiceNumber": "INV-100",
    "invoiceDate": "11/15/2019",
    "dueDate": "12/15/2019",
    "subtotal": 100,
    "taxAmount": 10,
    "totalAmount": 110,
    "lineItems": [{ "description": "Consulting Services", "quantity": 2, "unitPrice": 30, "amount": 60 }]
  },
  "confidence": { "invoiceNumber": 1, "totalAmount": 1 },
  "documentConfidence": 0.95,
  "processingTier": "digital",
  "billing": { "pagesProcessed": 1, "billable": true }
}

// Large PDF while processing (optional progress fields):
// "status": "processing", "jobTier": "large", "phase": "extracting",
// "totalPages": 80, "progress": { "chunksCompleted": 2, "chunksTotal": 4 }

// Auto-detect completed (requestedSchemaId was "auto"):
// "schemaId": "invoice", "classificationMode": "auto", "requestedSchemaId": "auto",
// "detectedSchemaId": "invoice", "classification": { "schemaId": "invoice", "confidence": 0.91 }

{
  "jobId": "ext_656c03b65e61454e5bc562567a0f98b3",
  "status": "completed",
  "schemaId": "receipt",
  "clientRef": "invoicehome-receipt",
  "extractedAt": "2026-07-11T22:31:16.976Z",
  "data": {
    "merchantName": "East Repair Inc.",
    "merchantAddress": "1912 Harvest Lane New York, NY 12210",
    "receiptNumber": "US-001",
    "receiptDate": "11/02/2019",
    "subtotal": 145,
    "taxAmount": 9.06,
    "totalAmount": 154.06,
    "currency": "$",
    "lineItems": [
      { "description": "Front and rear brake cables", "quantity": 1, "unitPrice": 100, "amount": 100 },
      { "description": "New set of pedal arms", "quantity": 2, "unitPrice": 15, "amount": 30 },
      { "description": "Labor 3hrs", "quantity": 3, "unitPrice": 5, "amount": 15 }
    ]
  },
  "confidence": { "merchantName": 1, "receiptNumber": 1, "totalAmount": 1, "lineItems": 1 },
  "provenance": [{ "field": "merchantName", "page": 1, "excerpt": "East Repair Inc." }],
  "billing": { "pagesProcessed": 1, "billable": true }
}

Status codes

curl

curl -X GET 'https://api.dev.oprag.ai/v1/extract/jobs/{jobId}' \
  -H 'X-Oprag-Key: sk_live_...'

Before you call it

• Built-in schemas come first, then the workspace's custom ones sorted by schemaId.

Path parameters

None.

Query parameters

Body parameters

None.GET requests carry no body.

Response

{
  "schemas": [
    { "schemaId": "invoice", "displayName": "Invoice", "source": "builtin", "status": "active" },
    { "schemaId": "receipt", "displayName": "Receipt", "source": "builtin", "status": "active" },
    {
      "schemaId": "custom_purchase_order",
      "displayName": "Purchase order",
      "source": "custom",
      "status": "active",
      "version": 2,
      "fieldCount": 7,
      "createdAt": "2026-06-01T10:00:00.000Z",
      "updatedAt": "2026-06-14T09:12:00.000Z"
    }
  ]
}

Status codes

curl

curl -X GET 'https://api.dev.oprag.ai/v1/extract/schemas' \
  -H 'X-Oprag-Key: sk_live_...'

Path parameters

None.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Request

{
  "schemaId": "custom_purchase_order",
  "displayName": "Purchase order",
  "documentDescription": "A supplier purchase order with line items and totals.",
  "extractionHints": "Totals are on the last page. Currency is always the document currency.",
  "fields": [
    { "key": "poNumber", "type": "string", "description": "Purchase order number" },
    { "key": "orderDate", "type": "date", "description": "Date the order was raised" },
    { "key": "total", "type": "number", "description": "Order total including tax" }
  ]
}

Response

{
  "schemaId": "custom_purchase_order",
  "displayName": "Purchase order",
  "source": "custom",
  "status": "active",
  "version": 1,
  "documentDescription": "A supplier purchase order with line items and totals.",
  "fields": [
    { "key": "poNumber", "type": "string", "description": "Purchase order number" },
    { "key": "orderDate", "type": "date", "description": "Date the order was raised" },
    { "key": "total", "type": "number", "description": "Order total including tax" }
  ],
  "createdAt": "2026-06-01T10:00:00.000Z",
  "updatedAt": "2026-06-01T10:00:00.000Z"
}

Status codes

curl

curl -X POST 'https://api.dev.oprag.ai/v1/extract/schemas' \
  -H 'X-Oprag-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"schemaId": "custom_purchase_order","displayName": "Purchase order","documentDescription": "A supplier purchase order with line items and totals.","extractionHints": "Totals are on the last page. Currency is always the document currency.","fields": [{ "key": "poNumber", "type": "string", "description": "Purchase order number" },{ "key": "orderDate", "type": "date", "description": "Date the order was raised" },{ "key": "total", "type": "number", "description": "Order total including tax" }]}'

Before you call it

• A built-in id returns a short descriptor with a documentationUrl; a custom id returns the full field definitions.

Path parameters

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

Body parameters

None.GET requests carry no body.

Response

{
  "schemaId": "invoice",
  "displayName": "Invoice",
  "source": "builtin",
  "status": "active",
  "documentationUrl": "/docs/api/extract/schemas/"
}

Status codes

curl

curl -X GET 'https://api.dev.oprag.ai/v1/extract/schemas/{schemaId}' \
  -H 'X-Oprag-Key: sk_live_...'

Before you call it

• Every accepted change bumps version.

Path parameters

Query parameters

None.Everything it needs is in the request body.

Body parameters

Request

{
  "displayName": "Supplier purchase order",
  "extractionHints": "Totals are on the last page; ignore the delivery note."
}

Response

{
  "schemaId": "custom_purchase_order",
  "displayName": "Supplier purchase order",
  "source": "custom",
  "status": "active",
  "version": 2,
  "updatedAt": "2026-06-14T09:12:00.000Z"
}

Status codes

curl

curl -X PATCH 'https://api.dev.oprag.ai/v1/extract/schemas/{schemaId}' \
  -H 'X-Oprag-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"displayName": "Supplier purchase order","extractionHints": "Totals are on the last page; ignore the delivery note."}'

Before you call it

• Archiving is not a hard delete: jobs already extracted with the schema keep their results, and the schemaId can never be reused.

Path parameters

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.DELETE requests carry no body.

Response

{
  "schemaId": "custom_purchase_order",
  "status": "archived",
  "archivedAt": "2026-06-20T08:30:00.000Z"
}

Status codes

curl

curl -X DELETE 'https://api.dev.oprag.ai/v1/extract/schemas/{schemaId}' \
  -H 'X-Oprag-Key: sk_live_...'