@talonic/docs 0.20.33 → 0.21.0

package/dist/seo.js

@@ -6125,6 +6125,42 @@ var openapi_default = {
         }
       }
     },
+    "/v1/reference-data/{id}/csv": {
+      get: {
+        operationId: "downloadReferenceDataCsv",
+        summary: "Download a reference dataset as CSV",
+        description: "Returns the full dataset as a CSV file attachment.",
+        tags: [
+          "Reference Data"
+        ],
+        parameters: [
+          {
+            $ref: "#/components/parameters/ResourceId"
+          }
+        ],
+        responses: {
+          "200": {
+            description: "CSV file (returned as an attachment via Content-Disposition).",
+            content: {
+              "text/csv": {
+                schema: {
+                  type: "string"
+                }
+              }
+            }
+          },
+          "401": {
+            $ref: "#/components/responses/Unauthorized"
+          },
+          "404": {
+            $ref: "#/components/responses/NotFound"
+          },
+          "429": {
+            $ref: "#/components/responses/RateLimitExceeded"
+          }
+        }
+      }
+    },
     "/v1/usage": {
       get: {
         operationId: "getUsage",
@@ -7114,7 +7150,7 @@ var openapi_default = {
       post: {
         operationId: "nshotOverride",
         summary: "Override an N-Shot value",
-        description: "Manually override the N-Shot selected value for a document-field pair.",
+        description: "Override an N-Shot cell for a document-field pair by selecting a specific shot's value.",
         tags: [
           "N-Shot"
         ],
@@ -7140,7 +7176,7 @@ var openapi_default = {
                 required: [
                   "document_id",
                   "field_name",
-                  "value"
+                  "selected_shot"
                 ],
                 properties: {
                   document_id: {
@@ -7152,8 +7188,14 @@ var openapi_default = {
                     type: "string",
                     example: "invoice_number"
                   },
-                  value: {
-                    description: "The override value to apply."
+                  selected_shot: {
+                    type: "integer",
+                    description: "Shot number (index) whose value should become the cell value.",
+                    example: 2
+                  },
+                  reason: {
+                    type: "string",
+                    description: "Optional human-readable reason for the override, stored in the audit trail."
                   }
                 }
               }
@@ -7162,16 +7204,12 @@ var openapi_default = {
         },
         responses: {
           "200": {
-            description: "Override applied.",
+            description: "The full updated comparison object, including the applied `override`.",
             content: {
               "application/json": {
                 schema: {
                   type: "object",
-                  properties: {
-                    success: {
-                      type: "boolean"
-                    }
-                  }
+                  additionalProperties: true
                 }
               }
             }
@@ -7195,7 +7233,7 @@ var openapi_default = {
       post: {
         operationId: "nshotJudgeDecision",
         summary: "Submit a judge decision for N-Shot",
-        description: "Submit an AI or human judge decision on which N-Shot candidate is correct.",
+        description: "Accept or decline the LLM judge's recommendation for an N-Shot cell. Accepting applies the judge's recommended shot as an override.\n",
         tags: [
           "N-Shot"
         ],
@@ -7221,7 +7259,7 @@ var openapi_default = {
                 required: [
                   "document_id",
                   "field_name",
-                  "decision"
+                  "accepted"
                 ],
                 properties: {
                   document_id: {
@@ -7233,9 +7271,9 @@ var openapi_default = {
                     type: "string",
                     example: "invoice_number"
                   },
-                  decision: {
-                    type: "string",
-                    description: "The judge's selected value or verdict."
+                  accepted: {
+                    type: "boolean",
+                    description: "Whether the judge recommendation is accepted (true) or declined (false)."
                   }
                 }
               }
@@ -7244,16 +7282,12 @@ var openapi_default = {
         },
         responses: {
           "200": {
-            description: "Judge decision recorded.",
+            description: "The full updated comparison object, including the recorded `judgement` (and `override` when accepted).",
             content: {
               "application/json": {
                 schema: {
                   type: "object",
-                  properties: {
-                    success: {
-                      type: "boolean"
-                    }
-                  }
+                  additionalProperties: true
                 }
               }
             }
@@ -9428,34 +9462,57 @@ var openapi_default = {
       get: {
         operationId: "getCreditsBalance",
         summary: "Get credit balance",
-        description: "Returns the current credit balance for the authenticated customer.",
+        description: "Returns the enriched credit balance for the authenticated customer:\ncredit balance with EUR conversion, 30-day burn rate, projected runway,\nand API tier info.\n",
         tags: [
           "Credits"
         ],
         responses: {
           "200": {
-            description: "Credit balance.",
+            description: "Enriched credit balance.",
             content: {
               "application/json": {
                 schema: {
                   type: "object",
                   required: [
-                    "balance",
-                    "currency"
+                    "balance_credits",
+                    "balance_eur",
+                    "burn_rate_30d_credits",
+                    "projected_runway_days",
+                    "tier",
+                    "tier_resets_at"
                   ],
                   properties: {
-                    balance: {
+                    balance_credits: {
+                      type: "integer",
+                      description: "Current credit balance.",
+                      example: 4200
+                    },
+                    balance_eur: {
                       type: "number",
-                      format: "float"
+                      format: "float",
+                      description: "Balance converted to EUR at the published credits-per-EUR rate.",
+                      example: 42
                     },
-                    currency: {
+                    burn_rate_30d_credits: {
+                      type: "integer",
+                      description: "Credits consumed over the last 30 days.",
+                      example: 1500
+                    },
+                    projected_runway_days: {
+                      type: "integer",
+                      description: "Projected days until the balance is exhausted at the 30-day burn rate. -1 when there is no recent consumption.",
+                      example: 84
+                    },
+                    tier: {
                       type: "string",
-                      example: "USD"
+                      description: "API tier of the organization.",
+                      example: "free"
                     },
-                    updated_at: {
+                    tier_resets_at: {
                       type: "string",
                       format: "date-time",
-                      example: "2026-04-25T14:30:00.000Z"
+                      description: "Start of the next monthly tier period (1st of next month, UTC).",
+                      example: "2026-05-01T00:00:00.000Z"
                     }
                   }
                 }
@@ -9475,19 +9532,31 @@ var openapi_default = {
       get: {
         operationId: "getCreditsHistory",
         summary: "Get credit history",
-        description: "Returns credit transaction history (purchases, deductions, adjustments).",
+        description: "Returns credit transaction history (purchases, consumption, adjustments, bonuses), most recent first, with page/limit pagination.",
         tags: [
           "Credits"
         ],
         parameters: [
           {
-            $ref: "#/components/parameters/Limit"
-          },
-          {
-            $ref: "#/components/parameters/Cursor"
+            name: "page",
+            in: "query",
+            schema: {
+              type: "integer",
+              minimum: 1,
+              default: 1
+            },
+            description: "Page number (1-based)."
           },
           {
-            $ref: "#/components/parameters/Order"
+            name: "limit",
+            in: "query",
+            schema: {
+              type: "integer",
+              minimum: 1,
+              maximum: 100,
+              default: 20
+            },
+            description: "Items per page (max 100)."
           }
         ],
         responses: {
@@ -9496,48 +9565,79 @@ var openapi_default = {
             content: {
               "application/json": {
                 schema: {
-                  allOf: [
-                    {
-                      $ref: "#/components/schemas/PaginatedResponse"
-                    },
-                    {
-                      type: "object",
-                      properties: {
-                        data: {
-                          type: "array",
-                          items: {
+                  type: "object",
+                  required: [
+                    "items",
+                    "total",
+                    "page",
+                    "limit"
+                  ],
+                  properties: {
+                    items: {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        properties: {
+                          id: {
+                            type: "string",
+                            format: "uuid",
+                            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+                          },
+                          customer_id: {
+                            type: "string",
+                            format: "uuid"
+                          },
+                          user_id: {
+                            type: [
+                              "string",
+                              "null"
+                            ],
+                            format: "uuid"
+                          },
+                          amount: {
+                            type: "integer",
+                            description: "Credit amount. Positive = credit, negative = debit."
+                          },
+                          type: {
+                            type: "string",
+                            description: "Transaction type: purchase, consumption, adjustment, bonus."
+                          },
+                          description: {
+                            type: [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          operation_type: {
+                            type: [
+                              "string",
+                              "null"
+                            ],
+                            description: "Pipeline stage that consumed credits, if applicable."
+                          },
+                          metadata: {
                             type: "object",
-                            properties: {
-                              id: {
-                                type: "string",
-                                format: "uuid",
-                                example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
-                              },
-                              type: {
-                                type: "string",
-                                description: "Transaction type: purchase, deduction, adjustment, refund."
-                              },
-                              amount: {
-                                type: "number",
-                                format: "float"
-                              },
-                              description: {
-                                type: [
-                                  "string",
-                                  "null"
-                                ]
-                              },
-                              created_at: {
-                                type: "string",
-                                format: "date-time",
-                                example: "2026-04-25T14:30:00.000Z"
-                              }
-                            }
+                            additionalProperties: true
+                          },
+                          created_at: {
+                            type: "string",
+                            format: "date-time",
+                            example: "2026-04-25T14:30:00.000Z"
                           }
                         }
                       }
+                    },
+                    total: {
+                      type: "integer",
+                      description: "Total number of transactions."
+                    },
+                    page: {
+                      type: "integer"
+                    },
+                    limit: {
+                      type: "integer"
                     }
-                  ]
+                  }
                 }
               }
             }
@@ -9554,60 +9654,73 @@ var openapi_default = {
     "/v1/credits/usage": {
       get: {
         operationId: "getCreditsUsage",
-        summary: "Get credit usage summary",
-        description: "Returns aggregate credit usage broken down by feature.",
+        summary: "Get usage statistics",
+        description: "Returns aggregated API usage stats grouped by operation type and model over the given period.",
         tags: [
           "Credits"
         ],
         parameters: [
           {
-            name: "from",
-            in: "query",
-            schema: {
-              type: "string",
-              format: "date-time"
-            },
-            description: "Start of the period (ISO 8601)."
-          },
-          {
-            name: "to",
+            name: "days",
             in: "query",
             schema: {
-              type: "string",
-              format: "date-time"
+              type: "integer",
+              default: 30
             },
-            description: "End of the period (ISO 8601)."
+            description: "Reporting window in days."
           }
         ],
         responses: {
           "200": {
-            description: "Credit usage summary.",
+            description: "Aggregated usage stats.",
             content: {
               "application/json": {
                 schema: {
                   type: "object",
+                  required: [
+                    "stats",
+                    "period_days"
+                  ],
                   properties: {
-                    total_used: {
-                      type: "number",
-                      format: "float"
-                    },
-                    breakdown: {
+                    stats: {
                       type: "array",
                       items: {
                         type: "object",
                         properties: {
-                          feature: {
+                          operation_type: {
                             type: "string"
                           },
-                          credits_used: {
-                            type: "number",
-                            format: "float"
+                          model: {
+                            type: "string"
                           },
                           call_count: {
                             type: "integer"
+                          },
+                          total_input_tokens: {
+                            type: "string",
+                            description: "Summed input tokens (serialized as a string)."
+                          },
+                          total_output_tokens: {
+                            type: "string",
+                            description: "Summed output tokens (serialized as a string)."
+                          },
+                          total_cache_read_tokens: {
+                            type: "string",
+                            description: "Summed cache-read tokens (serialized as a string)."
+                          },
+                          total_cost_usd: {
+                            type: [
+                              "string",
+                              "null"
+                            ],
+                            description: "Estimated total cost in USD (serialized as a string)."
                           }
                         }
                       }
+                    },
+                    period_days: {
+                      type: "integer",
+                      example: 30
                     }
                   }
                 }
@@ -9626,56 +9739,53 @@ var openapi_default = {
     "/v1/credits/usage/daily": {
       get: {
         operationId: "getCreditsUsageDaily",
-        summary: "Get daily credit usage",
-        description: "Returns per-day credit usage for the specified period (default last 30 days).",
+        summary: "Get daily usage breakdown",
+        description: "Returns per-day API usage for the specified period (default last 30 days) as a JSON array.",
         tags: [
           "Credits"
         ],
         parameters: [
           {
-            name: "from",
-            in: "query",
-            schema: {
-              type: "string",
-              format: "date-time"
-            },
-            description: "Start of the period (ISO 8601)."
-          },
-          {
-            name: "to",
+            name: "days",
             in: "query",
             schema: {
-              type: "string",
-              format: "date-time"
+              type: "integer",
+              default: 30
             },
-            description: "End of the period (ISO 8601)."
+            description: "Reporting window in days."
           }
         ],
         responses: {
           "200": {
-            description: "Daily credit usage.",
+            description: "Daily usage breakdown.",
             content: {
               "application/json": {
                 schema: {
-                  type: "object",
-                  properties: {
-                    data: {
-                      type: "array",
-                      items: {
-                        type: "object",
-                        properties: {
-                          date: {
-                            type: "string",
-                            format: "date"
-                          },
-                          credits_used: {
-                            type: "number",
-                            format: "float"
-                          },
-                          call_count: {
-                            type: "integer"
-                          }
-                        }
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      date: {
+                        type: "string",
+                        format: "date"
+                      },
+                      calls: {
+                        type: "integer"
+                      },
+                      input_tokens: {
+                        type: "string",
+                        description: "Summed input tokens for the day (serialized as a string)."
+                      },
+                      output_tokens: {
+                        type: "string",
+                        description: "Summed output tokens for the day (serialized as a string)."
+                      },
+                      cost_usd: {
+                        type: [
+                          "string",
+                          "null"
+                        ],
+                        description: "Estimated cost in USD for the day (serialized as a string)."
                       }
                     }
                   }
@@ -9696,19 +9806,31 @@ var openapi_default = {
       get: {
         operationId: "getCreditsUsageLog",
         summary: "Get credit usage log",
-        description: "Returns a detailed per-request usage log with model, tokens, and cost.",
+        description: "Returns a detailed per-request usage log with model, tokens, and cost, most recent first, with page/limit pagination.",
         tags: [
           "Credits"
         ],
         parameters: [
           {
-            $ref: "#/components/parameters/Limit"
-          },
-          {
-            $ref: "#/components/parameters/Cursor"
+            name: "page",
+            in: "query",
+            schema: {
+              type: "integer",
+              minimum: 1,
+              default: 1
+            },
+            description: "Page number (1-based)."
           },
           {
-            $ref: "#/components/parameters/Order"
+            name: "limit",
+            in: "query",
+            schema: {
+              type: "integer",
+              minimum: 1,
+              maximum: 100,
+              default: 20
+            },
+            description: "Items per page (max 100)."
           }
         ],
         responses: {
@@ -9717,48 +9839,75 @@ var openapi_default = {
             content: {
               "application/json": {
                 schema: {
-                  allOf: [
-                    {
-                      $ref: "#/components/schemas/PaginatedResponse"
-                    },
-                    {
-                      type: "object",
-                      properties: {
-                        data: {
-                          type: "array",
-                          items: {
-                            type: "object",
-                            properties: {
-                              id: {
-                                type: "string"
-                              },
-                              operation_type: {
-                                type: "string"
-                              },
-                              model: {
-                                type: "string"
-                              },
-                              input_tokens: {
-                                type: "integer"
-                              },
-                              output_tokens: {
-                                type: "integer"
-                              },
-                              cost_credits: {
-                                type: "number",
-                                format: "float"
-                              },
-                              created_at: {
-                                type: "string",
-                                format: "date-time",
-                                example: "2026-04-25T14:30:00.000Z"
-                              }
-                            }
+                  type: "object",
+                  required: [
+                    "items",
+                    "total",
+                    "page",
+                    "limit"
+                  ],
+                  properties: {
+                    items: {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        properties: {
+                          id: {
+                            type: "string",
+                            format: "uuid"
+                          },
+                          customer_id: {
+                            type: "string",
+                            format: "uuid"
+                          },
+                          model: {
+                            type: "string"
+                          },
+                          input_tokens: {
+                            type: "integer"
+                          },
+                          output_tokens: {
+                            type: "integer"
+                          },
+                          cache_read_tokens: {
+                            type: "integer"
+                          },
+                          cost_estimate_usd: {
+                            type: [
+                              "string",
+                              "null"
+                            ],
+                            description: "Estimated cost in USD (serialized as a string)."
+                          },
+                          operation_type: {
+                            type: "string"
+                          },
+                          document_id: {
+                            type: [
+                              "string",
+                              "null"
+                            ],
+                            format: "uuid"
+                          },
+                          created_at: {
+                            type: "string",
+                            format: "date-time",
+                            example: "2026-04-25T14:30:00.000Z"
                           }
                         }
                       }
+                    },
+                    total: {
+                      type: "integer",
+                      description: "Total number of log entries."
+                    },
+                    page: {
+                      type: "integer"
+                    },
+                    limit: {
+                      type: "integer"
                     }
-                  ]
+                  }
                 }
               }
             }
@@ -11465,7 +11614,7 @@ var openapi_default = {
       get: {
         operationId: "getReviewStats",
         summary: "Get review queue statistics",
-        description: "Returns aggregate statistics about the review queue (pending, approved, rejected counts).",
+        description: "Returns aggregate review queue counts grouped by status.",
         tags: [
           "Review"
         ],
@@ -11476,18 +11625,27 @@ var openapi_default = {
               "application/json": {
                 schema: {
                   type: "object",
+                  required: [
+                    "total",
+                    "by_status"
+                  ],
                   properties: {
-                    pending: {
-                      type: "integer"
-                    },
-                    approved: {
-                      type: "integer"
-                    },
-                    rejected: {
-                      type: "integer"
-                    },
                     total: {
-                      type: "integer"
+                      type: "integer",
+                      description: "Total number of review records.",
+                      example: 42
+                    },
+                    by_status: {
+                      type: "object",
+                      description: "Count of review records per status (e.g. pending, approved, rejected).",
+                      additionalProperties: {
+                        type: "integer"
+                      },
+                      example: {
+                        pending: 12,
+                        approved: 25,
+                        rejected: 5
+                      }
                     }
                   }
                 }
@@ -12809,12 +12967,12 @@ var openapi_default = {
             description: "Filter by value layer"
           },
           {
-            name: "source_type",
+            name: "kind",
             in: "query",
             schema: {
               type: "string"
             },
-            description: "Filter by source type (e.g. extraction, job, resolution)"
+            description: "Filter by source kind (e.g. structuring_run, resolution_run, data_product)"
           },
           {
             $ref: "#/components/parameters/Limit"
@@ -12931,14 +13089,34 @@ var openapi_default = {
                           field_key: {
                             type: "string"
                           },
-                          field_type: {
+                          display_name: {
+                            type: "string"
+                          },
+                          data_type: {
                             type: "string"
                           },
-                          ordinal: {
+                          position: {
                             type: "integer"
+                          },
+                          is_required: {
+                            type: "boolean"
+                          },
+                          is_hidden: {
+                            type: "boolean"
                           }
                         }
                       }
+                    },
+                    links: {
+                      type: "object",
+                      properties: {
+                        self: {
+                          type: "string"
+                        },
+                        record_set: {
+                          type: "string"
+                        }
+                      }
                     }
                   }
                 }
@@ -12976,6 +13154,7 @@ var openapi_default = {
             in: "query",
             schema: {
               type: "integer",
+              minimum: 1,
               default: 1
             }
           },
@@ -12984,9 +13163,21 @@ var openapi_default = {
             in: "query",
             schema: {
               type: "integer",
-              default: 50,
-              maximum: 200
+              minimum: 1,
+              maximum: 100,
+              default: 20
             }
+          },
+          {
+            name: "include",
+            in: "query",
+            schema: {
+              type: "string",
+              enum: [
+                "values"
+              ]
+            },
+            description: "Pass `include=values` to attach each record's latest-version cell values keyed by field key. A cell held for review (`pending_approval`) reports its status with a null value.\n"
           }
         ],
         responses: {
@@ -13001,7 +13192,58 @@ var openapi_default = {
                       type: "array",
                       items: {
                         type: "object",
-                        description: "Record with source_record_id and ordinal"
+                        properties: {
+                          id: {
+                            type: "string",
+                            format: "uuid"
+                          },
+                          document_id: {
+                            type: [
+                              "string",
+                              "null"
+                            ],
+                            format: "uuid"
+                          },
+                          ordinal: {
+                            type: "integer"
+                          },
+                          record_key: {
+                            type: [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          status: {
+                            type: "string"
+                          },
+                          confidence: {
+                            type: [
+                              "number",
+                              "null"
+                            ]
+                          },
+                          values: {
+                            type: "object",
+                            description: "Only present with `include=values`. Map of field key to the record's latest cell value.\n",
+                            additionalProperties: {
+                              type: "object",
+                              properties: {
+                                value: {
+                                  description: "Cell value. Null when the cell is held for review."
+                                },
+                                status: {
+                                  type: "string"
+                                },
+                                confidence: {
+                                  type: [
+                                    "number",
+                                    "null"
+                                  ]
+                                }
+                              }
+                            }
+                          }
+                        }
                       }
                     },
                     pagination: {
@@ -13020,6 +13262,17 @@ var openapi_default = {
                           type: "boolean"
                         }
                       }
+                    },
+                    links: {
+                      type: "object",
+                      properties: {
+                        self: {
+                          type: "string"
+                        },
+                        record_set: {
+                          type: "string"
+                        }
+                      }
                     }
                   }
                 }
@@ -13061,14 +13314,52 @@ var openapi_default = {
                 schema: {
                   type: "object",
                   properties: {
-                    data: {
-                      type: "array",
-                      items: {
-                        type: "object"
-                      }
+                    record_set_id: {
+                      type: "string",
+                      format: "uuid"
+                    },
+                    name: {
+                      type: "string"
                     },
                     total: {
                       type: "integer"
+                    },
+                    records: {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        properties: {
+                          id: {
+                            type: "string",
+                            format: "uuid"
+                          },
+                          document_id: {
+                            type: [
+                              "string",
+                              "null"
+                            ],
+                            format: "uuid"
+                          },
+                          ordinal: {
+                            type: "integer"
+                          },
+                          record_key: {
+                            type: [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          status: {
+                            type: "string"
+                          },
+                          confidence: {
+                            type: [
+                              "number",
+                              "null"
+                            ]
+                          }
+                        }
+                      }
                     }
                   }
                 }
@@ -24255,15 +24546,21 @@ var openapi_default = {
               "product"
             ]
           },
-          source_type: {
-            type: "string"
+          kind: {
+            type: "string",
+            description: "Source kind (e.g. structuring_run, resolution_run, data_product)."
           },
           source_id: {
-            type: "string",
-            format: "uuid"
+            type: [
+              "string",
+              "null"
+            ],
+            format: "uuid",
+            description: "Owning run/product ID where applicable."
           },
           status: {
-            type: "string"
+            type: "string",
+            description: "Lifecycle state (e.g. active)."
           },
           record_count: {
             type: "integer"
@@ -24274,6 +24571,23 @@ var openapi_default = {
           created_at: {
             type: "string",
             format: "date-time"
+          },
+          links: {
+            type: "object",
+            properties: {
+              self: {
+                type: "string"
+              },
+              fields: {
+                type: "string"
+              },
+              records: {
+                type: "string"
+              },
+              export: {
+                type: "string"
+              }
+            }
           }
         }
       }