@talonic/docs 0.20.26 → 0.20.28

package/dist/content.js

@@ -1,5 +1,5 @@
 // src/content/helpers.ts
-function deriveBreadcrumbs(sections61, leafId, domain) {
+function deriveBreadcrumbs(sections62, leafId, domain) {
   const domainLabels = {
     api: "API Reference",
     platform: "Platform Guide",
@@ -10,20 +10,20 @@ function deriveBreadcrumbs(sections61, leafId, domain) {
     label: domainLabels[domain] ?? domain,
     slug: domain
   };
-  for (const group of sections61) {
+  for (const group of sections62) {
     const child = group.children?.find((c) => c.id === leafId);
     if (child) {
       return [root, { label: group.label, slug: group.id }, { label: child.label, slug: child.id }];
     }
   }
-  const topLevel = sections61.find((s) => s.id === leafId);
+  const topLevel = sections62.find((s) => s.id === leafId);
   if (topLevel) {
     return [root, { label: topLevel.label, slug: topLevel.id }];
   }
   return [root];
 }
-function derivePrevNext(sections61, leafId) {
-  const flat = sections61.flatMap(
+function derivePrevNext(sections62, leafId) {
+  const flat = sections62.flatMap(
     (s) => s.children ?? [{ id: s.id, label: s.label }]
   );
   const idx = flat.findIndex((c) => c.id === leafId);
@@ -284,7 +284,11 @@ var API_NAV_SECTIONS = [
     { id: "cost-headers", label: "Cost Headers" }
   ] },
   { id: "usage", label: "Usage", children: [
-    { id: "usage-overview", label: "Overview" }
+    { id: "usage-overview", label: "Overview" },
+    { id: "usage-credits", label: "Credit Usage" }
+  ] },
+  { id: "pricing", label: "Pricing", children: [
+    { id: "pricing-overview", label: "Pricing Catalog" }
   ] },
   { id: "document-types", label: "Document Types", children: [
     { id: "list-document-types", label: "Document Types" }
@@ -25873,7 +25877,8 @@ var sections47 = [
       { type: "paragraph", text: "Two endpoints cover aggregate and document-level views. The aggregate endpoint returns workspace-wide totals with a breakdown by operation type and model over a configurable date range. The per-document endpoint drills into a specific document to show every AI call made during its processing lifecycle, including cache token utilization and per-operation cost estimates." },
       { type: "paragraph", text: "Cost estimates are computed from the model-specific token pricing at the time of the API call. Input tokens, output tokens, and cache read tokens are each priced at their respective rates. Cache read tokens represent prompt cache hits where previously cached input was reused at a significantly lower rate than fresh input tokens \u2014 high cache utilization indicates efficient prompt reuse across similar documents." },
       { type: "paragraph", text: "Usage data is available immediately after each AI operation completes. There is no delay or batching \u2014 the token counts and cost estimates are recorded synchronously as part of the operation lifecycle. Historical data is retained indefinitely and can be queried over any date range." },
-      { type: "callout", variant: "info", text: "Usage tracking is automatic and requires no configuration. Every AI operation performed by the platform \u2014 extraction, classification, triage, resolution, matching \u2014 is metered and available through these endpoints." },
+      { type: "callout", variant: "info", text: "Usage tracking is automatic and requires no configuration. Every AI operation performed by the platform (extraction, classification, triage, resolution, matching) is metered and available through these endpoints." },
+      { type: "callout", variant: "info", text: "There are two usage views. This endpoint (`GET /v1/usage`) reports raw AI token and call counts. `GET /v1/usage/credits` (see Credit Usage below) reports per-function CREDIT consumption from the customer-pay ledger. Use the first to understand token cost, the second to see where credits went." },
       {
         type: "endpoint",
         method: "GET",
@@ -26045,11 +26050,207 @@ var sections47 = [
       { question: "Why might a document have multiple usage entries?", answer: "A single document can trigger several AI operations during processing: OCR classification, document type resolution, field extraction (potentially chunked for large documents), and quality verification passes. Each operation is logged as a separate entry with its own token counts and cost." }
     ],
     mentions: ["token usage", "cost analysis", "AI operations", "input tokens", "output tokens", "cache tokens", "usage tracking"]
+  },
+  {
+    slug: "usage-credits",
+    parentSlug: "usage",
+    title: "Credit Usage by Function",
+    seoTitle: "Credit Usage API \u2014 Per-Function Credit Spend \u2014 Talonic Docs",
+    description: "See where your credits went: per-function credit consumption (extraction, structuring, intelligence operations) from the customer-pay ledger, over a trailing window.",
+    content: [
+      { type: "paragraph", text: 'The Credit Usage endpoint reports how many credits the workspace spent on each platform function over a trailing window. Where the aggregate Usage endpoint reports raw AI token counts, this endpoint reports the customer-pay view: the credits actually charged, grouped by the function that incurred them. It answers "where did my credits go" rather than "how many tokens did the platform burn".' },
+      { type: "paragraph", text: "Consumption is grouped by `operation_type`, the billable function (for example page ingestion, structuring cells, or intelligence operations such as matching and reconciliation). Each group reports the number of charged operations and the total credits they consumed, and the response carries a workspace total across all functions. The breakdown is ordered by spend, highest first, so the dominant cost driver is the first row." },
+      { type: "paragraph", text: "The window defaults to the last 30 days and is configurable from 1 to 365 days through the `days` query parameter. The endpoint reads the credit transaction ledger directly, so the figures reconcile exactly with the balance and transaction history reported by the Credits API. To convert credits to euros, divide by the credits-per-EUR rate returned by the Pricing API (1,000 credits per EUR at the standard rate)." },
+      { type: "paragraph", text: 'This endpoint requires an API key with the `read` scope. It is the natural companion to the Credits Balance endpoint: balance answers "how much is left", and credit usage answers "what consumed it". Together they let an agent monitor burn by function and decide whether to shift work to batch mode or trim a particular operation.' },
+      { type: "callout", variant: "info", text: "Per-function rows populate as billable operations are charged. While credit metering runs in shadow mode the ledger records what each operation would cost without deducting, so the breakdown can legitimately read as empty until enforcement is enabled for the workspace." },
+      {
+        type: "endpoint",
+        method: "GET",
+        path: "/v1/usage/credits",
+        summary: "Get per-function credit consumption.",
+        description: "Returns credit consumption grouped by platform function over the requested window, plus the workspace total. Requires the read scope.",
+        blocks: [
+          {
+            type: "param-table",
+            title: "Query parameters",
+            params: [
+              { name: "days", type: "integer", description: "Trailing reporting window in days. Default 30, clamped between 1 and 365." }
+            ]
+          }
+        ]
+      },
+      { type: "heading", level: 2, id: "usage-credits-response", text: "Response" },
+      {
+        type: "param-table",
+        title: "Response fields",
+        params: [
+          { name: "period_days", type: "integer", description: "Length of the reporting window in days." },
+          { name: "total_credits", type: "integer", description: "Total credits consumed across all functions in the window." },
+          { name: "by_function", type: "array", description: "Per-function breakdown, highest spend first." },
+          { name: "by_function[].operation_type", type: "string", description: "The platform function (billable operation type) that consumed credits." },
+          { name: "by_function[].operations", type: "integer", description: "Number of charged operations of this type in the window." },
+          { name: "by_function[].credits", type: "integer", description: "Total credits consumed by this function." }
+        ]
+      },
+      {
+        type: "code",
+        title: "Response \u2014 Credit usage by function",
+        code: `{
+  "period_days": 30,
+  "total_credits": 48200,
+  "by_function": [
+    { "operation_type": "page_ingest", "operations": 412, "credits": 41200 },
+    { "operation_type": "structuring_cell", "operations": 300, "credits": 6000 },
+    { "operation_type": "intelligence_op", "operations": 10, "credits": 1000 }
+  ]
+}`
+      },
+      {
+        type: "code",
+        title: "cURL \u2014 Credit usage for the last 7 days",
+        code: `curl -X GET "https://api.talonic.ai/v1/usage/credits?days=7" \\
+  -H "Authorization: Bearer tlnc_your_api_key"`
+      },
+      { type: "heading", level: 2, id: "usage-credits-errors", text: "Errors" },
+      {
+        type: "param-table",
+        title: "Error responses",
+        params: [
+          { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
+          { name: "403", type: "forbidden", description: "API key lacks the read scope." },
+          { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
+        ]
+      }
+    ],
+    related: [
+      { label: "Pricing Catalog", slug: "pricing-overview" },
+      { label: "Credits Balance", slug: "credits-balance" },
+      { label: "Usage Overview", slug: "usage-overview" }
+    ],
+    faq: [
+      { question: "How is this different from the aggregate Usage endpoint?", answer: "The aggregate Usage endpoint reports raw AI token and call counts (the technical view). Credit Usage reports the credits actually charged per function from the customer-pay ledger (the billing view). One tells you token cost; the other tells you where your credits went." },
+      { question: "What does operation_type contain?", answer: "It is the billable function that consumed the credits, such as page_ingest for document ingestion, structuring_cell for cells filled by model reasoning, or intelligence_op for matching, cases, and reconciliation. The values match the unit identifiers in the Pricing catalog." },
+      { question: "Why is my breakdown empty?", answer: "Per-function rows appear once billable operations are charged. While metering runs in shadow mode the ledger records what each operation would cost without deducting, so the breakdown can be empty until enforcement is enabled. The Pricing endpoint still returns the rates in the meantime." },
+      { question: "How do I convert credits to euros?", answer: "Divide credits by the credits_per_eur value returned by the Pricing endpoint (1,000 credits per EUR at the standard rate). For example, 41,200 credits of page ingestion is 41.20 EUR." }
+    ],
+    mentions: ["credit usage", "per-function spend", "credit consumption", "billing", "burn rate", "operation type", "credit ledger"]
   }
 ];
 
-// src/content/api/document-types.ts
+// src/content/api/pricing.ts
 var sections48 = [
+  {
+    slug: "pricing-overview",
+    parentSlug: "pricing",
+    title: "Pricing Catalog",
+    seoTitle: "Pricing API \u2014 Machine-Readable Credit Catalog \u2014 Talonic Docs",
+    description: "Fetch the public credit pricing catalog: fixed per-unit credit rates, EUR equivalents, the credits-per-EUR conversion, and processing-mode multipliers, so an agent can predict spend before running anything.",
+    content: [
+      { type: "paragraph", text: "The Pricing API exposes the credit catalog that governs what every billable Talonic operation costs. It returns fixed per-unit rates rather than fluctuating token costs, so the price of a planned job is known in advance. An agent can call this endpoint, read the per-page and per-cell rates, and compute the exact credit cost of a workload before spending a single credit." },
+      { type: "paragraph", text: 'Pricing is denominated in credits, the universal unit for all platform operations. The catalog also returns the credits-per-EUR conversion rate and the EUR equivalent of each unit, so the same response answers both "how many credits will this cost" and "how much is that in euros". One page of document ingestion costs 100 credits, which is 0.10 EUR at the standard rate of 1,000 credits per EUR.' },
+      { type: "paragraph", text: "The catalog separates the operations that carry a cost from the ones that are free. Document page ingestion, structuring cells filled by fresh model reasoning, and intelligence operations (matching, cases, reconciliation) are billable. Field Registry resolved cells, delivery, and validation are free: reusing knowledge the platform already captured, delivering data you already paid to produce, and checking quality should never carry a surcharge." },
+      { type: "paragraph", text: "Processing-mode multipliers apply on top of the per-unit rate. Batch mode runs at half cost (a 0.5x multiplier) in exchange for a 48-hour delivery window, while realtime processing runs at the full 1.0x rate. To quote a batch workload, multiply the per-unit credits by the unit count and then by the batch multiplier. The multipliers are returned in the same response so a caller never has to hardcode them." },
+      { type: "callout", variant: "info", text: "This endpoint is public and unauthenticated. An agent can read pricing before it signs up or provisions an API key, which makes it the right first call when deciding whether a workload fits a budget." },
+      {
+        type: "endpoint",
+        method: "GET",
+        path: "/v1/pricing",
+        summary: "Get the credit pricing catalog.",
+        description: "Returns the fixed per-unit credit rates, their EUR equivalents, the credits-per-EUR conversion rate, and processing-mode multipliers. No authentication required.",
+        blocks: [
+          {
+            type: "param-table",
+            title: "Query parameters",
+            params: [
+              { name: "(none)", type: "", description: "This endpoint takes no parameters." }
+            ]
+          }
+        ]
+      },
+      { type: "heading", level: 2, id: "pricing-response", text: "Response" },
+      {
+        type: "param-table",
+        title: "Response fields",
+        params: [
+          { name: "currency", type: "string", description: "Billing currency for the EUR equivalents. Always EUR." },
+          { name: "credits_per_eur", type: "number", description: "Conversion rate between credits and EUR (1,000 credits = 1 EUR at the standard rate)." },
+          { name: "multipliers", type: "object", description: "Processing-mode multipliers applied on top of per-unit cost, keyed by mode (e.g. realtime: 1, batch: 0.5)." },
+          { name: "units", type: "array", description: "The per-unit pricing catalog." },
+          { name: "units[].unit", type: "string", description: "Billable unit identifier (page_ingest, structuring_cell, registry_resolved_cell, intelligence_op, delivery, validation)." },
+          { name: "units[].label", type: "string", description: "Human-readable label for the unit." },
+          { name: "units[].credits", type: "number", description: "Credits charged per single unit. Zero for free units." },
+          { name: "units[].eur", type: "number", description: "EUR equivalent of one unit at the current conversion rate." },
+          { name: "units[].free", type: "boolean", description: "Whether the unit is free (credits equal zero)." }
+        ]
+      },
+      {
+        type: "code",
+        title: "Response \u2014 Pricing catalog",
+        code: `{
+  "currency": "EUR",
+  "credits_per_eur": 1000,
+  "multipliers": { "realtime": 1, "batch": 0.5 },
+  "units": [
+    { "unit": "page_ingest", "label": "Document page ingestion", "credits": 100, "eur": 0.1, "free": false },
+    { "unit": "structuring_cell", "label": "Structuring cell (LLM-reasoned)", "credits": 20, "eur": 0.02, "free": false },
+    { "unit": "registry_resolved_cell", "label": "Structuring cell (Field Registry resolved)", "credits": 0, "eur": 0, "free": true },
+    { "unit": "intelligence_op", "label": "Intelligence operation (matching, cases, reconciliation)", "credits": 100, "eur": 0.1, "free": false },
+    { "unit": "delivery", "label": "Delivery (webhook / export)", "credits": 0, "eur": 0, "free": true },
+    { "unit": "validation", "label": "Validation / quality check", "credits": 0, "eur": 0, "free": true }
+  ]
+}`
+      },
+      { type: "heading", level: 2, id: "pricing-estimate-example", text: "Estimating a Workload" },
+      { type: "paragraph", text: "To estimate the cost of a job, read the relevant unit rate and multiply by the expected unit count, then apply the processing-mode multiplier. A realtime extraction of a 20-page document costs 20 pages times 100 credits, which is 2,000 credits (2.00 EUR). The same workload submitted in batch mode costs 1,000 credits (1.00 EUR) at the 0.5x multiplier. Registry-resolved cells add nothing, so a document whose fields are answered entirely from the Field Registry incurs only its page-ingestion cost." },
+      {
+        type: "code",
+        title: "cURL \u2014 Fetch the pricing catalog",
+        code: `curl -X GET "https://api.talonic.ai/v1/pricing"`
+      },
+      {
+        type: "code",
+        title: "TypeScript \u2014 Predict spend before running",
+        code: `import { Talonic } from "@talonic/node"
+
+const talonic = new Talonic({ apiKey: process.env.TALONIC_API_KEY! })
+
+const pricing = await talonic.pricing.get()
+const perPage = pricing.units.find((u) => u.unit === "page_ingest")!
+
+const pages = 20
+const realtimeCredits = perPage.credits * pages
+const batchCredits = realtimeCredits * pricing.multipliers.batch
+
+console.log(\`Realtime: \${realtimeCredits} credits (\${realtimeCredits / pricing.credits_per_eur} EUR)\`)
+console.log(\`Batch:    \${batchCredits} credits (\${batchCredits / pricing.credits_per_eur} EUR)\`)`
+      },
+      { type: "heading", level: 2, id: "pricing-errors", text: "Errors" },
+      {
+        type: "param-table",
+        title: "Error responses",
+        params: [
+          { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
+        ]
+      }
+    ],
+    related: [
+      { label: "Credit Usage by Function", slug: "usage-credits" },
+      { label: "Credits Balance", slug: "credits-balance" },
+      { label: "Usage Overview", slug: "usage-overview" }
+    ],
+    faq: [
+      { question: "Do I need an API key to read pricing?", answer: "No. The pricing endpoint is public and unauthenticated, so an agent can fetch rates before signing up or provisioning a key. This makes it the natural first call when deciding whether a workload fits a budget." },
+      { question: "How is the credit cost of an operation calculated?", answer: "Multiply the per-unit credit rate by the number of units (pages, structuring cells, or intelligence operations), then apply the processing-mode multiplier (1.0 for realtime, 0.5 for batch). The catalog returns both the per-unit rates and the multipliers, so the full quote is computable client-side." },
+      { question: "Which operations are free?", answer: "Field Registry resolved cells, delivery, and validation cost zero credits. Reusing previously captured knowledge, delivering data you already paid to produce, and checking quality do not carry a surcharge. Only fresh ingestion, fresh model reasoning, and intelligence operations are billable." },
+      { question: "Why are prices in credits instead of EUR?", answer: "Credits are the universal unit across every platform operation, which keeps a single balance and a single rate table regardless of operation type. The catalog also returns the credits-per-EUR conversion and the EUR equivalent of each unit, so you can present either view." },
+      { question: "How do batch discounts work?", answer: "Batch mode applies a 0.5x multiplier to every per-unit rate in exchange for a 48-hour delivery window. The multiplier is returned under multipliers.batch so you never have to hardcode it; multiply your realtime estimate by that value to get the batch cost." }
+    ],
+    mentions: ["pricing", "credit catalog", "cost estimation", "per-page pricing", "batch discount", "credits per EUR", "budget", "agent pricing"]
+  }
+];
+
+// src/content/api/document-types.ts
+var sections49 = [
   {
     slug: "list-document-types",
     parentSlug: "document-types",
@@ -26206,7 +26407,7 @@ var sections48 = [
 ];
 
 // src/content/api/dialects.ts
-var sections49 = [
+var sections50 = [
   {
     slug: "list-dialects",
     parentSlug: "dialects",
@@ -26735,7 +26936,7 @@ var sections49 = [
 ];
 
 // src/content/api/fields.ts
-var sections50 = [
+var sections51 = [
   {
     slug: "list-fields",
     parentSlug: "fields",
@@ -27154,7 +27355,7 @@ var sections50 = [
 ];
 
 // src/content/api/data-products.ts
-var sections51 = [
+var sections52 = [
   {
     slug: "list-data-products",
     parentSlug: "data-products",
@@ -27646,7 +27847,7 @@ var sections51 = [
 ];
 
 // src/content/api/data-policies.ts
-var sections52 = [
+var sections53 = [
   {
     slug: "list-data-policies",
     parentSlug: "data-policies",
@@ -28334,7 +28535,7 @@ var sections52 = [
 ];
 
 // src/content/api/record-sets.ts
-var sections53 = [
+var sections54 = [
   {
     slug: "list-record-sets",
     parentSlug: "record-sets",
@@ -28794,7 +28995,7 @@ var sections53 = [
 ];
 
 // src/content/api/pipelines.ts
-var sections54 = [
+var sections55 = [
   {
     slug: "run-pipeline",
     parentSlug: "pipelines",
@@ -29351,7 +29552,7 @@ var sections54 = [
 ];
 
 // src/content/api/field-reviews.ts
-var sections55 = [
+var sections56 = [
   {
     slug: "list-field-reviews",
     parentSlug: "field-reviews",
@@ -29966,7 +30167,7 @@ dec_uuid_1,a1b2c3d4-e5f6-7890-abcd-ef1234567890,lease_oct.pdf,total_amount,gate,
 ];
 
 // src/content/api/spec-config.ts
-var sections56 = [
+var sections57 = [
   {
     slug: "get-spec-rail",
     parentSlug: "spec-config",
@@ -30958,7 +31159,7 @@ var sections56 = [
 ];
 
 // src/content/api/reconciliation.ts
-var sections57 = [
+var sections58 = [
   {
     slug: "analyze-reconciliation",
     parentSlug: "reconciliation",
@@ -31530,7 +31731,7 @@ var sections57 = [
 ];
 
 // src/content/api/matching-packages.ts
-var sections58 = [
+var sections59 = [
   {
     slug: "create-matching-package-config",
     parentSlug: "matching-packages",
@@ -32423,7 +32624,7 @@ talonic --help` }
 ];
 
 // src/content/sdk/index.ts
-var sections59 = sections_default;
+var sections60 = sections_default;
 
 // src/content/mcp/sections.json
 var sections_default2 = [
@@ -34918,7 +35119,7 @@ var sections_default2 = [
 ];
 
 // src/content/mcp/index.ts
-var sections60 = sections_default2;
+var sections61 = sections_default2;
 
 // src/content/index.ts
 var ALL_PLATFORM_RAW = [
@@ -34981,10 +35182,11 @@ var ALL_API_RAW = [
   ...sections56,
   ...sections57,
   ...sections58,
+  ...sections59,
   ...sections46
 ];
-var ALL_SDK_RAW = [...sections59];
-var ALL_MCP_RAW = [...sections60];
+var ALL_SDK_RAW = [...sections60];
+var ALL_MCP_RAW = [...sections61];
 function enrich(raw, navSections, domain) {
   return raw.map((r) => {
     const { prev, next } = derivePrevNext(navSections, r.slug);

package/dist/index.js

@@ -6997,7 +6997,11 @@ var API_NAV_SECTIONS = [
     { id: "cost-headers", label: "Cost Headers" }
   ] },
   { id: "usage", label: "Usage", children: [
-    { id: "usage-overview", label: "Overview" }
+    { id: "usage-overview", label: "Overview" },
+    { id: "usage-credits", label: "Credit Usage" }
+  ] },
+  { id: "pricing", label: "Pricing", children: [
+    { id: "pricing-overview", label: "Pricing Catalog" }
   ] },
   { id: "document-types", label: "Document Types", children: [
     { id: "list-document-types", label: "Document Types" }
@@ -7201,7 +7205,8 @@ var API_SECTION_META = [
   { id: "routing-rules", title: "Routing Rules API", description: "Document routing rules \u2014 create, manage, and reorder priority-based rules for automatic document workflow assignment." },
   { id: "reference-data", title: "Reference Data API", description: "Upload, list, and manage reference data tables used as lookup targets for matching configurations. Supports JSON upload, paginated row access, and CSV export." },
   { id: "fields", title: "Fields API", description: "Read-only access to the field registry \u2014 list fields with filters, cross-schema harmonization analysis, field detail with occurrences, and embedding-based similarity search." },
-  { id: "usage", title: "Usage API", description: "AI token usage tracking \u2014 aggregate stats by operation type and model, per-document usage breakdown with cost estimates." },
+  { id: "usage", title: "Usage API", description: "AI token usage tracking \u2014 aggregate stats by operation type and model, per-document usage breakdown with cost estimates, and per-function credit consumption." },
+  { id: "pricing", title: "Pricing API", description: "Public machine-readable credit pricing catalog \u2014 fixed per-unit credit rates, EUR equivalents, the credits-per-EUR conversion, and processing-mode multipliers, so an agent can predict spend before running." },
   { id: "document-types", title: "Document Types API", description: "Document type classification \u2014 list workspace document types by frequency and retrieve the 529-type ontology taxonomy." },
   { id: "registry", title: "Registry API", description: "Query previously-extracted field values across all documents \u2014 ingest once, query forever. Zero re-extraction, zero AI calls." },
   { id: "billing", title: "Billing API", description: "Billing settings, auto top-up for AI agents, and cost response headers on extraction requests." },