API reference

GET /api/v1/pricing

Get the price list No authentication operationId get_pricing

The current price list. No authentication needed.

Searches are priced per 1,000 billable tokens in the passages returned; the wallet holds credits (credits_per_eur credits = EUR 1).

Responses

GET /api/v1/search/collections

List the indexes you can search operationId list_collections

The search indexes your key can query, with their passage counts.

Responses

GET /api/v1/search/listings

List the listings a scope covers operationId list_search_listings

The listings a scope covers, so you can choose one before you search (scope=listing:<id>). Free.

Parameters

Responses

POST /api/v1/search/query

Search licensed data operationId search

Search licensed data and get ranked passages, each with its licence and provenance.

Charged per 1,000 billable tokens in the passages returned. A search with no results costs nothing. The cost is in the billing object and in the X-Query-Cost, X-Tokens-Used and X-Credits-Remaining headers.

Parameters

Request body application/json

Responses

GET /api/v1/search/quota

Get your rate limits and quota operationId search_quota

Your rate limits and what is left of them now (per minute, per day, per month), plus free searches and wallet credits.

Responses

GET /api/v1/search/results/{query_id}

Fetch an earlier search's results again operationId get_search_results

Fetch the results of an earlier search again, free, for 7 days.

Parameters

Responses

GET /api/v1/search/scope

Get your default search scope operationId get_search_scope

Where your searches look when they name no scope, and why.

Responses

PUT /api/v1/search/scope

Set what your organisation uses TRIVDA for operationId put_search_scope

Say what your organisation uses TRIVDA for. knowledge_bank makes searches that name no scope search only your own data; a key minted with a default_scope: scope keeps its own default.

Request body application/json

Responses

GET /api/v1/api-keys

List API keys operationId list_api_keys

List your organisation's API keys. Secrets are never returned, only their display prefix.

Responses

POST /api/v1/api-keys

Create an API key operationId create_api_key

Create an API key for your organisation. The secret (sk_live_...) is in this response only; store it safely.

Scopes narrow what the key may do: collection names and/or use_case:<name>. An empty list means everything your organisation may do. With sandbox: true the key is a sandbox key (sk_test_...) that only ever gets synthetic fixtures and is never charged.

Request body application/json

Responses

DELETE /api/v1/api-keys/{key_id}

Revoke an API key operationId revoke_api_key

Revoke an API key. It stops working at once.

Parameters

Responses

GET /api/v1/api-keys/current

Show the key this request uses operationId get_current_api_key

The credential this request was made with: its organisation, and for an API key its id, display prefix, name and scopes. Use it to check which key a script runs with.

Responses

GET /api/v1/usage/ledger

Get money spent and earned per day operationId usage_ledger

Money spent and earned per day, from your organisation's wallet ledger.

Parameters

Responses

GET /api/v1/usage/queries

List recent searches operationId usage_queries

Your recent searches, newest first, with hits, tokens and cost.

Parameters

Responses

GET /api/v1/usage/summary

Get spend and usage for a period operationId usage_summary

Spend and usage for a period, in total, per dataset and per day, with a projection to the end of the month.

Parameters

Responses

GET /api/v1/usage/wallet

Get your wallet balance operationId usage_wallet

Your wallet: spendable credits, earnings and free searches left.

Responses

POST /api/v1/wallet/convert-earnings

Convert earnings into credits operationId convert_earnings

Move earnings into spendable credits. Converted earnings can no longer be paid out.

Request body application/json

Responses

GET /api/v1/billing/profile

Get your billing details operationId get_billing_profile

Your organisation's billing details, and the required fields that are still missing.

Responses

PUT /api/v1/billing/profile

Set your billing details operationId put_billing_profile

Set your organisation's billing details. An EU VAT number is checked against VIES.

Request body application/json

Responses

GET /api/v1/billing/transactions

List your transactions operationId list_transactions

Your organisation's transactions, newest first: top-ups (with the Stripe invoice id and the VAT paid), searches, earnings, refunds, adjustments, promotional credit and payouts. Pass next_before back as before for the next page.

Parameters

Responses

GET /api/v1/ledger-roots

List the published monthly ledger roots operationId list_ledger_roots

Every published monthly ledger root. Each line of a partner statement carries an inclusion proof that folds up to its month's root here, so a partner can check its statement was part of the ledger without seeing anyone else's lines.

Responses

GET /api/v1/statements

List your partner statements operationId list_my_statements

Your monthly partner statements, your earnings balance and the payout terms (hold period and minimum).

Responses

GET /api/v1/statements/{statement_id}

Get one partner statement operationId get_my_statement

One monthly partner statement, with a line per dataset.

Parameters

Responses

GET /api/v1/statements/{statement_id}/csv

Download one partner statement as CSV operationId get_my_statement_csv

One monthly partner statement as CSV.

Parameters

Responses

GET /api/v1/compliance/gpai-summary

Get an EU AI Act training-content summary operationId gpai_summary

An EU AI Act article 53 summary of the datasets you can see: sources, licence basis, jurisdiction and opt-out posture.

Parameters

Responses

GET /api/v1/datasets

List datasets operationId list_datasets

The datasets you can see, your own and those offered on the marketplace, in dataset_id order, limit at a time (at most 1,000). When there are more, next_cursor is set: pass it back as cursor for the next page.

Parameters

Responses

GET /api/v1/datasets/{dataset_id}/earnings

Get one dataset's earnings operationId dataset_earnings

What one of your datasets has earned, per day and per buyer segment.

Parameters

Responses

POST /api/v1/datasets/{dataset_id}/erase

Delete a dataset operationId erase_dataset

