@talonic/docs 0.21.0 → 0.21.1

package/dist/seo.js

@@ -173,6 +173,14 @@ var openapi_default = {
     {
       name: "Webhooks",
       description: "Outbound HMAC-signed event webhooks \u2014 configure endpoints and read the event catalog, delivery format, signature scheme, and retry policy."
+    },
+    {
+      name: "Events",
+      description: "The tenant event feed \u2014 the timeline of everything that happened (extractions, run completions, review verdicts, delivery outcomes). The same rows webhooks fan out from, so missed webhook deliveries can be reconciled against this feed."
+    },
+    {
+      name: "Provenance",
+      description: "Document-level provenance \u2014 deterministic (subject, predicate, object) claims synthesized from captured fields and spans, each carrying its evidence quote and grounded flag."
     }
   ],
   paths: {
@@ -369,6 +377,9 @@ var openapi_default = {
           "401": {
             $ref: "#/components/responses/Unauthorized"
           },
+          "402": {
+            $ref: "#/components/responses/InsufficientCredits"
+          },
           "403": {
             $ref: "#/components/responses/Forbidden"
           },
@@ -9407,17 +9418,102 @@ var openapi_default = {
         }
       }
     },
+    "/v1/billing/packs": {
+      get: {
+        operationId: "getBillingPacks",
+        summary: "List purchasable credit packs",
+        description: "The self-serve credit-purchase catalog: flat prepaid packs\n(1,000 credits = 1 EUR, no volume bonuses). Buy via the checkout URL\nfrom `GET /v1/billing/upgrade-link`.\n",
+        tags: [
+          "Billing"
+        ],
+        responses: {
+          "200": {
+            description: "Credit pack catalog.",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  required: [
+                    "currency",
+                    "packs"
+                  ],
+                  properties: {
+                    currency: {
+                      type: "string",
+                      example: "EUR"
+                    },
+                    packs: {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        required: [
+                          "key",
+                          "eur",
+                          "credits"
+                        ],
+                        properties: {
+                          key: {
+                            type: "string",
+                            example: "50"
+                          },
+                          lookupKey: {
+                            type: "string",
+                            example: "credits_pack_50"
+                          },
+                          eur: {
+                            type: "number",
+                            example: 50
+                          },
+                          credits: {
+                            type: "integer",
+                            example: 5e4
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            $ref: "#/components/responses/Unauthorized"
+          },
+          "429": {
+            $ref: "#/components/responses/RateLimitExceeded"
+          }
+        }
+      }
+    },
     "/v1/billing/upgrade-link": {
       get: {
         operationId: "getBillingUpgradeLink",
-        summary: "Get an upgrade link",
-        description: 'Returns a URL the agent can hand to a human to upgrade the plan or add\npayment. When a hosted billing portal exists this is a portal session\nURL; until then it is a deep link into the dashboard billing settings\n(`provider: "dashboard"`). A human must complete the upgrade.\n',
+        summary: "Get a buy-credits link",
+        description: 'Returns a URL the agent hands to a human to buy prepaid credits. With\nbilling configured this is a real Stripe hosted-Checkout session\n(`provider: "stripe"`) for the selected pack; credits are available\nseconds after the human completes payment. Falls back to a dashboard\nbilling deep link (`provider: "dashboard"`) on deployments without\nStripe. A human must complete the payment either way.\n',
         tags: [
           "Billing"
         ],
+        parameters: [
+          {
+            name: "pack",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string",
+              enum: [
+                "10",
+                "50",
+                "250",
+                "1000"
+              ],
+              default: "50"
+            },
+            description: "Credit pack to check out (see `GET /v1/billing/packs`)."
+          }
+        ],
         responses: {
           "200": {
-            description: "Upgrade link.",
+            description: "Buy-credits link.",
             content: {
               "application/json": {
                 schema: {
@@ -9431,16 +9527,20 @@ var openapi_default = {
                     url: {
                       type: "string",
                       format: "uri",
-                      example: "https://app.talonic.com/settings/billing?upgrade=1"
+                      example: "https://checkout.stripe.com/c/pay/cs_test_..."
                     },
                     provider: {
                       type: "string",
-                      description: "'dashboard' (deep link) or 'stripe' (portal session) once a portal exists.",
-                      example: "dashboard"
+                      description: "'stripe' (hosted Checkout session) or 'dashboard' (deep link fallback).",
+                      example: "stripe"
                     },
                     requires_human: {
                       type: "boolean"
                     },
+                    pack: {
+                      type: "object",
+                      description: "The selected pack (stripe provider only)."
+                    },
                     message: {
                       type: "string"
                     }
@@ -17362,6 +17462,99 @@ var openapi_default = {
         }
       }
     },
+    "/v1/events": {
+      get: {
+        tags: [
+          "Events"
+        ],
+        summary: "List tenant events",
+        description: "Newest-first feed of platform events (document.extracted, run.*.completed/failed, result.flagged/approved/rejected, delivery.item.*, case.resolved). Alias of /v1/delivery/events at the API root.\n",
+        operationId: "listEvents",
+        security: [
+          {
+            BearerAuth: []
+          }
+        ],
+        parameters: [
+          {
+            name: "event_type",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            },
+            description: "Filter by event type, e.g. document.extracted"
+          },
+          {
+            name: "limit",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer",
+              default: 50,
+              maximum: 200
+            }
+          },
+          {
+            name: "offset",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer",
+              default: 0
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "{ data: [{ id, event_type, payload, created_at }], total, limit, offset }"
+          }
+        }
+      }
+    },
+    "/v1/documents/{id}/claims": {
+      get: {
+        tags: [
+          "Provenance"
+        ],
+        summary: "List a document's provenance claims",
+        description: "Deterministic atomic (subject, predicate, object) claims synthesized from the document's captured fields + provenance spans (no LLM). Each claim carries its evidence quote, grounded flag, and confidence. Field-level span detail lives on GET /v1/field-reviews/{docId}/{fieldKey}.\n",
+        operationId: "listDocumentClaims",
+        security: [
+          {
+            BearerAuth: []
+          }
+        ],
+        parameters: [
+          {
+            name: "id",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string",
+              format: "uuid"
+            }
+          },
+          {
+            name: "grounded",
+            in: "query",
+            required: false,
+            schema: {
+              type: "boolean"
+            },
+            description: "true = only span-backed claims"
+          }
+        ],
+        responses: {
+          "200": {
+            description: "{ data: [{ subject, predicate, object, qualifier, evidence, segment_id, grounded, confidence, origin }], total }"
+          },
+          "404": {
+            description: "Document not found or not owned by the caller."
+          }
+        }
+      }
+    },
     "/v1/webhooks/events": {
       get: {
         tags: [
@@ -18528,7 +18721,7 @@ var openapi_default = {
               statusCode: 429,
               code: "QUOTA_EXCEEDED",
               error: "Too Many Requests",
-              message: "Daily extract request limit (50) reached. Resets at midnight UTC.",
+              message: "Daily extract request ceiling reached. Resets at midnight UTC. Spend is governed by credits, not this abuse ceiling.",
               retryable: true,
               timestamp: "2026-04-25T23:45:00.000Z",
               path: "/v1/extract"
@@ -18536,6 +18729,48 @@ var openapi_default = {
           }
         }
       },
+      InsufficientCredits: {
+        description: "Insufficient credits (402). The body is the agent-actionable contract:\n`buy_credits_url` is where a human completes a purchase (see also\n`GET /v1/billing/upgrade-link` for a direct Stripe Checkout link), and\n`pricing_url` is the machine-readable rate catalog. Free workspaces\nreceive 5,000 credits monthly; purchased credits top up the same\nbalance.\n",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              required: [
+                "error",
+                "message",
+                "required_credits",
+                "balance_credits"
+              ],
+              properties: {
+                error: {
+                  type: "string",
+                  example: "insufficient_credits"
+                },
+                message: {
+                  type: "string"
+                },
+                required_credits: {
+                  type: "integer",
+                  example: 100
+                },
+                balance_credits: {
+                  type: "integer",
+                  example: 0
+                },
+                buy_credits_url: {
+                  type: "string",
+                  format: "uri",
+                  example: "https://app.talonic.com/settings/billing?buy=1"
+                },
+                pricing_url: {
+                  type: "string",
+                  example: "/v1/pricing"
+                }
+              }
+            }
+          }
+        }
+      },
       InternalServerError: {
         description: "An unexpected error occurred.",
         content: {

package/openapi.json

@@ -172,6 +172,14 @@
     {
       "name": "Webhooks",
       "description": "Outbound HMAC-signed event webhooks — configure endpoints and read the event catalog, delivery format, signature scheme, and retry policy."
+    },
+    {
+      "name": "Events",
+      "description": "The tenant event feed — the timeline of everything that happened (extractions, run completions, review verdicts, delivery outcomes). The same rows webhooks fan out from, so missed webhook deliveries can be reconciled against this feed."
+    },
+    {
+      "name": "Provenance",
+      "description": "Document-level provenance — deterministic (subject, predicate, object) claims synthesized from captured fields and spans, each carrying its evidence quote and grounded flag."
     }
   ],
   "paths": {
@@ -368,6 +376,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "402": {
+            "$ref": "#/components/responses/InsufficientCredits"
+          },
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
@@ -9387,17 +9398,102 @@
         }
       }
     },
+    "/v1/billing/packs": {
+      "get": {
+        "operationId": "getBillingPacks",
+        "summary": "List purchasable credit packs",
+        "description": "The self-serve credit-purchase catalog: flat prepaid packs\n(1,000 credits = 1 EUR, no volume bonuses). Buy via the checkout URL\nfrom `GET /v1/billing/upgrade-link`.\n",
+        "tags": [
+          "Billing"
+        ],
+        "responses": {
+          "200": {
+            "description": "Credit pack catalog.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "currency",
+                    "packs"
+                  ],
+                  "properties": {
+                    "currency": {
+                      "type": "string",
+                      "example": "EUR"
+                    },
+                    "packs": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "key",
+                          "eur",
+                          "credits"
+                        ],
+                        "properties": {
+                          "key": {
+                            "type": "string",
+                            "example": "50"
+                          },
+                          "lookupKey": {
+                            "type": "string",
+                            "example": "credits_pack_50"
+                          },
+                          "eur": {
+                            "type": "number",
+                            "example": 50
+                          },
+                          "credits": {
+                            "type": "integer",
+                            "example": 50000
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "429": {
+            "$ref": "#/components/responses/RateLimitExceeded"
+          }
+        }
+      }
+    },
     "/v1/billing/upgrade-link": {
       "get": {
         "operationId": "getBillingUpgradeLink",
-        "summary": "Get an upgrade link",
-        "description": "Returns a URL the agent can hand to a human to upgrade the plan or add\npayment. When a hosted billing portal exists this is a portal session\nURL; until then it is a deep link into the dashboard billing settings\n(`provider: \"dashboard\"`). A human must complete the upgrade.\n",
+        "summary": "Get a buy-credits link",
+        "description": "Returns a URL the agent hands to a human to buy prepaid credits. With\nbilling configured this is a real Stripe hosted-Checkout session\n(`provider: \"stripe\"`) for the selected pack; credits are available\nseconds after the human completes payment. Falls back to a dashboard\nbilling deep link (`provider: \"dashboard\"`) on deployments without\nStripe. A human must complete the payment either way.\n",
         "tags": [
           "Billing"
         ],
+        "parameters": [
+          {
+            "name": "pack",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "10",
+                "50",
+                "250",
+                "1000"
+              ],
+              "default": "50"
+            },
+            "description": "Credit pack to check out (see `GET /v1/billing/packs`)."
+          }
+        ],
         "responses": {
           "200": {
-            "description": "Upgrade link.",
+            "description": "Buy-credits link.",
             "content": {
               "application/json": {
                 "schema": {
@@ -9411,16 +9507,20 @@
                     "url": {
                       "type": "string",
                       "format": "uri",
-                      "example": "https://app.talonic.com/settings/billing?upgrade=1"
+                      "example": "https://checkout.stripe.com/c/pay/cs_test_..."
                     },
                     "provider": {
                       "type": "string",
-                      "description": "'dashboard' (deep link) or 'stripe' (portal session) once a portal exists.",
-                      "example": "dashboard"
+                      "description": "'stripe' (hosted Checkout session) or 'dashboard' (deep link fallback).",
+                      "example": "stripe"
                     },
                     "requires_human": {
                       "type": "boolean"
                     },
+                    "pack": {
+                      "type": "object",
+                      "description": "The selected pack (stripe provider only)."
+                    },
                     "message": {
                       "type": "string"
                     }
@@ -17342,6 +17442,99 @@
         }
       }
     },
+    "/v1/events": {
+      "get": {
+        "tags": [
+          "Events"
+        ],
+        "summary": "List tenant events",
+        "description": "Newest-first feed of platform events (document.extracted, run.*.completed/failed, result.flagged/approved/rejected, delivery.item.*, case.resolved). Alias of /v1/delivery/events at the API root.\n",
+        "operationId": "listEvents",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "event_type",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by event type, e.g. document.extracted"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 50,
+              "maximum": 200
+            }
+          },
+          {
+            "name": "offset",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "{ data: [{ id, event_type, payload, created_at }], total, limit, offset }"
+          }
+        }
+      }
+    },
+    "/v1/documents/{id}/claims": {
+      "get": {
+        "tags": [
+          "Provenance"
+        ],
+        "summary": "List a document's provenance claims",
+        "description": "Deterministic atomic (subject, predicate, object) claims synthesized from the document's captured fields + provenance spans (no LLM). Each claim carries its evidence quote, grounded flag, and confidence. Field-level span detail lives on GET /v1/field-reviews/{docId}/{fieldKey}.\n",
+        "operationId": "listDocumentClaims",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "grounded",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            },
+            "description": "true = only span-backed claims"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "{ data: [{ subject, predicate, object, qualifier, evidence, segment_id, grounded, confidence, origin }], total }"
+          },
+          "404": {
+            "description": "Document not found or not owned by the caller."
+          }
+        }
+      }
+    },
     "/v1/webhooks/events": {
       "get": {
         "tags": [
@@ -18508,7 +18701,7 @@
               "statusCode": 429,
               "code": "QUOTA_EXCEEDED",
               "error": "Too Many Requests",
-              "message": "Daily extract request limit (50) reached. Resets at midnight UTC.",
+              "message": "Daily extract request ceiling reached. Resets at midnight UTC. Spend is governed by credits, not this abuse ceiling.",
               "retryable": true,
               "timestamp": "2026-04-25T23:45:00.000Z",
               "path": "/v1/extract"
@@ -18516,6 +18709,48 @@
           }
         }
       },
+      "InsufficientCredits": {
+        "description": "Insufficient credits (402). The body is the agent-actionable contract:\n`buy_credits_url` is where a human completes a purchase (see also\n`GET /v1/billing/upgrade-link` for a direct Stripe Checkout link), and\n`pricing_url` is the machine-readable rate catalog. Free workspaces\nreceive 5,000 credits monthly; purchased credits top up the same\nbalance.\n",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "required": [
+                "error",
+                "message",
+                "required_credits",
+                "balance_credits"
+              ],
+              "properties": {
+                "error": {
+                  "type": "string",
+                  "example": "insufficient_credits"
+                },
+                "message": {
+                  "type": "string"
+                },
+                "required_credits": {
+                  "type": "integer",
+                  "example": 100
+                },
+                "balance_credits": {
+                  "type": "integer",
+                  "example": 0
+                },
+                "buy_credits_url": {
+                  "type": "string",
+                  "format": "uri",
+                  "example": "https://app.talonic.com/settings/billing?buy=1"
+                },
+                "pricing_url": {
+                  "type": "string",
+                  "example": "/v1/pricing"
+                }
+              }
+            }
+          }
+        }
+      },
       "InternalServerError": {
         "description": "An unexpected error occurred.",
         "content": {

package/package.json

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