Skip to main content
BETA
MenuClose

Tolvi AI

9 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.

Get the firm’s token balance, expiry and this month’s use

GET/api/v1/ai/balance

Scopes
engagements:read

Responses

200 OK, application/json

Body: object (AiBalance).

200 OK response for GET /api/v1/ai/balance
FieldTypeDescription
balancerequiredinteger

Tokens available now (unexpired).

heldrequiredinteger

Held for calls in progress.

spendablerequiredinteger
capacityrequiredinteger

Original size of the live lots (for the 20% / 5% alerts).

levelrequiredstring (AiBalanceLevel)

One of: ok, low, critical

nextExpiryrequiredobject (AiTokenExpiry)nullable
nextExpiry.​tokensrequiredinteger
nextExpiry.​onrequiredstring (date-time)
usedThisMonthrequiredinteger
myUsedThisMonthrequiredinteger
myLimitrequiredintegernullable
enabledrequiredboolean

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Token use by month, person, feature, engagement or model, with recent ledger entries

GET/api/v1/ai/usage

Scopes
engagements:read

Parameters

Parameters for GET /api/v1/ai/usage
NameInTypeDescription
groupByquerystring (AiUsageGroupBy)

One of: month, user, feature, engagement, model

fromquerystring (date)
toquerystring (date)

Responses

200 OK, application/json

Body: object (AiUsage).

200 OK response for GET /api/v1/ai/usage
FieldTypeDescription
groupByrequiredstring (AiUsageGroupBy)

One of: month, user, feature, engagement, model

groupsrequiredarray of AiUsageGroup
groups[].​keyrequiredstring
groups[].​labelrequiredstring
groups[].​tokensrequiredinteger

Tolvi AI tokens charged.

groups[].​callsrequiredinteger
groups[].​inputTokensrequiredinteger
groups[].​outputTokensrequiredinteger
groups[].​providerCostPencerequiredinteger

Provider cost in pence (at the configured exchange rate).

totalrequiredinteger
recentrequiredarray of AiLedgerEntry

The 50 most recent ledger entries.

recent[].​idrequiredstring
recent[].​atrequiredstring (date-time)
recent[].​typerequiredstring (AiLedgerEntryType)

One of: purchase, allowance, usage, refund, expiry, adjustment

recent[].​tokensrequiredinteger

Positive for credits, negative for usage and expiry.

recent[].​userIdrequiredstring (uuid)nullable
recent[].​engagementIdrequiredstring (uuid)nullable
recent[].​featurerequiredstringnullable
recent[].​modelrequiredstringnullable

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

List the token packs and prices (net, VAT, gross in pence)

GET/api/v1/ai/packs

Scopes
engagements:read

VAT is 0 and gross equals net while Tolvi is not VAT-registered (vatRegistered false).

Responses

200 OK, application/json

Body: object (AiPacks).

200 OK response for GET /api/v1/ai/packs
FieldTypeDescription
versionrequiredstring
currencyrequiredstring
vatRegisteredrequiredboolean

Whether Tolvi charges VAT on its prices. False: no VAT is charged, so vatPence is 0 and grossPence is the net price.

packsrequiredarray of AiPack
packs[].​idrequiredstring (TokenPackId)

One of: starter, practice, firm

packs[].​namerequiredstring
packs[].​tokensrequiredinteger
packs[].​netPencerequiredinteger

Net price in pence.

packs[].​vatPencerequiredinteger

VAT in pence: 0 while Tolvi is not VAT-registered.

packs[].​grossPencerequiredinteger

Net plus VAT, in pence (the net price while Tolvi is not VAT-registered).

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Buy a token pack (Stripe Checkout)

POST/api/v1/ai/checkout

Scopes
settings:admin and engagements:read
Access
A signed-in Tolvi session only, never an API token.

Partners and admins (or admins only, per the firm’s AI settings). The tokens are credited when Stripe confirms payment.

Request body

Required. application/json: object (AiCheckoutRequest).

Request body for POST /api/v1/ai/checkout
FieldTypeDescription
packIdrequiredstring (TokenPackId)

One of: starter, practice, firm

Responses

200 OK, application/json

Body: object (AiCheckout).

200 OK response for POST /api/v1/ai/checkout
FieldTypeDescription
sessionIdrequiredstring
urlrequiredstring (uri)

Send the browser here (Stripe Checkout).

packrequiredobject (AiPack)
pack.​idrequiredstring (TokenPackId)

One of: starter, practice, firm

pack.​namerequiredstring
pack.​tokensrequiredinteger
pack.​netPencerequiredinteger

Net price in pence.

pack.​vatPencerequiredinteger

VAT in pence: 0 while Tolvi is not VAT-registered.

pack.​grossPencerequiredinteger

Net plus VAT, in pence (the net price while Tolvi is not VAT-registered).

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

List recent AI suggestions

GET/api/v1/ai/suggestions

Scopes
engagements:read

Parameters

