{ "openapi": "3.1.0", "info": { "title": "TRIVDA API", "version": "1.0.0", "description": "Search licensed data and get passages with their licence and provenance; publish your own data and earn when other organisations search it.\n\nAuthenticate with an API key (`Authorization: Bearer sk_live_...`). A sandbox key (`sk_test_...`) gets synthetic fixtures from the same routes, marked with `\"sandbox\": true` and an `X-Sandbox: true` header, and is never charged. Searches are charged per 1,000 billable tokens in the passages returned; see `GET /api/v1/pricing` and the `X-Query-Cost`, `X-Tokens-Used` and `X-Credits-Remaining` response headers. The developer docs are at `/docs/` on the same host." }, "servers": [ { "url": "https://{host}", "description": "Your TRIVDA host. The REST API is served under /api/v1.", "variables": { "host": { "default": "your-trivda-host", "description": "The host name of your TRIVDA deployment." } } } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Search" }, { "name": "API keys" }, { "name": "Usage and wallet" }, { "name": "Billing" }, { "name": "Datasets" }, { "name": "Collections" }, { "name": "Trust" } ], "paths": { "/api/v1/api-keys": { "post": { "summary": "Create an API key", "description": "Create an API key for your organisation. The secret (`sk_live_...`) is in this\nresponse only; store it safely.\n\nScopes narrow what the key may do: collection names and/or `use_case:`. An empty\nlist means everything your organisation may do. With `sandbox: true` the key is a\nsandbox key (`sk_test_...`) that only ever gets synthetic fixtures and is never\ncharged.", "operationId": "create_api_key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "API keys" ] }, "get": { "summary": "List API keys", "description": "List your organisation's API keys. Secrets are never returned, only their display\nprefix.", "operationId": "list_api_keys", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "API keys" ] } }, "/api/v1/api-keys/current": { "get": { "summary": "Show the key this request uses", "description": "The credential this request was made with: its organisation, and for an API key\nits id, display prefix, name and scopes. Use it to check which key a script runs\nwith.", "operationId": "get_current_api_key", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCurrentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "API keys" ] } }, "/api/v1/api-keys/{key_id}": { "delete": { "summary": "Revoke an API key", "description": "Revoke an API key. It stops working at once.", "operationId": "revoke_api_key", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "API keys" ] } }, "/api/v1/billing/profile": { "get": { "summary": "Get your billing details", "description": "Your organisation's billing details, and the required fields that are still\nmissing.", "operationId": "get_billing_profile", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Billing Profile" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Billing" ] }, "put": { "summary": "Set your billing details", "description": "Set your organisation's billing details. An EU VAT number is checked against VIES.", "operationId": "put_billing_profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingProfileRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Put Billing Profile" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Billing" ] } }, "/api/v1/billing/transactions": { "get": { "summary": "List your transactions", "description": "Your organisation's transactions, newest first: top-ups (with the Stripe invoice\nid and the VAT paid), searches, earnings, refunds, adjustments, promotional credit\nand payouts. Pass `next_before` back as `before` for the next page.", "operationId": "list_transactions", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Before" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Transactions" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Billing" ] } }, "/api/v1/collection-rules": { "get": { "summary": "List your routing rules", "description": "Your organisation's routing rules, in the order they are tried.", "operationId": "list_collection_rules", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionRuleListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] }, "post": { "summary": "Create a routing rule", "description": "Route new uploads: a file whose document key matches `path_glob` (and whose type\nis in `mime`, if given) goes to `target_collection_id` instead of where its upload\nnamed, and takes that collection's terms. Rules are tried lowest `priority` first;\nthe first that matches wins. Files already uploaded do not move.", "operationId": "create_collection_rule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionRuleRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionRuleResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] } }, "/api/v1/collection-rules/{rule_id}": { "delete": { "summary": "Delete a routing rule", "description": "Delete a routing rule. Files it already routed stay where they are.", "operationId": "delete_collection_rule", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Rule Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionRuleDeleteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] } }, "/api/v1/collections": { "post": { "summary": "Create a collection", "description": "Make a new, empty collection with its terms. Upload into it with\n`POST /api/v1/datasets/upload` and `collection_id`. It stays private until you\npublish it (`POST /api/v1/datasets/{collection_id}/offer`).", "operationId": "create_collection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] }, "get": { "summary": "List your collections", "description": "Your organisation's collections, `limit` at a time (at most 200). When there are\nmore, pass `next_cursor` back as `cursor`.", "operationId": "list_data_collections", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] } }, "/api/v1/collections/{collection_id}": { "get": { "summary": "Get one collection", "description": "One of your collections: its title, slug, size and terms.", "operationId": "get_collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] }, "patch": { "summary": "Rename a collection", "description": "Rename a collection: its `title`, or its `slug` (409 if you already use it).\nIts id never changes.", "operationId": "update_collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] } }, "/api/v1/collections/{collection_id}/documents": { "get": { "summary": "List a collection's documents", "description": "A collection's documents in key order, `limit` at a time (at most 500). `folder`\n(a path such as `/Avtal/2024`) lists only the documents directly in it.", "operationId": "list_collection_documents", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } }, { "name": "folder", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folder" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionDocumentListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] } }, "/api/v1/collections/{collection_id}/documents/{doc_id}": { "get": { "summary": "Get one document and its versions", "description": "One document: its state, every version it has had, and other places the same\nbytes were uploaded to.", "operationId": "get_collection_document", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } }, { "name": "doc_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Doc Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionDocumentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] }, "delete": { "summary": "Remove one document", "description": "Remove one document from a collection: every version's passages, its stored\noriginal and anything cached that quotes it. The collection, its terms and its\nother documents stay. An automatic sync does not bring the document back; uploading\nit again yourself does.", "operationId": "delete_collection_document", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } }, { "name": "doc_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Doc Id" } }, { "name": "reason", "in": "query", "required": false, "schema": { "type": "string", "default": "owner_removed", "title": "Reason" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDeleteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] } }, "/api/v1/collections/{collection_id}/folders": { "get": { "summary": "List a collection's folders", "description": "A collection's folders in path order (at most 1,000 a page). `parent` (a path,\n`/` for the top) lists only its direct sub-folders.", "operationId": "list_collection_folders", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } }, { "name": "parent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 200, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionFolderListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Collections" ] } }, "/api/v1/compliance/gpai-summary": { "get": { "summary": "Get an EU AI Act training-content summary", "description": "An EU AI Act article 53 summary of the datasets you can see: sources, licence\nbasis, jurisdiction and opt-out posture.", "operationId": "gpai_summary", "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Provider" } }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Model" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpaiSummaryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/datasets": { "get": { "summary": "List datasets", "description": "The datasets you can see, your own and those offered on the marketplace, in\n`dataset_id` order, `limit` at a time (at most 1,000). When there are more,\n`next_cursor` is set: pass it back as `cursor` for the next page.", "operationId": "list_datasets", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 500, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/datasets/upload": { "post": { "summary": "Upload a file into a dataset", "description": "Upload a file, or a .zip of files, into one of your collections. The file is stored\nand queued, and the answer is `202 Accepted` with an `item_id`: follow it at\n`GET /api/v1/ingest/items/{item_id}` until it is `done` (with how many passages were\nindexed and how many were held back) or `failed` (with the reason).\n\nWhere it goes: `collection_id` (from `POST /api/v1/collections`) puts it in that\ncollection, whose terms stay as they are. Otherwise `dataset_id` is your own name for\na collection: the first upload under a name creates it (with a new `col_` id, and the\nform's licence fields as its terms), later uploads under the same name add to it.\nWithout either, the file's name is used. A routing rule (`POST /api/v1/collection-rules`)\nmay send it on to another collection. `doc_key` names the document inside the\ncollection, usually its path in its folder (`Avtal/2024/lease.pdf`; default: the file\nname): uploading new bytes under the same `doc_key` replaces the document's previous\nversion. Bytes your organisation already holds anywhere are not processed again\n(`duplicate: true`, the answer of the upload that holds them). An upload stays\nprivate unless `offered` is true.", "operationId": "upload_dataset", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_dataset" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetUploadResponse" } } } }, "202": { "description": "Accepted: the file is queued for ingest. Follow it at `GET /api/v1/ingest/items/{item_id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/datasets/usage": { "get": { "summary": "Get usage and earnings per dataset", "description": "Usage and earnings for the datasets your organisation owns.", "operationId": "dataset_usage", "parameters": [ { "name": "from_", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From " } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetUsageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/datasets/{dataset_id}/earnings": { "get": { "summary": "Get one dataset's earnings", "description": "What one of your datasets has earned, per day and per buyer segment.", "operationId": "dataset_earnings", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 90, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetEarningsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/datasets/{dataset_id}/erase": { "post": { "summary": "Delete a dataset", "description": "Delete one of your datasets: its indexed passages, stored originals and cached\nresults. `reason=owner_removed` lets you upload the same data again;\n`reason=erasure_request` (the default) blocks it from being ingested again.", "operationId": "erase_dataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "tenant", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } }, { "name": "reason", "in": "query", "required": false, "schema": { "type": "string", "default": "erasure_request", "title": "Reason" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EraseResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/datasets/{dataset_id}/offer": { "post": { "summary": "Publish a dataset to the marketplace", "description": "Publish one of your datasets to the marketplace. Every paying organisation can then\nsearch it, and you earn on each paid search by another organisation that returns\nit.", "operationId": "offer_dataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetRecordResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/datasets/{dataset_id}/withdraw": { "post": { "summary": "Take a dataset off the marketplace", "description": "Take one of your datasets off the marketplace. It stays indexed and searchable by\nyour own organisation.", "operationId": "withdraw_dataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetRecordResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/disclosure/display": { "get": { "summary": "Get how buyers see you", "description": "How buyers see your organisation: your default choice and each of your\ndatasets' choice, with the name or organisation type buyers are shown.", "operationId": "get_display", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Display" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] }, "put": { "summary": "Set how buyers see you", "description": "Choose how buyers see you: `named` or `org_type` (a verified organisation type,\nwith an optional label of your own), for one dataset or, without `dataset_id`, as\nyour default. Attribution a licence requires is shown to buyers either way.", "operationId": "put_display", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisplayRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Put Display" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/ingest/items/{item_id}": { "get": { "summary": "Get the state of a queued file", "description": "One queued file: `queued`, `running`, `done` (with the passages indexed and held\nback), `failed` (with the reason) or `cancelled`. Poll every few seconds.", "operationId": "get_ingest_item", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestItemResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/ledger-roots": { "get": { "summary": "List the published monthly ledger roots", "description": "Every published monthly ledger root. Each line of a partner statement carries\nan inclusion proof that folds up to its month's root here, so a partner can check\nits statement was part of the ledger without seeing anyone else's lines.", "operationId": "list_ledger_roots", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Ledger Roots" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Billing" ] } }, "/api/v1/pricing": { "get": { "summary": "Get the price list", "description": "The current price list. No authentication needed.\n\nSearches are priced per 1,000 billable tokens in the passages returned;\nthe wallet holds credits (`credits_per_eur` credits = EUR 1).", "operationId": "get_pricing", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingResponse" } } } } }, "tags": [ "Search" ], "security": [] } }, "/api/v1/search/collections": { "get": { "summary": "List the indexes you can search", "description": "The search indexes your key can query, with their passage counts.", "operationId": "list_collections", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Search" ] } }, "/api/v1/search/listings": { "get": { "summary": "List the listings a scope covers", "description": "The listings a scope covers, so you can choose one before you search\n(`scope=listing:`). Free.", "operationId": "list_search_listings", "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Q" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Search" ] } }, "/api/v1/search/query": { "post": { "summary": "Search licensed data", "description": "Search licensed data and get ranked passages, each with its licence\nand provenance.\n\nCharged per 1,000 billable tokens in the passages returned. A search with\nno results costs nothing. The cost is in the `billing` object and in the\n`X-Query-Cost`, `X-Tokens-Used` and `X-Credits-Remaining` headers.", "operationId": "search", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional, up to 255 characters. A retry with the same key and body within 24 hours returns the first response and is not charged again.", "title": "Idempotency-Key" }, "description": "Optional, up to 255 characters. A retry with the same key and body within 24 hours returns the first response and is not charged again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchQueryRequest" } } } }, "responses": { "200": { "description": "Ranked passages, with what the search cost.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchQueryResponse" } } }, "headers": { "X-Query-Cost": { "description": "EUR charged for this call, 6 decimals. 0 for a free search, a search with no results, or an Idempotency-Key replay.", "schema": { "type": "string" } }, "X-Tokens-Used": { "description": "Billable tokens in the returned passages. 0 on a replay.", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Wallet credits left after this call (1,000 credits = EUR 1 by default; see GET /api/v1/pricing).", "schema": { "type": "integer" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored response to an earlier request with the same Idempotency-Key. Absent otherwise.", "schema": { "type": "string" } } } }, "400": { "description": "The Idempotency-Key is longer than 255 characters." }, "401": { "description": "Missing, invalid or revoked credential." }, "402": { "description": "The wallet cannot cover the estimated cost and no free searches are left. Top up and retry." }, "403": { "description": "The key is not scoped for this index or use case, or the organisation is suspended." }, "409": { "description": "A request with this Idempotency-Key is still running." }, "422": { "description": "Invalid body, or an Idempotency-Key reused with a different body." }, "429": { "description": "Rate limit exceeded. Retry after the `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } } }, "tags": [ "Search" ] } }, "/api/v1/search/quota": { "get": { "summary": "Get your rate limits and quota", "description": "Your rate limits and what is left of them now (per minute, per day, per month),\nplus free searches and wallet credits.", "operationId": "search_quota", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Search" ] } }, "/api/v1/search/results/{query_id}": { "get": { "summary": "Fetch an earlier search's results again", "description": "Fetch the results of an earlier search again, free, for 7 days.", "operationId": "get_search_results", "parameters": [ { "name": "query_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Query Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchQueryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Search" ] } }, "/api/v1/search/scope": { "get": { "summary": "Get your default search scope", "description": "Where your searches look when they name no `scope`, and why.", "operationId": "get_search_scope", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchScopeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Search" ] }, "put": { "summary": "Set what your organisation uses TRIVDA for", "description": "Say what your organisation uses TRIVDA for. `knowledge_bank` makes searches\nthat name no `scope` search only your own data; a key minted with a\n`default_scope:` scope keeps its own default.", "operationId": "put_search_scope", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchScopeUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchScopeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Search" ] } }, "/api/v1/statements": { "get": { "summary": "List your partner statements", "description": "Your monthly partner statements, your earnings balance and the payout terms (hold\nperiod and minimum).", "operationId": "list_my_statements", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List My Statements" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Billing" ] } }, "/api/v1/statements/{statement_id}": { "get": { "summary": "Get one partner statement", "description": "One monthly partner statement, with a line per dataset.", "operationId": "get_my_statement", "parameters": [ { "name": "statement_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Statement Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get My Statement" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Billing" ] } }, "/api/v1/statements/{statement_id}/csv": { "get": { "summary": "Download one partner statement as CSV", "description": "One monthly partner statement as CSV.", "operationId": "get_my_statement_csv", "parameters": [ { "name": "statement_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Statement Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Billing" ] } }, "/api/v1/uploads/{upload_id}": { "get": { "summary": "Get the state of an upload", "description": "The state of an upload you started with an `upload_id`: `queued`, `running`,\n`done`, `failed`, `cancel_requested`, `cancelled` or `unknown`.", "operationId": "upload_status", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadStatusResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/uploads/{upload_id}/cancel": { "post": { "summary": "Cancel an upload", "description": "Cancel an upload you started with an `upload_id`, at any stage. Anything it already\nindexed is removed.", "operationId": "cancel_upload", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadCancelResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Datasets" ] } }, "/api/v1/usage/ledger": { "get": { "summary": "Get money spent and earned per day", "description": "Money spent and earned per day, from your organisation's wallet ledger.", "operationId": "usage_ledger", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerSummaryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Usage and wallet" ] } }, "/api/v1/usage/queries": { "get": { "summary": "List recent searches", "description": "Your recent searches, newest first, with hits, tokens and cost.", "operationId": "usage_queries", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageQueriesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Usage and wallet" ] } }, "/api/v1/usage/summary": { "get": { "summary": "Get spend and usage for a period", "description": "Spend and usage for a period, in total, per dataset and per day, with a projection\nto the end of the month.", "operationId": "usage_summary", "parameters": [ { "name": "from_", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From " } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummaryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Usage and wallet" ] } }, "/api/v1/usage/wallet": { "get": { "summary": "Get your wallet balance", "description": "Your wallet: spendable credits, earnings and free searches left.", "operationId": "usage_wallet", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Usage and wallet" ] } }, "/api/v1/vocabularies": { "get": { "summary": "List the vocabularies and their licences", "description": "The vocabularies and ontologies TRIVDA loads, links against or has excluded, with\ntheir version, licence, what may be redistributed and the attribution results show\nwith their concept ids. No authentication needed.", "operationId": "list_vocabularies", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VocabulariesResponse" } } } } }, "tags": [ "Trust" ], "security": [] } }, "/api/v1/wallet/convert-earnings": { "post": { "summary": "Convert earnings into credits", "description": "Move earnings into spendable credits. Converted earnings can no longer be paid out.", "operationId": "convert_earnings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertEarningsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "tags": [ "Usage and wallet" ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key (`sk_live_...`, or `sk_test_...` for the sandbox) from the dashboard's API keys page, or a short-lived access token." } }, "schemas": { "ApiKeyCreateRequest": { "properties": { "name": { "type": "string", "title": "Name", "default": "api key" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "sandbox": { "type": "boolean", "title": "Sandbox", "description": "Create a sandbox key (`sk_test_...`) instead of a live one. A sandbox key gets synthetic fixtures, never real data, and is never charged.", "default": false } }, "type": "object", "title": "ApiKeyCreateRequest" }, "ApiKeyCreatedResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "prefix": { "type": "string", "title": "Prefix" }, "name": { "type": "string", "title": "Name" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "sandbox": { "type": "boolean", "title": "Sandbox", "default": false }, "api_key": { "type": "string", "title": "Api Key" } }, "type": "object", "required": [ "id", "prefix", "name", "api_key" ], "title": "ApiKeyCreatedResponse" }, "ApiKeyCurrentResponse": { "properties": { "org_id": { "type": "string", "title": "Org Id" }, "auth_kind": { "type": "string", "title": "Auth Kind", "description": "`api_key`, or `oauth` for an access token." }, "sandbox": { "type": "boolean", "title": "Sandbox", "description": "True for a sandbox key: every response is a synthetic fixture.", "default": false }, "key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Id" }, "prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prefix" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" } }, "type": "object", "required": [ "org_id", "auth_kind" ], "title": "ApiKeyCurrentResponse", "description": "GET /api-keys/current: the credential this request was made with." }, "ApiKeyInfo": { "properties": { "id": { "type": "string", "title": "Id" }, "prefix": { "type": "string", "title": "Prefix" }, "name": { "type": "string", "title": "Name" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "sandbox": { "type": "boolean", "title": "Sandbox", "default": false }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Used At" }, "revoked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revoked At" } }, "type": "object", "required": [ "id", "prefix", "name" ], "title": "ApiKeyInfo" }, "ApiKeyListResponse": { "properties": { "keys": { "items": { "$ref": "#/components/schemas/ApiKeyInfo" }, "type": "array", "title": "Keys" } }, "type": "object", "title": "ApiKeyListResponse" }, "BillingProfileRequest": { "properties": { "company_name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Company Name" }, "org_number": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Org Number" }, "address_line1": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Address Line1" }, "address_line2": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Address Line2" }, "postal_code": { "type": "string", "maxLength": 32, "minLength": 1, "title": "Postal Code" }, "city": { "type": "string", "maxLength": 128, "minLength": 1, "title": "City" }, "country": { "type": "string", "maxLength": 2, "minLength": 2, "title": "Country" }, "vat_id": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ], "title": "Vat Id" }, "invoice_email": { "type": "string", "maxLength": 255, "minLength": 3, "title": "Invoice Email" }, "nace_section": { "anyOf": [ { "type": "string", "maxLength": 1 }, { "type": "null" } ], "title": "Nace Section" }, "buyer_segment": { "anyOf": [ { "type": "string", "maxLength": 16 }, { "type": "null" } ], "title": "Buyer Segment" }, "size_band": { "anyOf": [ { "type": "string", "maxLength": 16 }, { "type": "null" } ], "title": "Size Band" } }, "type": "object", "required": [ "company_name", "address_line1", "postal_code", "city", "country", "invoice_email" ], "title": "BillingProfileRequest" }, "Body_upload_dataset": { "properties": { "file": { "anyOf": [ { "type": "string", "contentMediaType": "application/octet-stream" }, { "type": "null" } ], "title": "File" }, "source_uri": { "type": "string", "title": "Source Uri", "default": "" }, "content_sha256": { "type": "string", "title": "Content Sha256", "default": "" }, "file_name": { "type": "string", "title": "File Name", "default": "" }, "dataset_id": { "type": "string", "title": "Dataset Id", "default": "" }, "data_owner": { "type": "string", "title": "Data Owner", "default": "" }, "license": { "type": "string", "title": "License", "default": "CC-BY-4.0" }, "license_basis": { "type": "string", "title": "License Basis", "default": "owner-license" }, "granted_uses": { "type": "string", "title": "Granted Uses", "default": "search,rag" }, "labels": { "type": "string", "title": "Labels", "default": "" }, "jurisdiction": { "type": "string", "title": "Jurisdiction", "default": "global" }, "offered": { "type": "boolean", "title": "Offered", "default": false }, "upload_id": { "type": "string", "title": "Upload Id", "default": "" }, "trigger": { "type": "string", "title": "Trigger", "default": "user" }, "acl": { "type": "string", "title": "Acl", "default": "" }, "lane": { "type": "string", "title": "Lane", "default": "" }, "batch_id": { "type": "string", "title": "Batch Id", "default": "" }, "collection_id": { "type": "string", "title": "Collection Id", "default": "" }, "doc_key": { "type": "string", "title": "Doc Key", "default": "" }, "collection_title": { "type": "string", "title": "Collection Title", "default": "" } }, "type": "object", "title": "Body_upload_dataset" }, "CollectionCreateRequest": { "properties": { "title": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Title" }, "slug": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Slug", "description": "Your own handle for it, unique in your organisation (lowercase letters, digits, `-` and `_`). Uploads that name it as `dataset_id` go here. Default: from the title." }, "data_owner": { "type": "string", "maxLength": 255, "title": "Data Owner", "default": "" }, "license_basis": { "type": "string", "maxLength": 64, "title": "License Basis", "default": "owner-license" }, "granted_uses": { "items": { "type": "string" }, "type": "array", "title": "Granted Uses" }, "jurisdiction": { "type": "string", "maxLength": 32, "title": "Jurisdiction", "default": "global" }, "labels": { "items": { "type": "string" }, "type": "array", "title": "Labels" } }, "additionalProperties": false, "type": "object", "required": [ "title" ], "title": "CollectionCreateRequest", "description": "A new, empty collection and its terms (its rights record). It stays private\nuntil you publish it with `POST /api/v1/datasets/{collection_id}/offer`." }, "CollectionDocumentListResponse": { "properties": { "documents": { "items": { "$ref": "#/components/schemas/CollectionDocumentResponse" }, "type": "array", "title": "Documents" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "title": "CollectionDocumentListResponse" }, "CollectionDocumentResponse": { "properties": { "doc_id": { "type": "string", "title": "Doc Id" }, "collection_id": { "type": "string", "title": "Collection Id" }, "doc_key": { "type": "string", "title": "Doc Key" }, "folder": { "type": "string", "title": "Folder" }, "title": { "type": "string", "title": "Title" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mime" }, "bytes": { "type": "integer", "title": "Bytes", "default": 0 }, "current_version": { "type": "string", "title": "Current Version" }, "state": { "type": "string", "title": "State" }, "chunks_indexed": { "type": "integer", "title": "Chunks Indexed", "default": 0 }, "chunks_quarantined": { "type": "integer", "title": "Chunks Quarantined", "default": 0 }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "versions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DocumentVersionEntry" }, "type": "array" }, { "type": "null" } ], "title": "Versions" }, "also_at": { "anyOf": [ { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Also At" } }, "type": "object", "required": [ "doc_id", "collection_id", "doc_key", "folder", "title", "current_version", "state" ], "title": "CollectionDocumentResponse", "description": "A document: one file, archive member or export thread, with its versions." }, "CollectionFolderListResponse": { "properties": { "folders": { "items": { "$ref": "#/components/schemas/CollectionFolderResponse" }, "type": "array", "title": "Folders" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "title": "CollectionFolderListResponse" }, "CollectionFolderResponse": { "properties": { "folder_id": { "type": "string", "title": "Folder Id" }, "path": { "type": "string", "title": "Path" }, "name": { "type": "string", "title": "Name" }, "depth": { "type": "integer", "title": "Depth", "default": 0 }, "document_count": { "type": "integer", "title": "Document Count", "default": 0 } }, "type": "object", "required": [ "folder_id", "path", "name" ], "title": "CollectionFolderResponse" }, "CollectionInfo": { "properties": { "collection": { "type": "string", "title": "Collection" }, "points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Points" } }, "type": "object", "required": [ "collection" ], "title": "CollectionInfo" }, "CollectionListResponse": { "properties": { "collections": { "items": { "$ref": "#/components/schemas/CollectionResponse" }, "type": "array", "title": "Collections" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "title": "CollectionListResponse" }, "CollectionResponse": { "properties": { "collection_id": { "type": "string", "title": "Collection Id" }, "dataset_id": { "type": "string", "title": "Dataset Id" }, "slug": { "type": "string", "title": "Slug" }, "title": { "type": "string", "title": "Title" }, "kind": { "type": "string", "title": "Kind", "default": "documents" }, "sensitivity": { "type": "string", "title": "Sensitivity", "default": "standard" }, "origin": { "type": "string", "title": "Origin", "default": "upload" }, "document_count": { "type": "integer", "title": "Document Count", "default": 0 }, "bytes_total": { "type": "integer", "title": "Bytes Total", "default": 0 }, "documents_listed": { "type": "boolean", "title": "Documents Listed", "default": true }, "offered": { "type": "boolean", "title": "Offered", "default": false }, "license_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Basis" }, "granted_uses": { "items": { "type": "string" }, "type": "array", "title": "Granted Uses" }, "jurisdiction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jurisdiction" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "collection_id", "dataset_id", "slug", "title" ], "title": "CollectionResponse", "description": "One of your collections. `collection_id` is also the `dataset_id` of its rights\nrecord: offer, withdraw, erase, earnings and search scope (`listing:`) take it." }, "CollectionRuleDeleteResponse": { "properties": { "rule_id": { "type": "string", "title": "Rule Id" }, "deleted": { "type": "boolean", "title": "Deleted", "default": true } }, "type": "object", "required": [ "rule_id" ], "title": "CollectionRuleDeleteResponse" }, "CollectionRuleListResponse": { "properties": { "rules": { "items": { "$ref": "#/components/schemas/CollectionRuleResponse" }, "type": "array", "title": "Rules" } }, "type": "object", "title": "CollectionRuleListResponse" }, "CollectionRuleRequest": { "properties": { "target_collection_id": { "type": "string", "title": "Target Collection Id" }, "path_glob": { "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ], "title": "Path Glob", "description": "fnmatch pattern over the document key, e.g. `Avtal/*` (`*` also crosses folders)." }, "mime": { "items": { "type": "string" }, "type": "array", "title": "Mime", "description": "Only these types; empty = any." }, "priority": { "type": "integer", "maximum": 100000.0, "minimum": 0.0, "title": "Priority", "description": "Lowest first.", "default": 100 }, "source_collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Collection Id", "description": "Only uploads headed for this collection; none = every upload." } }, "additionalProperties": false, "type": "object", "required": [ "target_collection_id" ], "title": "CollectionRuleRequest", "description": "Send new uploads whose document key matches to a collection." }, "CollectionRuleResponse": { "properties": { "rule_id": { "type": "string", "title": "Rule Id" }, "target_collection_id": { "type": "string", "title": "Target Collection Id" }, "source_collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Collection Id" }, "priority": { "type": "integer", "title": "Priority", "default": 100 }, "path_glob": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Path Glob" }, "mime": { "items": { "type": "string" }, "type": "array", "title": "Mime" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "rule_id", "target_collection_id" ], "title": "CollectionRuleResponse" }, "CollectionUpdateRequest": { "properties": { "title": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Title" }, "slug": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Slug" } }, "additionalProperties": false, "type": "object", "title": "CollectionUpdateRequest" }, "CollectionsResponse": { "properties": { "embedder": { "type": "string", "title": "Embedder" }, "backend": { "type": "string", "title": "Backend" }, "location": { "type": "string", "title": "Location" }, "collections": { "items": { "$ref": "#/components/schemas/CollectionInfo" }, "type": "array", "title": "Collections" } }, "type": "object", "required": [ "embedder", "backend", "location" ], "title": "CollectionsResponse" }, "ConvertEarningsRequest": { "properties": { "tokens": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Tokens" } }, "type": "object", "required": [ "tokens" ], "title": "ConvertEarningsRequest", "description": "Move tokens from the caller's OWN earnings bucket into its OWN credits bucket —\nthe explicit, user-initiated action that funds queries out of what an org was paid.\nThere is deliberately no org field: the target org is always ``principal.tenant_id``,\nnever caller-supplied, so this can never touch another org's balance." }, "DatasetEarningsPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "tokens": { "type": "integer", "title": "Tokens", "default": 0 }, "gross_tokens": { "type": "integer", "title": "Gross Tokens", "default": 0 }, "fee_tokens": { "type": "integer", "title": "Fee Tokens", "default": 0 } }, "type": "object", "required": [ "date" ], "title": "DatasetEarningsPoint", "description": "One day of earnings on one dataset." }, "DatasetEarningsResponse": { "properties": { "dataset_id": { "type": "string", "title": "Dataset Id" }, "from_ts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Ts" }, "to_ts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Ts" }, "total_tokens": { "type": "integer", "title": "Total Tokens", "default": 0 }, "gross_tokens": { "type": "integer", "title": "Gross Tokens", "default": 0 }, "fee_tokens": { "type": "integer", "title": "Fee Tokens", "default": 0 }, "series": { "items": { "$ref": "#/components/schemas/DatasetEarningsPoint" }, "type": "array", "title": "Series" }, "segments": { "items": { "$ref": "#/components/schemas/DatasetEarningsSegment" }, "type": "array", "title": "Segments" }, "min_buyers_per_segment": { "type": "integer", "title": "Min Buyers Per Segment", "default": 3 } }, "type": "object", "required": [ "dataset_id" ], "title": "DatasetEarningsResponse" }, "DatasetEarningsSegment": { "properties": { "segment": { "type": "string", "title": "Segment" }, "label": { "type": "string", "title": "Label" }, "queries": { "type": "integer", "title": "Queries", "default": 0 }, "tokens": { "type": "integer", "title": "Tokens", "default": 0 } }, "type": "object", "required": [ "segment", "label" ], "title": "DatasetEarningsSegment", "description": "One buyer segment's contribution to a dataset's earnings (FD6, D80). Never a\nbuyer organisation: ``segment`` is a cell with at least k buyers, or ``other``." }, "DatasetListResponse": { "properties": { "datasets": { "items": { "$ref": "#/components/schemas/DatasetRecordResponse" }, "type": "array", "title": "Datasets" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "title": "DatasetListResponse" }, "DatasetRecordResponse": { "properties": { "dataset_id": { "type": "string", "title": "Dataset Id" }, "data_owner": { "type": "string", "title": "Data Owner", "default": "" }, "warranties_ok": { "type": "boolean", "title": "Warranties Ok", "default": false }, "database_right": { "type": "boolean", "title": "Database Right", "default": false }, "jurisdiction": { "type": "string", "title": "Jurisdiction", "default": "global" }, "provider_agreement_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Agreement Ref" }, "granted_uses": { "items": { "type": "string" }, "type": "array", "title": "Granted Uses" }, "license_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Basis" }, "controller_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Controller Role" }, "legal_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Basis" }, "transfer_restriction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transfer Restriction" }, "labels": { "items": { "type": "string" }, "type": "array", "title": "Labels" }, "owner_tenant": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Tenant" }, "offered": { "type": "boolean", "title": "Offered", "default": false }, "entitled": { "type": "boolean", "title": "Entitled", "default": false }, "revoked": { "type": "boolean", "title": "Revoked", "default": false }, "display_identity": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Display Identity" }, "indexed_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexed Points" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug" }, "document_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Document Count" } }, "type": "object", "required": [ "dataset_id" ], "title": "DatasetRecordResponse" }, "DatasetUploadResponse": { "properties": { "dataset_id": { "type": "string", "title": "Dataset Id" }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id" }, "indexed": { "type": "integer", "title": "Indexed", "default": 0 }, "quarantined": { "type": "integer", "title": "Quarantined", "default": 0 }, "documents": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Documents" }, "displaced": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Displaced" }, "tiers": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Tiers" }, "collection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection" }, "labels": { "items": { "type": "string" }, "type": "array", "title": "Labels" }, "granted_uses": { "items": { "type": "string" }, "type": "array", "title": "Granted Uses" }, "license_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License Basis" }, "offered": { "type": "boolean", "title": "Offered", "default": false }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Item Id" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Batch Id" }, "duplicate": { "type": "boolean", "title": "Duplicate", "default": false }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "doc_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Doc Id" }, "doc_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Doc Key" } }, "type": "object", "required": [ "dataset_id" ], "title": "DatasetUploadResponse", "description": "Result of a self-service upload: the registered dataset + what the pipeline\ningest actually did (gate-passing chunks indexed, the rest quarantined)." }, "DatasetUsage": { "properties": { "hits": { "type": "integer", "title": "Hits", "default": 0 }, "tokens": { "type": "integer", "title": "Tokens", "default": 0 }, "cost_eur": { "type": "number", "title": "Cost Eur", "default": 0.0 } }, "type": "object", "title": "DatasetUsage" }, "DatasetUsageEntry": { "properties": { "dataset_id": { "type": "string", "title": "Dataset Id" }, "labels": { "items": { "type": "string" }, "type": "array", "title": "Labels" }, "data_owner": { "type": "string", "title": "Data Owner", "default": "" }, "queries": { "type": "integer", "title": "Queries", "default": 0 }, "hits": { "type": "integer", "title": "Hits", "default": 0 }, "tokens_attributed": { "type": "integer", "title": "Tokens Attributed", "default": 0 }, "earned_eur": { "type": "number", "title": "Earned Eur", "default": 0.0 }, "by_use_case": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Use Case" }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Used At" }, "self_queries": { "type": "integer", "title": "Self Queries", "default": 0 }, "self_hits": { "type": "integer", "title": "Self Hits", "default": 0 } }, "type": "object", "required": [ "dataset_id" ], "title": "DatasetUsageEntry", "description": "Per-dataset usage & earnings attribution over the requested window. ``earned_eur``\nsplits each query's billed cost proportionally across the datasets its hits touched —\nthe revenue-share substrate the per-hit rows exist for.\n\n``queries``/``hits``/``tokens_attributed``/``by_use_case``/``last_used_at`` cover ALL\nusage, including the owner querying its own dataset (\"internal only\" is a paid mode —\nself-use bills, and must be visible). ``earned_eur`` is computed from third-party rows\nonly, so self-use never inflates it (the wallet never pays an org for querying itself —\nsee ``metering._credit_earnings``). ``self_queries``/``self_hits`` isolate how much of\nthe total was the owner's own traffic, so the UI can label an all-self-use row honestly\ninstead of rendering it as unused." }, "DatasetUsageResponse": { "properties": { "from_ts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Ts" }, "to_ts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Ts" }, "datasets": { "items": { "$ref": "#/components/schemas/DatasetUsageEntry" }, "type": "array", "title": "Datasets" }, "total_earned_eur": { "type": "number", "title": "Total Earned Eur", "default": 0.0 } }, "type": "object", "title": "DatasetUsageResponse" }, "DayUsage": { "properties": { "day": { "type": "string", "title": "Day" }, "tokens": { "type": "integer", "title": "Tokens", "default": 0 }, "spend_eur": { "type": "number", "title": "Spend Eur", "default": 0.0 }, "queries": { "type": "integer", "title": "Queries", "default": 0 } }, "type": "object", "required": [ "day" ], "title": "DayUsage" }, "DisplayRequest": { "properties": { "dataset_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Dataset Id" }, "mode": { "type": "string", "pattern": "^(named|org_type)$", "title": "Mode" }, "org_type_label": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Org Type Label" }, "attribution_text": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Attribution Text" } }, "type": "object", "required": [ "mode" ], "title": "DisplayRequest" }, "DocumentDeleteResponse": { "properties": { "doc_id": { "type": "string", "title": "Doc Id" }, "collection_id": { "type": "string", "title": "Collection Id" }, "reason": { "type": "string", "title": "Reason" }, "points_deleted": { "type": "integer", "title": "Points Deleted", "default": 0 }, "originals_deleted": { "type": "integer", "title": "Originals Deleted", "default": 0 }, "versions": { "type": "integer", "title": "Versions", "default": 0 } }, "type": "object", "required": [ "doc_id", "collection_id", "reason" ], "title": "DocumentDeleteResponse" }, "DocumentVersionEntry": { "properties": { "sha256": { "type": "string", "title": "Sha256" }, "bytes": { "type": "integer", "title": "Bytes", "default": 0 }, "observed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Observed At" }, "superseded_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Superseded At" }, "current": { "type": "boolean", "title": "Current", "default": false } }, "type": "object", "required": [ "sha256" ], "title": "DocumentVersionEntry" }, "EraseResponse": { "properties": { "dataset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Id" }, "tenant": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" }, "reason": { "type": "string", "title": "Reason", "default": "erasure_request" }, "points_deleted": { "type": "integer", "title": "Points Deleted", "default": 0 }, "revoked": { "type": "boolean", "title": "Revoked", "default": false }, "record_deleted": { "type": "boolean", "title": "Record Deleted", "default": false }, "suppressed": { "type": "boolean", "title": "Suppressed", "default": false }, "originals_deleted": { "type": "integer", "title": "Originals Deleted", "default": 0 }, "cache_purged": { "type": "boolean", "title": "Cache Purged", "default": false }, "graph_rows_deleted": { "type": "integer", "title": "Graph Rows Deleted", "default": 0 }, "relations_deleted": { "type": "integer", "title": "Relations Deleted", "default": 0 } }, "type": "object", "title": "EraseResponse" }, "GpaiSummaryResponse": { "properties": { "general_information": { "additionalProperties": true, "type": "object", "title": "General Information" }, "data_sources": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Data Sources" }, "processing": { "additionalProperties": true, "type": "object", "title": "Processing" } }, "type": "object", "title": "GpaiSummaryResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "IngestAcceptedResponse": { "properties": { "item_id": { "type": "string", "title": "Item Id" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Batch Id" }, "upload_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Upload Id" }, "dataset_id": { "type": "string", "title": "Dataset Id" }, "state": { "type": "string", "title": "State" }, "duplicate": { "type": "boolean", "title": "Duplicate", "default": false }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sha256" }, "lane": { "type": "string", "title": "Lane", "default": "interactive" }, "offered": { "type": "boolean", "title": "Offered", "default": false }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "doc_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Doc Key" } }, "type": "object", "required": [ "item_id", "dataset_id", "state" ], "title": "IngestAcceptedResponse", "description": "202 Accepted from `POST /datasets/upload`: the file is stored and queued. Follow\n`GET /api/v1/ingest/items/{item_id}` until `state` is `done`, `failed` or\n`cancelled`." }, "IngestItemResponse": { "properties": { "item_id": { "type": "string", "title": "Item Id" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Batch Id" }, "upload_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Upload Id" }, "dataset_id": { "type": "string", "title": "Dataset Id" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name" }, "bytes": { "type": "integer", "title": "Bytes", "default": 0 }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sha256" }, "state": { "type": "string", "title": "State" }, "lane": { "type": "string", "title": "Lane", "default": "interactive" }, "attempts": { "type": "integer", "title": "Attempts", "default": 0 }, "max_attempts": { "type": "integer", "title": "Max Attempts", "default": 0 }, "error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Class" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "indexed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexed" }, "quarantined": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Quarantined" }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "doc_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Doc Id" }, "doc_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Doc Key" }, "duplicate_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Duplicate Of" }, "offer_refused": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Offer Refused" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finished At" } }, "type": "object", "required": [ "item_id", "dataset_id", "state" ], "title": "IngestItemResponse", "description": "One file in the ingest queue, and where it stands." }, "LedgerDayPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "spent_eur": { "type": "number", "title": "Spent Eur", "default": 0.0 }, "earned_eur": { "type": "number", "title": "Earned Eur", "default": 0.0 }, "spent_queries": { "type": "integer", "title": "Spent Queries", "default": 0 }, "earned_queries": { "type": "integer", "title": "Earned Queries", "default": 0 } }, "type": "object", "required": [ "date" ], "title": "LedgerDayPoint", "description": "One day of money moving, from the org's own ledger." }, "LedgerSummaryResponse": { "properties": { "from_ts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Ts" }, "to_ts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Ts" }, "owns_datasets": { "type": "boolean", "title": "Owns Datasets", "default": false }, "total_spent_eur": { "type": "number", "title": "Total Spent Eur", "default": 0.0 }, "total_earned_eur": { "type": "number", "title": "Total Earned Eur", "default": 0.0 }, "net_eur": { "type": "number", "title": "Net Eur", "default": 0.0 }, "total_spent_queries": { "type": "integer", "title": "Total Spent Queries", "default": 0 }, "total_earned_queries": { "type": "integer", "title": "Total Earned Queries", "default": 0 }, "series": { "items": { "$ref": "#/components/schemas/LedgerDayPoint" }, "type": "array", "title": "Series" } }, "type": "object", "title": "LedgerSummaryResponse", "description": "Both sides of the marketplace for one org, over one period.\n\nSpend and earnings are read from the SAME table (``wallet_ledger``) rather\nthan one from the ledger and one recomputed from usage records. Two sources\nfor two halves of a subtraction is how a \"net\" figure ends up not being the\ndifference between the two numbers printed beside it.\n\nEuro, not tokens: a query the org paid for and a query someone else ran\nagainst its data are not comparable as counts, and the whole point of putting\nthem on one chart is that they ARE comparable as money. Converted here with\nthe serving layer's own ``per_1k_tokens_eur`` — the frontend never sees that\nrate and must not guess it." }, "ListingCard": { "properties": { "listing_id": { "type": "string", "title": "Listing Id" }, "title": { "type": "string", "title": "Title" }, "origin": { "type": "string", "title": "Origin", "description": "`own` or `marketplace`." }, "source": { "type": "string", "title": "Source", "description": "Who the data is from, as the partner chose to be shown; `Your organisation` for your own." }, "verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Verified" }, "licence": { "type": "string", "title": "Licence" }, "uses": { "items": { "type": "string" }, "type": "array", "title": "Uses" }, "jurisdiction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jurisdiction" }, "labels": { "items": { "type": "string" }, "type": "array", "title": "Labels" }, "offered": { "type": "boolean", "title": "Offered", "default": false }, "passages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Passages", "description": "Indexed passages." }, "scope": { "type": "string", "title": "Scope", "description": "The `scope` value that searches only this listing." } }, "type": "object", "required": [ "listing_id", "title", "origin", "source", "licence", "scope" ], "title": "ListingCard", "description": "One listing a scope covers. Until collections exist a listing is a dataset." }, "ListingGroup": { "properties": { "listing_id": { "type": "string", "title": "Listing Id" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "hits": { "type": "integer", "title": "Hits", "default": 0 }, "ranks": { "items": { "type": "integer" }, "type": "array", "title": "Ranks" } }, "type": "object", "required": [ "listing_id" ], "title": "ListingGroup", "description": "Marketplace passages of one listing (E12): which ranks came from it." }, "ListingsResponse": { "properties": { "scope": { "type": "string", "title": "Scope" }, "listings": { "items": { "$ref": "#/components/schemas/ListingCard" }, "type": "array", "title": "Listings" } }, "type": "object", "required": [ "scope" ], "title": "ListingsResponse" }, "PricingResponse": { "properties": { "currency": { "type": "string", "title": "Currency" }, "per_1k_tokens_eur": { "type": "number", "title": "Per 1K Tokens Eur" }, "own_data_per_1k_tokens_eur": { "type": "number", "title": "Own Data Per 1K Tokens Eur" }, "own_data_price_decided": { "type": "boolean", "title": "Own Data Price Decided" }, "per_source_eur": { "type": "number", "title": "Per Source Eur" }, "credits_per_eur": { "type": "integer", "title": "Credits Per Eur" }, "platform_fee_bps": { "type": "integer", "title": "Platform Fee Bps" }, "partner_share_bps": { "type": "integer", "title": "Partner Share Bps" }, "token_unit": { "type": "string", "title": "Token Unit" }, "estimate_tokens_per_hit": { "type": "integer", "title": "Estimate Tokens Per Hit" }, "free_queries_per_org": { "type": "integer", "title": "Free Queries Per Org" } }, "type": "object", "required": [ "currency", "per_1k_tokens_eur", "own_data_per_1k_tokens_eur", "own_data_price_decided", "per_source_eur", "credits_per_eur", "platform_fee_bps", "partner_share_bps", "token_unit", "estimate_tokens_per_hit", "free_queries_per_org" ], "title": "PricingResponse", "description": "GET /api/v1/pricing — the one price, for the dashboard and the public." }, "QuotaResponse": { "properties": { "rpm_limit": { "type": "integer", "title": "Rpm Limit" }, "rpm_remaining": { "type": "integer", "title": "Rpm Remaining" }, "daily_quota": { "type": "integer", "title": "Daily Quota" }, "daily_remaining": { "type": "integer", "title": "Daily Remaining" }, "monthly_quota": { "type": "integer", "title": "Monthly Quota" }, "monthly_remaining": { "type": "integer", "title": "Monthly Remaining" }, "free_queries_remaining": { "type": "integer", "title": "Free Queries Remaining" }, "wallet_balance_tokens": { "type": "integer", "title": "Wallet Balance Tokens" } }, "type": "object", "required": [ "rpm_limit", "rpm_remaining", "daily_quota", "daily_remaining", "monthly_quota", "monthly_remaining", "free_queries_remaining", "wallet_balance_tokens" ], "title": "QuotaResponse" }, "RecentQuery": { "properties": { "time": { "type": "string", "title": "Time" }, "query_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query Id" }, "collection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection" }, "use_case": { "type": "string", "title": "Use Case", "default": "rag" }, "hits": { "type": "integer", "title": "Hits", "default": 0 }, "tokens": { "type": "integer", "title": "Tokens", "default": 0 }, "cost_eur": { "type": "number", "title": "Cost Eur", "default": 0.0 }, "status": { "type": "string", "title": "Status", "default": "ok" } }, "type": "object", "required": [ "time" ], "title": "RecentQuery", "description": "One row of the dashboard's recent-queries table (mirrors the Trivda shape)." }, "SearchHit": { "properties": { "rank": { "type": "integer", "title": "Rank" }, "score": { "type": "number", "title": "Score" }, "text": { "type": "string", "title": "Text" }, "readiness_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Readiness Tier" }, "source_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Uri" }, "concept_ids": { "items": { "type": "string" }, "type": "array", "title": "Concept Ids" }, "license": { "additionalProperties": true, "type": "object", "title": "License" }, "content_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Class" }, "pii_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pii Tier" }, "citation": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Citation" }, "provenance_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provenance Id" }, "display_identity": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Display Identity" }, "attribution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribution" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin" }, "listing_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Listing Id" }, "relations": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Relations", "description": "Ids of the relations in this response's `relations` that concern this passage. Present only for an organisation with the context graph." } }, "type": "object", "required": [ "rank", "score", "text" ], "title": "SearchHit" }, "SearchQueryRequest": { "properties": { "query": { "type": "string", "maxLength": 4000, "minLength": 1, "title": "Query", "description": "What to search for, in plain language." }, "top_k": { "type": "integer", "maximum": 50.0, "minimum": 1.0, "title": "Top K", "description": "How many passages to return at most.", "default": 8 }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "Optional subject domain (for example `legal`, `finance`, `medical`). It steers query expansion and, where one is configured, the domain's own index." }, "content_type": { "type": "string", "title": "Content Type", "description": "Which kind of content to search: `general` (default) or a specialised family such as `code`; picks the index the query runs against.", "default": "general" }, "use_case": { "type": "string", "title": "Use Case", "description": "What you will do with the passages: `search`, `rag`, `finetune`, `train`, `export` or `redistribute`. Only passages whose licence allows it are returned, and the use is recorded with each search.", "default": "rag" }, "collection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection", "description": "Optional index name. A scoped key may only name an index in its scopes." }, "min_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Min Tier", "description": "Reserved; not applied yet." }, "scope": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ], "title": "Scope", "description": "Where to search: `mine` (your organisation's own data only), `marketplace` (other organisations' published data only), `all` (both) or `listing:` (one listing; see `GET /api/v1/search/listings`). Left out, your key's or organisation's default applies (`GET /api/v1/search/scope`); for an existing key that is `all`." } }, "type": "object", "required": [ "query" ], "title": "SearchQueryRequest" }, "SearchQueryResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/SearchHit" }, "type": "array", "title": "Results" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope", "description": "The scope this search ran in (`mine`, `marketplace`, `all`, `listing:`)." }, "listings": { "items": { "$ref": "#/components/schemas/ListingGroup" }, "type": "array", "title": "Listings", "description": "The marketplace passages grouped by listing, best rank first. Your own passages are not grouped." }, "query_expansion": { "additionalProperties": true, "type": "object", "title": "Query Expansion" }, "used": { "additionalProperties": true, "type": "object", "title": "Used" }, "relations": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Relations", "description": "The relations between the data points of the passages (D217), for an organisation with the context graph; absent otherwise. Each has an `id` (listed on the passages it concerns), `subject`, `predicate` and `object` (node keys) or `value`, the labels `subject_label` / `object_label` as its sources write them, `qualifiers`, a `confidence`, a one-line `text`, the ranks of the passages it concerns (`hits`) and of those that state it (`stated_in`), and the `sources` its evidence is in. A relation is evidence that a source states it, not a TRIVDA assertion. Only relations whose evidence you may see are listed." }, "vocabularies": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Vocabularies", "description": "The vocabularies whose concept ids appear in this response (in `concept_ids` or the query expansion): name, version, licence and, where the licence asks for it, the attribution text to show with them." }, "query_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query Id" }, "latency_ms": { "type": "integer", "title": "Latency Ms", "default": 0 }, "billing": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Billing", "description": "What this call cost: `tokens` (billable), `cost_eur` (charged), `list_cost_eur` (the price of what was returned), `credits_charged`, `free_query_used`, `balance_credits` (after the charge) and `replayed` (an Idempotency-Key replay, never charged)." } }, "type": "object", "title": "SearchQueryResponse" }, "SearchScopeResponse": { "properties": { "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Intent", "description": "What your organisation uses TRIVDA for: `knowledge_bank`, `marketplace` or null." }, "default_scope": { "type": "string", "title": "Default Scope", "description": "The scope a search runs in when it names none, for this credential." }, "default_source": { "type": "string", "title": "Default Source", "description": "Why: `key` (the API key's `default_scope:`), `intent` or `default`." }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "graph_evidence": { "type": "boolean", "title": "Graph Evidence", "description": "Whether `POST /api/v1/context/gather` can build an evidence bundle for you.", "default": false } }, "type": "object", "required": [ "default_scope", "default_source" ], "title": "SearchScopeResponse", "description": "Your organisation's search scope settings (E12)." }, "SearchScopeUpdate": { "properties": { "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Intent", "description": "`knowledge_bank` (searches default to your own data), `marketplace`, or null for the platform default (`all`)." } }, "additionalProperties": false, "type": "object", "title": "SearchScopeUpdate" }, "UploadCancelResponse": { "properties": { "upload_id": { "type": "string", "title": "Upload Id" }, "outcome": { "type": "string", "title": "Outcome" }, "dataset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Id" }, "points_deleted": { "type": "integer", "title": "Points Deleted", "default": 0 }, "originals_deleted": { "type": "integer", "title": "Originals Deleted", "default": 0 } }, "type": "object", "required": [ "upload_id", "outcome" ], "title": "UploadCancelResponse" }, "UploadStatusResponse": { "properties": { "upload_id": { "type": "string", "title": "Upload Id" }, "state": { "type": "string", "title": "State" }, "dataset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Id" }, "indexed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexed" }, "quarantined": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Quarantined" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Item Id" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Batch Id" }, "attempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Attempts" } }, "type": "object", "required": [ "upload_id", "state" ], "title": "UploadStatusResponse", "description": "Where one upload stands, for a client whose request timed out while the\npipeline kept running (the dashboard's upload worker; server/uploads.py)." }, "UsageQueriesResponse": { "properties": { "queries": { "items": { "$ref": "#/components/schemas/RecentQuery" }, "type": "array", "title": "Queries" }, "limit": { "type": "integer", "title": "Limit", "default": 50 }, "offset": { "type": "integer", "title": "Offset", "default": 0 } }, "type": "object", "title": "UsageQueriesResponse" }, "UsageSummaryResponse": { "properties": { "consumed_eur": { "type": "number", "title": "Consumed Eur", "default": 0.0 }, "projected_eom_eur": { "type": "number", "title": "Projected Eom Eur", "default": 0.0 }, "total_hits": { "type": "integer", "title": "Total Hits", "default": 0 }, "total_tokens": { "type": "integer", "title": "Total Tokens", "default": 0 }, "by_dataset": { "additionalProperties": { "$ref": "#/components/schemas/DatasetUsage" }, "type": "object", "title": "By Dataset" }, "by_day": { "items": { "$ref": "#/components/schemas/DayUsage" }, "type": "array", "title": "By Day" } }, "type": "object", "title": "UsageSummaryResponse", "description": "Dashboard header: spend so far this window, a linear end-of-month projection,\nand the breakdowns the Trivda usage view charts (per dataset, per day)." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VocabulariesResponse": { "properties": { "vocabularies": { "items": { "$ref": "#/components/schemas/VocabularyInfo" }, "type": "array", "title": "Vocabularies" } }, "type": "object", "title": "VocabulariesResponse" }, "VocabularyInfo": { "properties": { "vocab_id": { "type": "string", "title": "Vocab Id" }, "name": { "type": "string", "title": "Name" }, "publisher": { "type": "string", "title": "Publisher" }, "version": { "type": "string", "title": "Version" }, "licence": { "type": "string", "title": "Licence", "description": "SPDX id, or LicenseRef- for a custom licence" }, "licence_url": { "type": "string", "title": "Licence Url" }, "source_url": { "type": "string", "title": "Source Url" }, "status": { "type": "string", "title": "Status", "description": "active: loaded and linked. review: waiting for legal review, not loaded. excluded: never loaded into anything that serves results" }, "redistribute_ids": { "type": "boolean", "title": "Redistribute Ids" }, "redistribute_labels": { "type": "boolean", "title": "Redistribute Labels" }, "redistribute_definitions": { "type": "boolean", "title": "Redistribute Definitions" }, "crosswalk_allowed": { "type": "boolean", "title": "Crosswalk Allowed" }, "attribution_required": { "type": "boolean", "title": "Attribution Required" }, "attribution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribution" }, "retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retrieved At", "description": "When the loaded data was retrieved" }, "terms_checked_at": { "type": "string", "title": "Terms Checked At", "description": "When the licence terms were last read" }, "notes": { "type": "string", "title": "Notes", "default": "" } }, "type": "object", "required": [ "vocab_id", "name", "publisher", "version", "licence", "licence_url", "source_url", "status", "redistribute_ids", "redistribute_labels", "redistribute_definitions", "crosswalk_allowed", "attribution_required", "terms_checked_at" ], "title": "VocabularyInfo" }, "WalletResponse": { "properties": { "balance_tokens": { "type": "integer", "title": "Balance Tokens", "default": 0 }, "free_queries_remaining": { "type": "integer", "title": "Free Queries Remaining", "default": 0 }, "credits_tokens": { "type": "integer", "title": "Credits Tokens", "default": 0 }, "earnings_tokens": { "type": "integer", "title": "Earnings Tokens", "default": 0 }, "withdrawable_tokens": { "type": "integer", "title": "Withdrawable Tokens", "default": 0 } }, "type": "object", "title": "WalletResponse" } } } }