@talonic/docs 0.20.1 → 0.20.2

package/dist/content.js

@@ -4441,10 +4441,11 @@ var sections17 = [
         params: [
           { name: "extract", type: "scope", description: "Submit documents for extraction (`POST /v1/extract`, `POST /v1/documents/:id/re-extract`)." },
           { name: "read", type: "scope", description: "Read operations \u2014 list and retrieve documents, extractions, schemas, jobs, sources, and other resources." },
-          { name: "write", type: "scope", description: "Write operations \u2014 create, update, and delete schemas, sources, jobs, delivery bindings, and other resources." }
+          { name: "write", type: "scope", description: "Write operations \u2014 create, update, and delete schemas, sources, jobs, delivery bindings, and other resources." },
+          { name: "billing", type: "scope", description: "Billing operations \u2014 trigger credit top-ups (`POST /v1/billing/topup`). Not included by default; add explicitly when creating the key." }
         ]
       },
-      { type: "paragraph", text: "If a request requires a scope your key does not carry, the API returns `403` with error code `insufficient_scope` and lists the required scopes in the response body." },
+      { type: "paragraph", text: "New keys default to `extract`, `read`, and `write`. The `billing` scope must be added explicitly. If a request requires a scope your key does not carry, the API returns `403` with error code `insufficient_scope` and lists the required scopes in the response body." },
       { type: "callout", text: "Keep your API key secret. Do not expose it in client-side code or version control. If a key is compromised, revoke it immediately from the dashboard." }
     ],
     related: [
@@ -4454,7 +4455,7 @@ var sections17 = [
     faq: [
       { question: "How do I authenticate with the Talonic API?", answer: "Include a Bearer token in the Authorization header of every request. API keys use the tlnc_ prefix." },
       { question: "Where do I get an API key?", answer: "Create and manage API keys from Settings \u2192 API Keys in the Talonic dashboard." },
-      { question: "What scopes are available?", answer: "Three scopes: extract (submit documents), read (list/retrieve resources), and write (create/update/delete resources). New keys get all three by default." }
+      { question: "What scopes are available?", answer: "Four scopes: extract (submit documents), read (list/retrieve resources), write (create/update/delete resources), and billing (trigger credit top-ups). New keys get extract, read, and write by default; billing must be added explicitly." }
     ],
     mentions: ["Bearer token", "API key", "Authorization header", "scopes", "extract", "read", "write"]
   },
@@ -4481,9 +4482,9 @@ var sections17 = [
     parentSlug: "overview",
     title: "Quick Start",
     seoTitle: "API Quick Start Guide \u2014 Talonic Docs",
-    description: "Get started with the Talonic API in under 60 seconds. Extract structured data from a document with a single curl command using sync mode.",
+    description: "Three modes, one API. Auto-detect extraction, schema-driven extraction, and document filtering \u2014 all with per-cell confidence and cost transparency.",
     content: [
-      { type: "paragraph", text: "Extract structured data from a document in a single API call. This guide uses **sync mode** (documents \u22645 pages return results immediately)." },
+      { type: "paragraph", text: "Three modes. One API. Auto-detect what's in the document. Send your own schema and get exactly that shape. Or skip the document entirely and query data you already ingested. Plus per-cell provenance, confidence scores, and cost transparency on every call." },
       { type: "heading", level: 3, id: "prerequisites", text: "Prerequisites" },
       { type: "list", items: [
         "A Talonic account \u2014 sign up at [app.talonic.com](https://app.talonic.com)",
@@ -4491,15 +4492,42 @@ var sections17 = [
         "A PDF or image file to extract (e.g. an invoice)"
       ] },
       { type: "code", language: "bash", title: "Set your API key", code: `export TALONIC_API_KEY="tlnc_live_..."` },
-      { type: "heading", level: 3, id: "step-1-extract", text: "1. Extract a document" },
-      { type: "paragraph", text: "Send a file with an inline schema describing the fields you want:" },
-      { type: "code", language: "bash", title: "curl \u2014 extract an invoice", code: `curl -X POST https://api.talonic.com/v1/extract \\
+      { type: "heading", level: 2, id: "mode-1-auto-detect", text: "Mode 1 \u2014 Auto-detect extract" },
+      { type: "paragraph", text: "Send a document with no schema. Talonic discovers every field automatically." },
+      { type: "code", language: "bash", title: "curl \u2014 auto-detect all fields", code: `curl -X POST https://api.talonic.com/v1/extract \\
+  -H "Authorization: Bearer $TALONIC_API_KEY" \\
+  -F "file=@invoice.pdf"` },
+      { type: "paragraph", text: "Returns every field the AI discovers \u2014 vendor, dates, amounts, line items, addresses \u2014 with per-field confidence scores. Use this when you don't know the document structure upfront." },
+      { type: "heading", level: 2, id: "mode-2-schema-extract", text: "Mode 2 \u2014 Schema-driven extract" },
+      { type: "paragraph", text: "Send a document AND the shape you want. Get exactly those fields back." },
+      { type: "code", language: "bash", title: "curl \u2014 extract with inline schema", code: `curl -X POST https://api.talonic.com/v1/extract \\
   -H "Authorization: Bearer $TALONIC_API_KEY" \\
   -F "file=@invoice.pdf" \\
   -F 'schema={"vendor_name":"string","invoice_number":"string","total_amount":"number","due_date":"date"}'` },
-      { type: "heading", level: 3, id: "step-1-response", text: "Response (200 OK)" },
-      { type: "paragraph", text: "For documents \u22645 pages, you get the extracted data immediately:" },
-      { type: "code", language: "json", title: "Sync response", code: `{
+      { type: "paragraph", text: "The response contains exactly the four fields you asked for \u2014 nothing more. Save the schema with `POST /v1/schemas` for reuse across future extractions." },
+      { type: "heading", level: 2, id: "mode-3-filter", text: "Mode 3 \u2014 Query ingested data" },
+      { type: "paragraph", text: "Don't send a document. Query data you already extracted \u2014 across all documents in your workspace." },
+      { type: "code", language: "bash", title: "curl \u2014 filter previously extracted documents", code: `curl -X POST https://api.talonic.com/v1/documents/filter \\
+  -H "Authorization: Bearer $TALONIC_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "conditions": [
+      { "fieldId": "vendor_name", "operator": "eq", "value": "Acme GmbH" }
+    ],
+    "limit": 50
+  }'` },
+      { type: "paragraph", text: "Returns all documents matching your filter \u2014 no re-extraction, no AI cost. Ingest once, query forever." },
+      { type: "heading", level: 2, id: "cost-transparency", text: "Cost on every call" },
+      { type: "paragraph", text: "Every synchronous extraction response includes cost headers so you can track spend per call:" },
+      { type: "code", language: "bash", title: "Cost headers", code: `X-Talonic-Cost-Credits: 12
+X-Talonic-Cost-EUR: 0.012
+X-Talonic-Balance-Credits: 64918
+X-Talonic-Cells-Resolved-Registry: 3
+X-Talonic-Cells-Resolved-AI: 5` },
+      { type: "paragraph", text: "Fields resolved from the registry (`X-Talonic-Cells-Resolved-Registry`) cost nothing. Only AI-resolved fields consume credits." },
+      { type: "heading", level: 2, id: "example-response", text: "Example response" },
+      { type: "paragraph", text: "A synchronous extraction returns structured data with confidence scores:" },
+      { type: "code", language: "json", title: "Response (200 OK)", code: `{
   "extraction_id": "d1a2b3c4-5678-9abc-def0-1234567890ab",
   "request_id": "req_x7y8z9a0b1c2d3e4",
   "status": "complete",
@@ -4507,7 +4535,6 @@ var sections17 = [
     "id": "f0e1d2c3-b4a5-9687-8765-432109876543",
     "filename": "invoice.pdf",
     "pages": 2,
-    "size_bytes": 184320,
     "type_detected": "Invoice"
   },
   "data": {
@@ -4528,35 +4555,29 @@ var sections17 = [
   "processing": {
     "duration_ms": 1840,
     "pages_processed": 2
-  },
-  "links": {
-    "self": "/v1/extractions/d1a2b3c4-5678-9abc-def0-1234567890ab",
-    "document": "/v1/documents/f0e1d2c3-b4a5-9687-8765-432109876543"
   }
 }` },
-      { type: "heading", level: 3, id: "step-2-verify", text: "2. Verify it worked" },
-      { type: "paragraph", text: "Retrieve the extraction by ID to confirm the data is persisted:" },
-      { type: "code", language: "bash", title: "Verify extraction", code: `curl https://api.talonic.com/v1/extractions/d1a2b3c4-5678-9abc-def0-1234567890ab \\
-  -H "Authorization: Bearer $TALONIC_API_KEY"` },
-      { type: "paragraph", text: "You should see the same `data` object. The extraction is now stored and queryable across your workspace." },
       { type: "heading", level: 3, id: "next-steps", text: "Next steps" },
       { type: "list", items: [
         "**Reuse schemas** \u2014 save your schema with `POST /v1/schemas`, then pass `schema_id` on future extractions.",
         "**Large documents** \u2014 files >5 pages return `202 Accepted` with a `poll_url`. See [Processing Modes](extract-processing-mode).",
         "**Webhooks** \u2014 receive results via `extraction.complete` events instead of polling. See [Webhook Events](webhook-events).",
-        "**Batch mode** \u2014 process at 50% cost with `processing_mode=batch`. See [Batches](batches)."
+        "**Batch mode** \u2014 process at 50% cost with `processing_mode=batch`. See [Batches](batches).",
+        "**Credits** \u2014 check your balance anytime with `GET /v1/credits/balance`. See [Credits](credits-balance)."
       ] }
     ],
     related: [
       { label: "POST /v1/extract", slug: "post-extract" },
+      { label: "Filter Documents", slug: "filter-documents" },
       { label: "Schema Formats", slug: "extract-schemas" },
       { label: "Processing Modes", slug: "extract-processing-mode" }
     ],
     faq: [
-      { question: "How do I get started with the Talonic API?", answer: "Set your TALONIC_API_KEY environment variable, then send a file with an inline schema to POST /v1/extract. Documents \u22645 pages return results immediately in sync mode." },
-      { question: "Do I need to create a schema first?", answer: "No. You can pass an inline schema as a JSON object on your first extraction. Save it with POST /v1/schemas later for reuse." }
+      { question: "How do I get started with the Talonic API?", answer: "Three modes: (1) send a file with no schema for auto-detect, (2) send a file with a schema for exact extraction, (3) POST /v1/documents/filter to query already-ingested data." },
+      { question: "Do I need to create a schema first?", answer: "No. Mode 1 auto-detects all fields. Mode 2 accepts an inline schema. Save it with POST /v1/schemas later for reuse." },
+      { question: "Can I query previously extracted data without re-extracting?", answer: "Yes. POST /v1/documents/filter lets you search across all previously extracted documents by field values. No AI cost \u2014 ingest once, query forever." }
     ],
-    mentions: ["curl", "quick start", "sync mode", "TALONIC_API_KEY"]
+    mentions: ["curl", "quick start", "sync mode", "three modes", "auto-detect", "filter", "query", "cost headers"]
   },
   {
     slug: "pagination",
@@ -4851,9 +4872,34 @@ var sections18 = [
           { name: "400", type: "invalid_options", description: "The options field is not valid JSON." },
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "422", type: "extraction_failed", description: "Extraction completed but produced no usable output. Check the document quality or schema definition." },
-          { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
+          { name: "429", type: "rate_limited", description: "Too many requests. Check X-RateLimit-Reset for when the window resets." }
         ]
-      }
+      },
+      { type: "heading", level: 2, id: "post-extract-cost-headers", text: "Cost Headers" },
+      { type: "paragraph", text: "Synchronous 200 responses include cost transparency headers so you can track spend per call without a separate API round-trip:" },
+      {
+        type: "param-table",
+        title: "Cost response headers",
+        params: [
+          { name: "X-Talonic-Cost-Credits", type: "integer", description: "Credits consumed by this extraction." },
+          { name: "X-Talonic-Cost-EUR", type: "number", description: "EUR cost of this extraction." },
+          { name: "X-Talonic-Balance-Credits", type: "integer", description: "Remaining credit balance after this call." },
+          { name: "X-Talonic-Cells-Resolved-Registry", type: "integer", description: "Fields resolved from the registry (no AI cost)." },
+          { name: "X-Talonic-Cells-Resolved-AI", type: "integer", description: "Fields resolved by the AI model." }
+        ]
+      },
+      {
+        type: "code",
+        language: "bash",
+        title: "Cost headers on a sync response",
+        code: `HTTP/1.1 200 OK
+X-Talonic-Cost-Credits: 12
+X-Talonic-Cost-EUR: 0.012
+X-Talonic-Balance-Credits: 64918
+X-Talonic-Cells-Resolved-Registry: 3
+X-Talonic-Cells-Resolved-AI: 5`
+      },
+      { type: "callout", text: "Cost headers are only present on synchronous (200) responses. For async (202) extractions, check the credits balance endpoint or listen for the `extraction.complete` webhook which includes cost data." }
     ],
     related: [
       { label: "Schema Formats", slug: "extract-schemas" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talonic/docs",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "description": "Talonic documentation components — API Reference & Platform Guide",
   "license": "UNLICENSED",
   "private": false,