Parameters for GET /api/v1/ai/suggestions
NameInTypeDescription
engagementIdquerystring (uuid)

Responses

200 OK, application/json

Body: array of AiSuggestion.

An AI draft. A person accepts (then applies it through the normal endpoints) or discards it.

200 OK response for GET /api/v1/ai/suggestions
FieldTypeDescription
[].​idrequiredstring (uuid)
[].​featurerequiredstring (AiFeature)

One of: explain_movements, suggest_mappings, review_assistant, check_evidence, explain_sync_changes, ask_tolvi, draft_client_queries, summarise_meeting, sa_assistant, sa_read_document, accounts_draft_note

[].​engagementIdrequiredstring (uuid)nullable
[].​sectionCoderequiredstringnullable
[].​outputrequiredobject

The feature’s structured output (see @tolvi/ai output schemas).

[].​tokensrequiredinteger

Tolvi AI tokens charged.

[].​modelrequiredstring
[].​promptVersionrequiredstring
[].​statusrequiredstring (AiSuggestionStatus)

One of: proposed, accepted, discarded

[].​createdAtrequiredstring (date-time)
[].​decidedByrequiredstring (uuid)nullable
[].​decidedAtrequiredstring (date-time)nullable
[].​estimateinteger

The estimate shown before running.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Get an AI suggestion

GET/api/v1/ai/suggestions/{id}

Scopes
engagements:read

Parameters

Parameters for GET /api/v1/ai/suggestions/{id}
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (AiSuggestion).

An AI draft. A person accepts (then applies it through the normal endpoints) or discards it.

200 OK response for GET /api/v1/ai/suggestions/{id}
FieldTypeDescription
idrequiredstring (uuid)
featurerequiredstring (AiFeature)

One of: explain_movements, suggest_mappings, review_assistant, check_evidence, explain_sync_changes, ask_tolvi, draft_client_queries, summarise_meeting, sa_assistant, sa_read_document, accounts_draft_note

engagementIdrequiredstring (uuid)nullable
sectionCoderequiredstringnullable
outputrequiredobject

The feature’s structured output (see @tolvi/ai output schemas).

tokensrequiredinteger

Tolvi AI tokens charged.

modelrequiredstring
promptVersionrequiredstring
statusrequiredstring (AiSuggestionStatus)

One of: proposed, accepted, discarded

createdAtrequiredstring (date-time)
decidedByrequiredstring (uuid)nullable
decidedAtrequiredstring (date-time)nullable
estimateinteger

The estimate shown before running.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Accept an AI suggestion

POST/api/v1/ai/suggestions/{id}/accept

Scopes
engagements:write and engagements:read

Records the decision; the person then applies it (e.g. saves the note) through the normal endpoints.

Parameters

Parameters for POST /api/v1/ai/suggestions/{id}/accept
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (AiSuggestion).

An AI draft. A person accepts (then applies it through the normal endpoints) or discards it.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Discard an AI suggestion

POST/api/v1/ai/suggestions/{id}/discard

Scopes
engagements:write and engagements:read

Parameters

Parameters for POST /api/v1/ai/suggestions/{id}/discard
NameInTypeDescription
idrequiredpathstring (uuid)

Responses

200 OK, application/json

Body: object (AiSuggestion).

An AI draft. A person accepts (then applies it through the normal endpoints) or discards it.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Run a Tolvi AI feature

POST/api/v1/ai/{feature}

Scopes
engagements:write and engagements:read
Retries
Send an Idempotency-Key to make retries safe.

Estimate → reserve → run → settle against the firm’s token ledger. Returns a suggestion (status proposed). With estimateOnly, returns the estimate instead (AiEstimate). 402 when the balance cannot cover the estimate; 403 when the feature is off or your monthly limit is used.

Parameters

Parameters for POST /api/v1/ai/{feature}
NameInTypeDescription
featurerequiredpathstring (AiFeature)

One of: explain_movements, suggest_mappings, review_assistant, check_evidence, explain_sync_changes, ask_tolvi, draft_client_queries, summarise_meeting, sa_assistant, sa_read_document, accounts_draft_note

Idempotency-Keyheaderstring

A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours.

1 to 255 characters

Request body

Required. application/json: object (AiRequest).

engagementId is required. explain_movements: sectionCode (and optionally accountCodes); review_assistant: optional sectionCode; check_evidence: evidenceId (and optionally the ticked account in accountCodes); ask_tolvi: question (and history).

Request body for POST /api/v1/ai/{feature}
FieldTypeDescription
engagementIdrequiredstring (uuid)
sectionCodestring
accountCodesarray of string

up to 200 items

evidenceIdstring (uuid)
questionstring

up to 4000 characters

historyarray of AskHistoryTurn

up to 20 items

history[].​questionrequiredstring

up to 4000 characters

history[].​answerrequiredstring

up to 20000 characters

estimateOnlyboolean

Only estimate the cost; nothing is reserved or run.

Responses

200 OK, application/json

Body: one of: object (AiSuggestion), object (AiEstimate).

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).