Delete one of your datasets: its indexed passages, stored originals and cached results. reason=owner_removed lets you upload the same data again; reason=erasure_request (the default) blocks it from being ingested again.

Parameters

Responses

POST /api/v1/datasets/{dataset_id}/offer

Publish a dataset to the marketplace operationId offer_dataset

Publish one of your datasets to the marketplace. Every paying organisation can then search it, and you earn on each paid search by another organisation that returns it.

Parameters

Responses

POST /api/v1/datasets/{dataset_id}/withdraw

Take a dataset off the marketplace operationId withdraw_dataset

Take one of your datasets off the marketplace. It stays indexed and searchable by your own organisation.

Parameters

Responses

POST /api/v1/datasets/upload

Upload a file into a dataset operationId upload_dataset

Upload a file, or a .zip of files, into one of your collections. The file is stored and queued, and the answer is 202 Accepted with an item_id: follow it at GET /api/v1/ingest/items/{item_id} until it is done (with how many passages were indexed and how many were held back) or failed (with the reason).

Where it goes: collection_id (from POST /api/v1/collections) puts it in that collection, whose terms stay as they are. Otherwise dataset_id is your own name for a collection: the first upload under a name creates it (with a new col_ id, and the form's licence fields as its terms), later uploads under the same name add to it. Without either, the file's name is used. A routing rule (POST /api/v1/collection-rules) may send it on to another collection. doc_key names the document inside the collection, usually its path in its folder (Avtal/2024/lease.pdf; default: the file name): uploading new bytes under the same doc_key replaces the document's previous version. Bytes your organisation already holds anywhere are not processed again (duplicate: true, the answer of the upload that holds them). An upload stays private unless offered is true.

Request body multipart/form-data

Responses

GET /api/v1/datasets/usage

Get usage and earnings per dataset operationId dataset_usage

Usage and earnings for the datasets your organisation owns.

Parameters

Responses

GET /api/v1/disclosure/display

Get how buyers see you operationId get_display

How buyers see your organisation: your default choice and each of your datasets' choice, with the name or organisation type buyers are shown.

Responses

PUT /api/v1/disclosure/display

Set how buyers see you operationId put_display

Choose how buyers see you: named or org_type (a verified organisation type, with an optional label of your own), for one dataset or, without dataset_id, as your default. Attribution a licence requires is shown to buyers either way.

Request body application/json

Responses

GET /api/v1/ingest/items/{item_id}

Get the state of a queued file operationId get_ingest_item

One queued file: queued, running, done (with the passages indexed and held back), failed (with the reason) or cancelled. Poll every few seconds.

Parameters

Responses

GET /api/v1/uploads/{upload_id}

Get the state of an upload operationId upload_status

The state of an upload you started with an upload_id: queued, running, done, failed, cancel_requested, cancelled or unknown.

Parameters

Responses

POST /api/v1/uploads/{upload_id}/cancel

Cancel an upload operationId cancel_upload

Cancel an upload you started with an upload_id, at any stage. Anything it already indexed is removed.

Parameters

Responses

GET /api/v1/collection-rules

List your routing rules operationId list_collection_rules

Your organisation's routing rules, in the order they are tried.

Responses

POST /api/v1/collection-rules

Create a routing rule operationId create_collection_rule

Route new uploads: a file whose document key matches path_glob (and whose type is in mime, if given) goes to target_collection_id instead of where its upload named, and takes that collection's terms. Rules are tried lowest priority first; the first that matches wins. Files already uploaded do not move.

Request body application/json

Responses

DELETE /api/v1/collection-rules/{rule_id}

Delete a routing rule operationId delete_collection_rule

Delete a routing rule. Files it already routed stay where they are.

Parameters

Responses

GET /api/v1/collections

List your collections operationId list_data_collections

Your organisation's collections, limit at a time (at most 200). When there are more, pass next_cursor back as cursor.

Parameters

Responses

POST /api/v1/collections

Create a collection operationId create_collection

Make a new, empty collection with its terms. Upload into it with POST /api/v1/datasets/upload and collection_id. It stays private until you publish it (POST /api/v1/datasets/{collection_id}/offer).

Request body application/json

Responses

GET /api/v1/collections/{collection_id}

Get one collection operationId get_collection

One of your collections: its title, slug, size and terms.

Parameters

Responses

PATCH /api/v1/collections/{collection_id}

Rename a collection operationId update_collection

Rename a collection: its title, or its slug (409 if you already use it). Its id never changes.

Parameters

Request body application/json

Responses

GET /api/v1/collections/{collection_id}/documents

List a collection's documents operationId list_collection_documents

A collection's documents in key order, limit at a time (at most 500). folder (a path such as /Avtal/2024) lists only the documents directly in it.

Parameters

Responses

GET /api/v1/collections/{collection_id}/documents/{doc_id}

Get one document and its versions operationId get_collection_document

One document: its state, every version it has had, and other places the same bytes were uploaded to.

Parameters

Responses

DELETE /api/v1/collections/{collection_id}/documents/{doc_id}

Remove one document operationId delete_collection_document

Remove one document from a collection: every version's passages, its stored original and anything cached that quotes it. The collection, its terms and its other documents stay. An automatic sync does not bring the document back; uploading it again yourself does.

Parameters

Responses

GET /api/v1/collections/{collection_id}/folders

List a collection's folders operationId list_collection_folders

A collection's folders in path order (at most 1,000 a page). parent (a path, / for the top) lists only its direct sub-folders.

Parameters

Responses

GET /api/v1/vocabularies

List the vocabularies and their licences No authentication operationId list_vocabularies

The vocabularies and ontologies TRIVDA loads, links against or has excluded, with their version, licence, what may be redistributed and the attribution results show with their concept ids. No authentication needed.

Responses