Exchange an email and password — plus a one-time code where two-factor is on — for a bearer token and the abilities it was granted.

curl -X POST 'https://ovolos.ai/api/v1/auth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
      "email": "[email protected]",
      "password": "YOUR_PASSWORD",
      "device_name": "Budget spreadsheet sync"
  }'

const response = await fetch("https://ovolos.ai/api/v1/auth/token", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "email": "[email protected]",
      "password": "YOUR_PASSWORD",
      "device_name": "Budget spreadsheet sync"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/auth/token",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "email": "[email protected]",
        "password": "YOUR_PASSWORD",
        "device_name": "Budget spreadsheet sync",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "token": "3|ovo_<redacted: 48 more characters>",
        "token_type": "Bearer",
        "device_name": "Budget spreadsheet sync",
        "abilities": [
            "profile:read",
            "networth:read",
            "accounts:read",
            "holdings:read",
            "spending:read",
            "planning:read",
            "connections:read"
        ]
    }
}

Swap the one-time code from the mobile sign-in redirect for a bearer token, in the same response shape as the token endpoint above.

• The code is single-use, is consumed on lookup whether or not it turns out to be valid, and expires within minutes.
• It carries the abilities asked for when the code was issued, so this cannot widen a token past what was approved in the browser.

curl -X POST 'https://ovolos.ai/api/v1/auth/mobile/exchange' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
      "code": "YOUR_CODE",
      "device_name": "Ovolos for iOS"
  }'

const response = await fetch("https://ovolos.ai/api/v1/auth/mobile/exchange", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "code": "YOUR_CODE",
      "device_name": "Ovolos for iOS"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/auth/mobile/exchange",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "code": "YOUR_CODE",
        "device_name": "Ovolos for iOS",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "token": "3|ovo_<redacted: 48 more characters>",
        "token_type": "Bearer",
        "device_name": "Ovolos for iOS",
        "abilities": [
            "profile:read",
            "networth:read",
            "accounts:read",
            "holdings:read",
            "spending:read",
            "planning:read",
            "connections:read"
        ]
    }
}

Revoke the token used on this request (logout). Returns 204 No Content.

Takes no query parameters and no body.

curl -X DELETE 'https://ovolos.ai/api/v1/auth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/auth/token", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/auth/token",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

204 No Content

The vocabularies that are the same for every reader on the platform: every account type with the side it falls on, and every reportable asset-class slug with its label. These are what `type` and `{class}` are validated against.

• The one read on this API whose answer cannot vary by portfolio: X-Portfolio changes nothing, and it is safe to cache until you deploy a new release.

Takes no query parameters and no body.

curl 'https://ovolos.ai/api/v1/enums' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/enums", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/enums",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "account_types": [
            {
                "value": "checking",
                "label": "Checking",
                "category": "asset"
            },
            {
                "value": "savings",
                "label": "Savings",
                "category": "asset"
            },
            {
                "value": "term_deposit",
                "label": "Term Deposit",
                "category": "asset"
            },
            {
                "value": "cash",
                "label": "Cash",
                "category": "asset"
            },
            {
                "value": "brokerage",
                "label": "Brokerage",
                "category": "asset"
            },
            {
                "value": "retirement",
                "label": "Retirement",
                "category": "asset"
            },
            {
                "value": "discretionary_mandate",
                "label": "Discretionary Mandate",
                "category": "asset"
            },
            {
                "value": "stocks",
                "label": "Stocks",
                "category": "asset"
            },
            {
                "value": "mutual_funds",
                "label": "Mutual Funds",
                "category": "asset"
            },
            {
                "value": "crypto",
                "label": "Crypto",
                "category": "asset"
            },
            {
                "value": "private_company",
                "label": "Private Company",
                "category": "asset"
            },
            {
                "value": "private_fund",
… 83 more lines, trimmed for reading. The committed capture is whole.

The acting portfolio's own category vocabulary — the exact set every category write on this API validates against, each row in the shape POST /api/v1/spending/categories answers with.

• It is the built-in vocabulary plus anything the account holder has added, with their renamed labels applied, so a static list a client holds may be refused.
• Archived categories are listed and flagged: a row already carrying one can still be saved, but do not newly assign one.
• `spending` is whether the category counts toward the spending totals — false for transfers, income and asset purchases — and is how /spending/summary aggregates.
• `meta.portfolio_id` names the books these belong to: the answer changes with X-Portfolio, so do not cache it across them.

Takes no query parameters and no body.

curl 'https://ovolos.ai/api/v1/spending/categories' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/spending/categories", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/spending/categories",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "value": "income",
            "label": "Income",
            "color": "#9fef00",
            "spending": false,
            "archived": false
        },
        {
            "value": "transfer",
            "label": "Transfer",
            "color": "#6f7e97",
            "spending": false,
            "archived": false
        },
        {
            "value": "groceries",
            "label": "Groceries",
            "color": "#2ee6b6",
            "spending": true,
            "archived": false
        },
        {
            "value": "dining",
            "label": "Dining & Takeout",
            "color": "#ffcc5c",
            "spending": true,
            "archived": false
        },
        {
            "value": "transport",
            "label": "Transport",
            "color": "#5cb2ff",
            "spending": true,
            "archived": false
        },
        {
            "value": "housing",
            "label": "Housing",
            "color": "#a98bff",
            "spending": true,
            "archived": false
        },
        {
            "value": "utilities",
            "label": "Bills & Utilities",
            "color": "#5cecff",
            "spending": true,
            "archived": false
        },
        {
            "value": "shopping",
            "label": "Shopping",
            "color": "#ff6ad5",
            "spending": true,
            "archived": false
        },
        {
            "value": "entertainment",
… 123 more lines, trimmed for reading. The committed capture is whole.

The token user, the portfolio this request is acting in, the abilities the token holds, and every portfolio it could act in instead — each with its currency and its account, entity and member counts. Put a row's `portfolio_id` in X-Portfolio to work inside it.

• `counts.accounts` is the size of the books, archived and sold accounts included, so it is allowed to disagree with GET /accounts, which hides both.
• An entity-scoped grant counts only what it reaches.
• `counts.members` is null for a portfolio you do not own — how many people can see somebody's books is theirs to know.

Takes no query parameters and no body.

Assistant equivalent: whoami

curl 'https://ovolos.ai/api/v1/me' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/me", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/me",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "user": {
            "id": 1,
            "name": "Alex Rivera",
            "email": "[email protected]",
            "display_currency": "EUR",
            "push_alerts_enabled": true,
            "daily_digest_email": true
        },
        "acting_portfolio": {
            "portfolio_id": 1,
            "name": "Rivera Household",
            "owner_name": "Alex Rivera",
            "role": "owner",
            "entity_scoped": false,
            "spending_tools": true,
            "ai_tools": true
        },
        "abilities": [
            "profile:read",
            "profile:write",
            "networth:read",
            "accounts:read",
            "accounts:write",
            "holdings:read",
            "holdings:write",
            "spending:read",
            "spending:write",
            "planning:read",
            "planning:write",
            "connections:read",
            "connections:write",
            "feedback:write",
            "portfolios:write"
        ],
        "portfolios": [
            {
                "portfolio_id": 1,
                "name": "Rivera Household",
                "owner_name": null,
                "role": "owner",
                "acting": true,
                "currency": "EUR",
                "counts": {
                    "accounts": 16,
                    "entities": 2,
                    "members": 1
                }
            },
            {
                "portfolio_id": 4,
                "name": "Side Ventures",
                "owner_name": null,
                "role": "owner",
                "acting": false,
                "currency": "EUR",
                "counts": {
                    "accounts": 0,
                    "entities": 1,
… 6 more lines, trimmed for reading. The committed capture is whole.

Update the three settings a token may change about the person holding it: the currency every figure is converted into, whether alerts may reach their phones, and whether they get the emailed daily recap. Send only what is changing.

• It always writes your own row, never the acting portfolio owner's: X-Portfolio changes which books you are reading, not whose settings you are editing.
• `display_currency` accepts null, which is the app's "work it out from the accounts", so null and omitted mean different things here.

Assistant equivalent: set_preferences

curl -X PATCH 'https://ovolos.ai/api/v1/me/preferences' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "display_currency": "GBP"
  }'

const response = await fetch("https://ovolos.ai/api/v1/me/preferences", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "display_currency": "GBP"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/me/preferences",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "display_currency": "GBP",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "display_currency": "GBP",
        "push_alerts_enabled": true,
        "daily_digest_email": true
    },
    "meta": {
        "unchanged": false
    }
}

What your AI has cost this UTC calendar month and whether you can afford another run: spend against your monthly budget, what is left, what is held for runs still going, a breakdown by feature and your last twenty runs.

• Always your own figures. The AI ledger is keyed on a person and carries no portfolio id, so X-Portfolio does not change the answer.
• Amounts are US dollars, never your display currency, and carried to four decimal places because one model call can cost less than a cent — the one exception to this API's two-decimal money rule.
• `meta.billed_work.charged_to_you: false` means a run there spends the portfolio owner's budget, and `would_be_refused` is null because their remaining room is their figure, not yours.
• `typical_run_cost` is what one run of that feature is expected to cost — the size of the reservation it would take, never a total you have spent.
• `ai_tools_granted: false` refuses a run whatever the budget says. Read `meta.billed_work` before starting anything.

Takes no query parameters and no body.

Assistant equivalent: ai_usage

curl 'https://ovolos.ai/api/v1/me/ai-usage' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/me/ai-usage", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/me/ai-usage",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "currency": "USD",
        "month": "2026-06",
        "budget": 10,
        "spent": 0.7125,
        "reserved": 0,
        "committed": 0.7125,
        "remaining": 9.2875,
        "percent_used": 7,
        "unpriced_calls": 0,
        "by_feature": [
            {
                "feature": "valuation_research",
                "label": "AI valuation — research",
                "runs": 1,
                "calls": 1,
                "cost": 0.7123
            },
            {
                "feature": "categorization",
                "label": "Transaction categorization",
                "runs": 1,
                "calls": 1,
                "cost": 0.0002
            }
        ],
        "recent_runs": [
            {
                "label": "Transaction categorization",
                "calls": 1,
                "cost": 0.0002,
                "finished_at": "2026-06-13T07:05:00+00:00"
            },
            {
                "label": "AI valuation — research",
                "calls": 1,
                "cost": 0.7123,
                "finished_at": "2026-06-11T10:24:00+00:00"
            }
        ]
    },
    "meta": {
        "whose_spend": {
            "user_id": 1,
            "name": "Alex Rivera",
            "is_owner_of_acting_portfolio": true
        },
        "scope": "Your own AI spend, on the account you authenticated as. Acting inside another portfolio does not change it: the AI ledger is keyed on a person, not on a set of books, and one person's billing is never reported to another.",
        "period": {
            "start": "2026-06-01T00:00:00+00:00",
            "resets_at": "2026-07-01T00:00:00+00:00",
            "basis": "utc_calendar_month"
        },
        "windows": {
            "budget": "policy",
            "spent": "this_month",
            "reserved": "now",
            "by_feature": "this_month",
            "recent_runs": "all_time"
… 25 more lines, trimmed for reading. The committed capture is whole.

Register a device to receive this user's alerts. It upserts on the token, so re-registering the same phone corrects that row rather than adding a second; `meta.created` separates the two.

• The row belongs to the token user and never to the acting portfolio owner — registering a member's phone against the owner would push the owner's alerts to it.

curl -X POST 'https://ovolos.ai/api/v1/me/push-tokens' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
      "platform": "android"
  }'

const response = await fetch("https://ovolos.ai/api/v1/me/push-tokens", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
      "platform": "android"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/me/push-tokens",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
        "platform": "android",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
        "platform": "android"
    },
    "meta": {
        "created": true
    }
}

Stop sending alerts to one device — the sign-out call, so the next person to hold the phone does not get the last one's alerts. `{token}` is the Expo token string itself, not an id.

• A token that never existed, belongs to somebody else, or has already been pruned as unregistered all answer 404 alike, so treat "gone" as success.

Takes no query parameters and no body.

curl -X DELETE 'https://ovolos.ai/api/v1/me/push-tokens/ExponentPushToken%5Bdocs0000000000000000%5D' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/me/push-tokens/ExponentPushToken%5Bdocs0000000000000000%5D", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/me/push-tokens/ExponentPushToken%5Bdocs0000000000000000%5D",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true
    }
}

Who can see one portfolio you own: the live grants and the invitations still outstanding, each with the person's role, whether their access covers all entities or a named few, and whether they were given the spending tools, the paid AI tools and the daily digest.

• Owner-only, and the portfolio is named in the path rather than taken from X-Portfolio — one merely shared with you answers exactly as one that does not exist.
• `state` is "active" or "pending": a pending invitation is the same record earlier, which is why they are one list.
• It never returns the invite token — that link is the access — nor a revoked grant, nor your own owner row.

Takes no query parameters and no body.

Assistant equivalent: list_portfolio_members

curl 'https://ovolos.ai/api/v1/portfolios/1/members' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/portfolios/1/members", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/portfolios/1/members",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 5,
            "state": "active",
            "email": "[email protected]",
            "name": "Sam Okonkwo",
            "role": {
                "value": "edit",
                "label": "Can edit"
            },
            "all_entities": true,
            "legal_entities": [],
            "scope_summary": "All entities",
            "spending_tools": true,
            "ai_tools": true,
            "daily_digest": false,
            "invited_at": "2026-01-05T10:00:00+00:00",
            "accepted_at": "2026-01-06T11:30:00+00:00"
        }
    ],
    "meta": {
        "portfolio_id": 1,
        "portfolio_name": "Rivera Household",
        "owner_role": "owner",
        "count": 1,
        "active": 1,
        "pending": 0,
        "writes": "Not exposed, on either surface. Inviting, editing, revoking and accepting are a published boundary: sharing a portfolio is a judgement about a person. Do it in Settings → Portfolios."
    }
}

Make a new, empty set of books — its own accounts, entities, budgets and net worth, kept apart from the ones you have. It arrives with your owner membership and a default legal entity.

• Its currency is inherited from your display currency once, at creation, and there is no way to change it afterwards on either surface.
• It does not switch you into it: `meta.acting_portfolio_id` is unchanged, and the next call still needs X-Portfolio to work inside the new one.
• Two of your own cannot share a name, so leaving `name` out twice is a 422 — every unnamed portfolio is created as "Personal". A ceiling on how many one person may own is the other unlisted 422.

Assistant equivalent: create_portfolio

curl -X POST 'https://ovolos.ai/api/v1/portfolios' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/portfolios", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/portfolios",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "portfolio_id": 5,
        "name": "Personal",
        "owner_name": null,
        "role": "owner",
        "acting": false,
        "currency": "EUR",
        "counts": {
            "accounts": 0,
            "entities": 1,
            "members": 0
        }
    },
    "meta": {
        "created_with": {
            "owner_membership": true,
            "default_legal_entity": "Alex Rivera"
        },
        "acting_portfolio_id": 1,
        "next": "Pass portfolio_id 5 in the X-Portfolio header (or the MCP `portfolio` argument) to work inside it."
    }
}

Rename a portfolio you own. A label and nothing else: no account, value, permission or figure moves, and everyone who was in it still is.

• The name is the only field either surface will change: the currency is inherited at creation, and changing it would re-denominate every figure the books ever reported.
• Only your own: one shared with you answers exactly as one that does not exist.

Assistant equivalent: rename_portfolio

curl -X PATCH 'https://ovolos.ai/api/v1/portfolios/4' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "name": "Side Ventures (2026)"
  }'

const response = await fetch("https://ovolos.ai/api/v1/portfolios/4", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "name": "Side Ventures (2026)"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/portfolios/4",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "name": "Side Ventures (2026)",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "portfolio_id": 4,
        "name": "Side Ventures (2026)",
        "owner_name": null,
        "role": "owner",
        "acting": false,
        "currency": "EUR",
        "counts": {
            "accounts": 0,
            "entities": 1,
            "members": 0
        }
    },
    "meta": {
        "unchanged": false
    }
}

Remove a portfolio you own, permanently, once the body carries `confirm_name` matching its exact name. `meta.removed` counts what went with it.

• There is no soft delete and no restore anywhere in Ovolos.
• Refused while the portfolio holds any account — archived and sold ones count — and refused on your last one, so no valuation, transaction or holding is reachable here and `meta.accounts_lost` is always 0.
• Everything else filed there goes silently: legal entities, account groups, custom spending categories, budgets, planned items, alerts, sync reviews, instrument aliases, live grants, invitations, and a bank connection whose accounts were never imported.
• If you delete the portfolio your X-Portfolio names, `meta.was_acting` says so — that header is now dead rather than silently falling back to whatever else you own.

Assistant equivalent: delete_portfolio

curl -X DELETE 'https://ovolos.ai/api/v1/portfolios/4' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "confirm_name": "Side Ventures"
  }'

const response = await fetch("https://ovolos.ai/api/v1/portfolios/4", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "confirm_name": "Side Ventures"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/portfolios/4",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "confirm_name": "Side Ventures",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true,
        "portfolio_id": 4,
        "name": "Side Ventures"
    },
    "meta": {
        "removed": {
            "legal_entities": 1,
            "account_groups": 0,
            "spending_categories": 0,
            "budgets": 0,
            "planned_items": 0,
            "planned_occurrence_overrides": 0,
            "alerts": 0,
            "connections": 0,
            "sync_reviews": 0,
            "instrument_aliases": 0,
            "members": 0,
            "pending_invitations": 0,
            "revoked_grants": 0
        },
        "accounts_lost": 0,
        "was_acting": false,
        "note": "Your acting portfolio is unchanged."
    }
}

Assets, liabilities and net worth with the liquidity split, two allocation breakdowns, a month-end series carrying all three legs, growth over the chosen range as delta, total return and CAGR, and how current the valuations behind the total are.

• `allocation` is by account type and `allocation_by_class` groups those same types — the same money at two grains, so never add them together.
• `pct` is a share of assets, not of net worth: liabilities are nowhere in the denominator.
• `range` scopes everything, not only growth — a 6m call returns a six-month series and a CAGR measured over six months, so figures from two ranges are not comparable.
• `as_of` is the date of the request, not the age of the marks behind it. `valuations` is what says how current the total actually is.
• `valuations.stale_share` and `severe_share` are percentages of assets past their account type's amber and red staleness thresholds; `oldest_stale_as_of` is null when nothing is stale.
• Totals are never adjusted for staleness: an old mark contributes at face value, so a material `severe_share` is a figure to quote with its age, not to correct.

Assistant equivalent: net_worth_overview

curl 'https://ovolos.ai/api/v1/networth/overview' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/networth/overview", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/networth/overview",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "currency": "EUR",
        "range": "1y",
        "as_of": "2026-06-15",
        "valuations": {
            "oldest_stale_as_of": null,
            "stale_share": 0,
            "severe_share": 0,
            "stale_accounts": 0,
            "severe_accounts": 0
        },
        "totals": {
            "assets": 582650,
            "liabilities": 241720,
            "net": 340930,
            "liquid": 121650,
            "basis": "invested",
            "tiers": {
                "cash": 75950,
                "marketable": 45700,
                "illiquid": 436000,
                "locked": 25000
            }
        },
        "series": [
            {
                "date": "2025-06-30",
                "assets": 532100,
                "liabilities": 249700,
                "net": 282400
            },
            {
                "date": "2025-07-31",
                "assets": 532100,
                "liabilities": 249700,
                "net": 282400
            },
            {
                "date": "2025-08-31",
                "assets": 532100,
                "liabilities": 249700,
                "net": 282400
            },
            {
                "date": "2025-09-30",
                "assets": 542450,
                "liabilities": 248050,
                "net": 294400
            },
            {
                "date": "2025-10-31",
                "assets": 542450,
                "liabilities": 248050,
                "net": 294400
            },
            {
                "date": "2025-11-30",
                "assets": 542450,
                "liabilities": 248050,
… 138 more lines, trimmed for reading. The committed capture is whole.

The portfolio's letter on the eighteen-grade scale, plus the weighted risk score, class spread, largest holdings, liquidity split, currency exposure, leverage, volatility, worst drawdown, and a plain-language verdict.

• `grade_scale.grade` is null when the portfolio cannot be rated — `reason` says which fact is missing. `verdict.letter` is the same letter in display form; there is one ladder.
• `score` and `grade_scale.score` are different indices pointing opposite ways: `score` is 1–5 where higher is riskier, `grade_scale.score` is 0–100 where higher is safer.
• `liquidity` and `leverage` count lifestyle assets on both legs — they ask what you could sell to meet what you owe. Every other figure here excludes them.
• `currency_exposure` is a snapshot; `fx_attribution` is a movement, and it covers foreign-currency ASSET accounts only — so it is not the portfolio's total change.
• An empty `accounts` list means no exposure only when `unmeasured` is empty too — anything listed there is in none of the three totals, which then understate. Each account is measured over its own first and last valuation, so there is no single window.
• `volatility` is the swing of the invested book over the last twelve months. Only a newly opened account's starting balance is stripped out — deposits and withdrawals inside accounts you already held read as movement, so a large transfer inflates it.
• Branch on `findings[].key`, never on `title`. The key is stable and permanent; `title` and `detail` are copy and get rewritten.
• `volatility.measurable` and `max_drawdown.measurable` are false when too little of the invested book is marked to market — the figures describe the marks on file, not market prices, and the grade drops those inputs on the same test.

Assistant equivalent: net_worth_risk

curl 'https://ovolos.ai/api/v1/networth/risk' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/networth/risk", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/networth/risk",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "currency": "EUR",
        "as_of": "2026-06-15",
        "has_data": true,
        "score": 1.94,
        "grade_scale": {
            "score": 70.53,
            "grade": "D-",
            "graded": true,
            "label": "D−",
            "word": "Exposed",
            "headline": "The bottom of “coping”. Below here, something needs action.",
            "reason": null,
            "guidance": null,
            "cappedBy": "hazard",
            "cappedDetail": "R3",
            "triggeredBy": null,
            "coveredWeight": 0.78,
            "provisional": false,
            "hex": "#ea580c",
            "on_hex": "#1c1917",
            "shape": "rounded",
            "modifier": -1,
            "window": {
                "months": 26,
                "available_months": 26,
                "from": "2024-04-15",
                "to": "2026-06-15",
                "capped": false,
                "enough_history": true,
                "label": "2 years"
            }
        },
        "band": {
            "value": 2,
            "label": "Low"
        },
        "high_risk_exposure": {
            "value": 12600,
            "pct": 2.2
        },
        "breakdown": [
            {
                "level": 1,
                "label": "Very Low",
                "value": 100950,
                "pct": 17.3
            },
            {
                "level": 2,
                "label": "Low",
                "value": 436000,
                "pct": 74.8
            },
            {
                "level": 3,
                "label": "Moderate",
                "value": 33100,
                "pct": 5.7
… 253 more lines, trimmed for reading. The committed capture is whole.

How net worth has moved: its letter on the eighteen-grade scale, time-weighted CAGR, the organic-growth vs money-added split, top movers, drawdown and recovery, and low/base/high projections over several horizons.

• Projections are estimates, not advice.
• `grade_scale` is measured over the CANONICAL window, never over `range`. A client that assumes the two agree will read a one-year grade off a request it made for three.
• `grade_scale.grade` is null when the portfolio cannot be rated, with a `reason`; `verdict.letter` is the same letter in display form.
• `volatility` is the swing of the invested book. Only a newly opened account's starting balance is stripped out — deposits and withdrawals inside accounts you already held read as movement, so a large transfer inflates it.
• `volatility` is measured over the last twelve months whatever `range` says, and is the same figure /networth/risk answers. `drawdown` is the one here that follows `range`, so the two do not share a window.
• Each projection horizon is compounded from the `cagr` and `annualized_pct` printed in this same body, so `low`, `base` and `high` can be reproduced from it exactly. The base it compounds is the INVESTED net, which is not `growth.current`.
• `growth.organic` is always the trailing `growth.organic_months`, whatever `range` says — the sibling fields beside it are all-time or follow `range`, so it is the odd one and now carries its own window.
• `volatility.measurable` and `drawdown.measurable` are false when too little of the invested book is marked to market for the grade to read the same series. The figures still describe the marks on file; they are not market prices.

Assistant equivalent: net_worth_trajectory

curl 'https://ovolos.ai/api/v1/networth/trajectory' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/networth/trajectory", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/networth/trajectory",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "currency": "EUR",
        "range": "1y",
        "as_of": "2026-06-15",
        "has_history": true,
        "grade_scale": {
            "score": 86.67,
            "grade": "A-",
            "graded": true,
            "label": "A−",
            "word": "Compounding",
            "headline": "Strong overall, with one dimension that is merely fine.",
            "reason": null,
            "guidance": null,
            "cappedBy": null,
            "cappedDetail": null,
            "triggeredBy": null,
            "coveredWeight": 1,
            "provisional": false,
            "hex": "#047857",
            "on_hex": "#ffffff",
            "shape": "rounded",
            "modifier": -1,
            "window": {
                "months": 26,
                "available_months": 26,
                "from": "2024-04-15",
                "to": "2026-06-15",
                "capped": false,
                "enough_history": true,
                "label": "2 years"
            }
        },
        "growth": {
            "current": 340930,
            "delta": 83930,
            "organic": 54030,
            "organic_months": 12,
            "total_pct": 30.7,
            "cagr": 12.9,
            "years": 2.206707734428474
        },
        "organic_split": {
            "total": 58530,
            "contributed": 4500,
            "organic": 54030
        },
        "verdict": {
            "word": "Compounding",
            "letter": "A−",
            "hex": "#047857",
            "headline": "Strong overall, with one dimension that is merely fine.",
            "sentences": [
                "Your net worth is compounding about 12.9% a year — up 30.7% all-time."
            ]
        },
        "top_movers": {
            "months": 12,
            "label": "Jun 2025",
… 152 more lines, trimmed for reading. The committed capture is whole.

Every lifestyle asset — the home you live in, the car you drive, owned for use rather than for return — with what each is worth, what each costs a year, a `balance_sheet` reconciliation, and the debts still stranded against net worth.

• These accounts, and any mortgage linked to one, are excluded from net worth and from every figure derived from it.
• `balance_sheet` is not net worth and is never presented as it: `net` minus `held_for_use` is `net_worth`.
• `cost` and `per_year` are signed, so a negative `per_year` means the asset gained more than it cost.
• `cost` is null where there is nothing to measure from (`cost_unavailable` says which fact is missing), and `count` is how many assets produced a cost — not how many you hold.
• `stranded_debt` lists liabilities nothing links to a lifestyle asset. If one funded an asset here, net worth is falling by that asset's whole value instead of the equity in it — set its `linked_account_id`.

Assistant equivalent: lifestyle_report

curl 'https://ovolos.ai/api/v1/networth/lifestyle' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/networth/lifestyle", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/networth/lifestyle",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "currency": "EUR",
        "cost": {
            "count": 1,
            "per_year": 6112.83,
            "per_month": 509.4
        },
        "assets": [
            {
                "id": 10,
                "name": "Family Estate Car",
                "type": {
                    "value": "vehicle",
                    "label": "Vehicle"
                },
                "value": 29000,
                "is_sold": false,
                "sold_at": null,
                "cost": {
                    "basis": 37000,
                    "basis_source": "valuation",
                    "basis_date": "2024-03-31",
                    "current": 29000,
                    "depreciation": 8000,
                    "running": 830,
                    "total": 8830,
                    "years": 2.21,
                    "per_year": 6112.83,
                    "per_month": 509.4,
                    "appreciating": false
                },
                "cost_unavailable": null
            }
        ],
        "debts": [],
        "totals": {
            "value": 29000,
            "debt": 0,
            "equity": 29000
        },
        "stranded_debt": [
            {
                "id": 12,
                "name": "Kifissia Mortgage",
                "type": {
                    "value": "mortgage",
                    "label": "Mortgage"
                },
                "value": 239800
            }
        ],
        "balance_sheet": {
            "currency": "EUR",
            "assets": 611650,
            "liabilities": 241720,
            "net": 369930,
            "held_for_use": 29000,
            "net_worth": 340930,
            "note": "A balance-sheet total across everything you own, NOT your net worth. It includes held_for_use — assets kept for use rather than return, net of any debt funding them — which net_worth deliberately leaves out along with every figure derived from it. net minus held_for_use is net_worth."
… 7 more lines, trimmed for reading. The committed capture is whole.

One asset-class sleeve in depth: the class summary, per-account composition, the lifestyle assets listed beside it, a 12-month value history, the contribution-stripped organic return, and class-specific detail — property equity and rental book, the token/chain split, private-equity `nav_steps`.

• `{class}` is `real-estate`, `investments`, `crypto`, `vehicles`, `watches`, `private-equity` or `cash-savings` — the asset-class slugs from GET /enums. Anything else is a 404.
• `composition` is the invested book and sums to `summary.value`. `held_for_use_assets` lists the class's lifestyle accounts separately — `id`, `name`, `icon`, `institution`, `value`, a null `pct` and `is_lifestyle` true — and they are in no figure here.
• `held_for_use_assets` is asset value, gross. `balance_sheet.held_for_use` on /networth/lifestyle is the portfolio-wide figure net of the debt funding it, so a house appears here at full value and there minus its mortgage.
• `has_data` describes the invested book alone. A class holding nothing but lifestyle accounts answers false with `held_for_use_assets` populated — read the array before concluding the class is empty.
• `marks_freshness` is the only thing on this API that says a hand-entered figure has gone stale — read it before restating what a private company is worth.
• On `real-estate`, `rentals.rows[].cashYieldOnEquity` divides cash flow after debt service by CURRENT equity. Never quote it as cash-on-cash: that is measured against the cash put in at purchase, which is not recorded. Null without a payment on file.
• `appreciation.blendedCagr` is the rate that reproduces the book — the r solving Σ(purchase × (1+r)^years) = Σ(current) — not the average of `rows[].cagr`. Read `covered` and `total` beside it: a property with no purchase date is in `rows`, not in the rate.

Assistant equivalent: position_by_class

curl 'https://ovolos.ai/api/v1/networth/positions/cash-savings' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/networth/positions/cash-savings", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/networth/positions/cash-savings",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "currency": "EUR",
        "class": {
            "slug": "cash-savings",
            "group": "Cash & savings",
            "label": "Cash & Savings",
            "icon": "piggy-bank"
        },
        "has_data": true,
        "summary": {
            "value": 100950,
            "assets_share": 17.3,
            "count": 4,
            "delta_12m": 4350,
            "delta_12m_pct": 4.5
        },
        "composition": [
            {
                "id": 2,
                "name": "Rainy Day Savings",
                "icon": "piggy-bank",
                "institution": "Northbank",
                "value": 40600,
                "pct": 40.2
            },
            {
                "id": 1,
                "name": "Everyday Current Account",
                "icon": "wallet",
                "institution": "Northbank",
                "value": 26750,
                "pct": 26.5
            },
            {
                "id": 3,
                "name": "Two-Year Fixed Bond",
                "icon": "timer",
                "institution": "Northbank",
                "value": 25000,
                "pct": 24.8
            },
            {
                "id": 14,
                "name": "Northbank Joint Account",
                "icon": "wallet",
                "institution": "Northbank",
                "value": 8600,
                "pct": 8.5
            }
        ],
        "held_for_use_assets": [],
        "history": [
            {
                "label": "Jun 2025",
                "date": "2025-06-30",
                "value": 96600
            },
            {
                "label": "Jul 2025",
… 107 more lines, trimmed for reading. The committed capture is whole.

Every account with id, type, institution, current value, classification, sync health and staleness, plus a `loan` block on anything that borrows. `meta.balance_sheet` beneath the list totals assets, liabilities and net.

• Archived and sold accounts are excluded unless asked for, and then arrive mixed into the same list with signed values — read `is_archived` and `is_sold` before summing.
• `staleness` is measured against a threshold that differs by account type, so "too old" is not one number.
• The `loan` figures are in the account's own currency, never the display currency: a payment is a sum the lender takes in the currency of the loan.
• Every loan term is independently null, and a null `interest_rate` means nobody recorded one rather than that the borrowing is free.
• `meta.balance_sheet` is not net worth: it covers every active account rather than the filtered page, it includes accounts marked `is_lifestyle`, and `net` minus `held_for_use` is `net_worth`.

Assistant equivalent: list_accounts

curl 'https://ovolos.ai/api/v1/accounts' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 6,
            "name": "Cold Storage Wallet",
            "institution": null,
            "type": {
                "value": "crypto",
                "label": "Crypto",
                "group": "Crypto"
            },
            "category": "asset",
            "group": null,
            "legal_entity": {
                "id": 1,
                "name": "Alex Rivera",
                "kind": "personal",
                "is_default": true
            },
            "currency": "USD",
            "value": {
                "amount": 6200,
                "signed": 6200,
                "currency": "EUR"
            },
            "ownership_pct": 100,
            "liquidity": "marketable",
            "risk_level": 5,
            "notes": null,
            "account_group_id": null,
            "linked_account_id": null,
            "is_lifestyle": false,
            "is_linked": false,
            "sync_health": null,
            "last_valued_on": "2026-05-31",
            "is_archived": false,
            "archived_at": null,
            "is_sold": false,
            "sold_at": null,
            "staleness": {
                "stale": false,
                "severe": false,
                "label": null,
                "updates_automatically": false,
                "stale_after_days": 30,
                "severe_after_days": 90
            },
            "loan": null,
            "updated_at": "2026-06-15T12:00:00+00:00",
            "ai_valuation": null
        },
        {
            "id": 5,
            "name": "Direct Equities",
            "institution": null,
            "type": {
                "value": "stocks",
                "label": "Stocks",
                "group": "Investments"
            },
… 669 more lines, trimmed for reading. The committed capture is whole.

One account: its value, a valuation history window, and any holdings it contains. The account block is the same shape the list returns.

• Archived and sold accounts resolve here, since the list can hand you their ids.

Assistant equivalent: account_details

curl 'https://ovolos.ai/api/v1/accounts/1' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/1", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/1",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 1,
        "name": "Everyday Current Account",
        "institution": "Northbank",
        "type": {
            "value": "checking",
            "label": "Checking",
            "group": "Cash & savings"
        },
        "category": "asset",
        "group": {
            "id": 1,
            "name": "Everyday banking"
        },
        "legal_entity": {
            "id": 1,
            "name": "Alex Rivera",
            "kind": "personal",
            "is_default": true
        },
        "currency": "EUR",
        "value": {
            "amount": 26750,
            "signed": 26750,
            "currency": "EUR"
        },
        "ownership_pct": 100,
        "liquidity": "cash",
        "risk_level": 1,
        "notes": "The account salary lands in.",
        "account_group_id": 1,
        "linked_account_id": null,
        "is_lifestyle": false,
        "is_linked": false,
        "sync_health": null,
        "last_valued_on": "2026-06-14",
        "is_archived": false,
        "archived_at": null,
        "is_sold": false,
        "sold_at": null,
        "staleness": {
            "stale": false,
            "severe": false,
            "label": null,
            "updates_automatically": false,
            "stale_after_days": 30,
            "severe_after_days": 90
        },
        "loan": null,
        "updated_at": "2026-06-15T12:00:00+00:00",
        "ai_valuation": null,
        "valuations": [
            {
                "date": "2025-09-30",
                "value": 24700,
                "value_display": 24700
            },
            {
                "date": "2025-12-31",
… 31 more lines, trimmed for reading. The committed capture is whole.

Create an account: a current or savings account, a brokerage, a property, a vehicle, a credit card, a loan or a mortgage. Send `opening_value` with its `as_of` to seed the history from that date; leave it out and the account exists at zero until the first valuation lands.

• The type decides the sign — a liability is subtracted from net worth, every other type added — and fixes the default liquidity tier, risk level and accepted `details` keys.
• An account made here is manual: connected to no bank, syncing nothing, worth exactly what is recorded against it.
• A retry that does not carry the original Idempotency-Key is a second account, and a second copy of one mortgage counts the same debt twice.

What this accepts depends on the account type: checking, savings, term_deposit, cash, brokerage, retirement, discretionary_mandate, stocks, mutual_funds, crypto, private_company, private_fund, real_estate, vehicle, watch, other_asset, credit_card, loan, mortgage, other_liability. Fields marked above with the types they belong to are refused on the others.

Assistant equivalent: create_account

curl -X POST 'https://ovolos.ai/api/v1/accounts' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "name": "Glyfada Maisonette",
      "type": "real_estate",
      "currency": "EUR",
      "ownership_percentage": 50
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "name": "Glyfada Maisonette",
      "type": "real_estate",
      "currency": "EUR",
      "ownership_percentage": 50
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "name": "Glyfada Maisonette",
        "type": "real_estate",
        "currency": "EUR",
        "ownership_percentage": 50,
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 17,
        "name": "Glyfada Maisonette",
        "institution": null,
        "type": {
            "value": "real_estate",
            "label": "Real Estate",
            "group": "Real estate"
        },
        "category": "asset",
        "group": null,
        "legal_entity": {
            "id": 1,
            "name": "Alex Rivera",
            "kind": "personal",
            "is_default": true
        },
        "currency": "EUR",
        "value": {
            "amount": 0,
            "signed": 0,
            "currency": "EUR"
        },
        "ownership_pct": 50,
        "liquidity": "illiquid",
        "risk_level": 2,
        "notes": null,
        "account_group_id": null,
        "linked_account_id": null,
        "is_lifestyle": false,
        "is_linked": false,
        "sync_health": null,
        "last_valued_on": null,
        "is_archived": false,
        "archived_at": null,
        "is_sold": false,
        "sold_at": null,
        "staleness": {
            "stale": true,
            "severe": true,
            "label": "never",
            "updates_automatically": false,
            "stale_after_days": 180,
            "severe_after_days": 365
        },
        "loan": null,
        "updated_at": "2026-06-15T12:00:00+00:00",
        "ai_valuation": null
    },
    "meta": {
        "currency": "EUR"
    }
}

Edit an account: its name, institution, type, ownership share, liquidity and risk overrides, the group and legal entity it is filed under, the loan it is linked to, and its type-specific `details`. Absent fields keep their stored values.

• Changing the type can move the account from the asset side of net worth to the liability side, flipping the sign of its balance in the total and in the allocation.
• Changing the currency redenominates rather than converts: a 200,000 EUR flat becomes a 200,000 USD flat. A provider-linked account does not accept `currency` at all.
• `details` is written whole, so every key left out of it is cleared.
• `ownership_percentage` rescales what the account contributes to every total.
• This is not how a balance is corrected — what an account is worth is a valuation.

What this accepts depends on the account type: checking, savings, term_deposit, cash, brokerage, retirement, discretionary_mandate, stocks, mutual_funds, crypto, private_company, private_fund, real_estate, vehicle, watch, other_asset, credit_card, loan, mortgage, other_liability. Fields marked above with the types they belong to are refused on the others.

It also depends on whether the account is provider-linked, which is a second axis rather than another type: a linked account of any type refuses the fields its provider owns, marked above.

Assistant equivalent: update_account

curl -X PATCH 'https://ovolos.ai/api/v1/accounts/9' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -H 'If-Match: THE_ETAG_FROM_YOUR_LAST_READ' \
  -d '{
      "name": "Kifissia Apartment (Flat 4)"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/9", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
  },
  body: JSON.stringify({
      "name": "Kifissia Apartment (Flat 4)"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/accounts/9",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
        "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
    },
    json={
        "name": "Kifissia Apartment (Flat 4)",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 9,
        "name": "Kifissia Apartment (Flat 4)",
        "institution": null,
        "type": {
            "value": "real_estate",
            "label": "Real Estate",
            "group": "Real estate"
        },
        "category": "asset",
        "group": null,
        "legal_entity": {
            "id": 5,
            "name": "Rivera Family Trust",
            "kind": "trust",
            "is_default": false
        },
        "currency": "EUR",
        "value": {
            "amount": 436000,
            "signed": 436000,
            "currency": "EUR"
        },
        "ownership_pct": 100,
        "liquidity": "illiquid",
        "risk_level": 2,
        "notes": null,
        "account_group_id": null,
        "linked_account_id": 12,
        "is_lifestyle": false,
        "is_linked": false,
        "sync_health": null,
        "last_valued_on": "2026-05-31",
        "is_archived": false,
        "archived_at": null,
        "is_sold": false,
        "sold_at": null,
        "staleness": {
            "stale": false,
            "severe": false,
            "label": null,
            "updates_automatically": false,
            "stale_after_days": 180,
            "severe_after_days": 365
        },
        "loan": null,
        "updated_at": "2026-06-15T12:00:00+00:00",
        "ai_valuation": null
    },
    "meta": {
        "currency": "EUR"
    }
}

Hide an account. It deletes nothing — the valuation history, the holdings and the transactions all survive and it can be brought back — but the balance leaves net worth at once, the account drops out of the totals, the allocation and the list, and a provider-linked one stops syncing.

• To the person reading their net worth this is indistinguishable from deletion, and the direction is not always the obvious one: hiding a mortgage makes them look richer.
• The body must be empty, `cascade` included, so a call that already reads as removal cannot answer 200 to a caller who believes the holdings went with it.

Takes no query parameters and no body.

Assistant equivalent: hide_account

curl -X POST 'https://ovolos.ai/api/v1/accounts/5/archive' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/5/archive", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/5/archive",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 5,
        "name": "Direct Equities",
        "institution": null,
        "type": {
            "value": "stocks",
            "label": "Stocks",
            "group": "Investments"
        },
        "category": "asset",
        "group": null,
        "legal_entity": {
            "id": 1,
            "name": "Alex Rivera",
            "kind": "personal",
            "is_default": true
        },
        "currency": "USD",
        "value": {
            "amount": 12800,
            "signed": 12800,
            "currency": "USD"
        },
        "ownership_pct": 100,
        "liquidity": "marketable",
        "risk_level": 4,
        "notes": null,
        "account_group_id": null,
        "linked_account_id": null,
        "is_lifestyle": false,
        "is_linked": false,
        "sync_health": null,
        "last_valued_on": "2026-05-31",
        "is_archived": true,
        "archived_at": "2026-06-15T12:00:00+00:00",
        "is_sold": false,
        "sold_at": null,
        "staleness": {
            "stale": false,
            "severe": false,
            "label": null,
            "updates_automatically": false,
            "stale_after_days": 30,
            "severe_after_days": 90
        },
        "loan": null,
        "updated_at": "2026-06-15T12:00:00+00:00",
        "ai_valuation": null
    },
    "meta": {
        "unchanged": false
    }
}

Bring a hidden account back: its balance rejoins net worth and it reappears in the list, with everything it held.

• It deliberately fires no provider sync, so a linked account rejoins the daily schedule and its balance can lag until then.

Takes no query parameters and no body.

Assistant equivalent: hide_account

curl -X POST 'https://ovolos.ai/api/v1/accounts/15/restore' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/15/restore", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/15/restore",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 15,
        "name": "Closed Student Account",
        "institution": null,
        "type": {
            "value": "savings",
            "label": "Savings",
            "group": "Cash & savings"
        },
        "category": "asset",
        "group": null,
        "legal_entity": {
            "id": 1,
            "name": "Alex Rivera",
            "kind": "personal",
            "is_default": true
        },
        "currency": "EUR",
        "value": {
            "amount": 2400,
            "signed": 2400,
            "currency": "USD"
        },
        "ownership_pct": 100,
        "liquidity": "cash",
        "risk_level": 1,
        "notes": null,
        "account_group_id": null,
        "linked_account_id": null,
        "is_lifestyle": false,
        "is_linked": false,
        "sync_health": null,
        "last_valued_on": "2026-05-31",
        "is_archived": false,
        "archived_at": null,
        "is_sold": false,
        "sold_at": null,
        "staleness": {
            "stale": false,
            "severe": false,
            "label": null,
            "updates_automatically": false,
            "stale_after_days": 30,
            "severe_after_days": 90
        },
        "loan": null,
        "updated_at": "2026-06-15T12:00:00+00:00",
        "ai_valuation": null
    },
    "meta": {
        "unchanged": false
    }
}

A twelve-month amortisation for a loan or a mortgage: each month's payment split into interest and principal, what is left at the end of the year, and the month the debt clears at the current payment.

• A forecast, not a statement (`meta.estimate`): it assumes today's balance, rate and payment hold, while the account's real balance follows the principal recorded against the loan.
• Money is in the loan's own currency and is never converted — a schedule in another currency matches no statement the lender sends.
• `projected_payoff_month` is null when the payment cannot out-pace the interest (`growing: true`), and when clearing the debt would take over a century.
• It is not `payoff_date`, which is the date the user recorded and sits in `meta.terms`; `paid_off_on` is only the month inside the charted year the balance reaches zero.
• A loan with terms but no recorded balance answers 200 with `data: null` and `meta.reason` "no_balance" — a missing valuation, not a bad call.

Takes no query parameters and no body.

Refuses ?currency= with 422 unexpected_field. It is a decision, not an omission.

Assistant equivalent: loan_projection

curl 'https://ovolos.ai/api/v1/accounts/12/loan-projection' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/12/loan-projection", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/12/loan-projection",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "months": [
            {
                "month": "2026-07",
                "interest": 649.46,
                "principal": 770.54,
                "balance": 239029.46
            },
            {
                "month": "2026-08",
                "interest": 647.37,
                "principal": 772.63,
                "balance": 238256.83
            },
            {
                "month": "2026-09",
                "interest": 645.28,
                "principal": 774.72,
                "balance": 237482.11
            },
            {
                "month": "2026-10",
                "interest": 643.18,
                "principal": 776.82,
                "balance": 236705.29
            },
            {
                "month": "2026-11",
                "interest": 641.08,
                "principal": 778.92,
                "balance": 235926.37
            },
            {
                "month": "2026-12",
                "interest": 638.97,
                "principal": 781.03,
                "balance": 235145.33
            },
            {
                "month": "2027-01",
                "interest": 636.85,
                "principal": 783.15,
                "balance": 234362.19
            },
            {
                "month": "2027-02",
                "interest": 634.73,
                "principal": 785.27,
                "balance": 233576.92
            },
            {
                "month": "2027-03",
                "interest": 632.6,
                "principal": 787.4,
                "balance": 232789.52
            },
            {
                "month": "2027-04",
                "interest": 630.47,
… 44 more lines, trimmed for reading. The committed capture is whole.

What one physical asset has cost to own, in three independently-nullable blocks: `basis` (what was paid), `running` (everything attributed to keeping it) and `ownership` (the two together). Property, vehicles, watches and other physical assets only.

• `basis.source` "valuation" means the price was estimated from the earliest value on record, which understates the loss.
• Negative depreciation means the asset gained value, which correctly reduces what it has cost to own.
• `ownership.per_year` is each half annualised over its own window and then added, deliberately not `total` divided by `years`.
• `running` excludes the purchase itself by category, so the two halves never double-count.
• `ownership` is null with `ownership_unavailable` naming the check that fired; on a sold asset, reading its current value as 0 would report a total loss of the whole purchase price.

Assistant equivalent: cost_of_ownership

curl 'https://ovolos.ai/api/v1/accounts/10/cost-of-ownership' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/10/cost-of-ownership", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/10/cost-of-ownership",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "basis": {
            "amount": 37000,
            "date": "2024-03-31",
            "source": "valuation"
        },
        "running": {
            "count": 2,
            "total": 830,
            "last_12m": 830,
            "annual": 2490,
            "since": "2026-04-19",
            "per_year": [
                {
                    "year": 2026,
                    "total": 830
                }
            ]
        },
        "ownership": {
            "basis": 37000,
            "basis_source": "valuation",
            "basis_date": "2024-03-31",
            "current": 29000,
            "depreciation": 8000,
            "running": 830,
            "total": 8830,
            "years": 2.21,
            "per_year": 6112.83,
            "per_month": 509.4,
            "appreciating": false
        },
        "ownership_unavailable": null
    },
    "meta": {
        "account_id": 10,
        "name": "Family Estate Car",
        "type": {
            "value": "vehicle",
            "label": "Vehicle"
        },
        "is_lifestyle": true,
        "is_sold": false,
        "sold_at": null,
        "currency": "EUR",
        "note": "Depreciation is a fall in recorded value, not a realised loss. A negative one means the asset has gained and has therefore cost less than nothing to own."
    }
}

For an account held in a currency other than the one you report in, how much of its change was the asset moving and how much the exchange rate. `fx_component` is the rate applied to the stake held at the window's start; `fx_pct` is null when the change is near zero.

• Everything except `native_change` is in the display currency; `native_change` is the only figure in the account's own.
• `non_fx_component` plus `fx_component` equals `display_change` to the cent by construction, so do not recompute the parts from the percentage.
• All legs are signed alike: a positive `display_change` beside a negative `fx_component` is a real gain held back by the rate.
• The window is `meta.start_on` to `meta.end_on` — the account's first and last valuation, not today and not when it was opened.
• A 200 with `data: null` is a real answer, and `meta.unavailable` names which of `same_currency`, `insufficient_history` or `no_rate` produced it. None is a zero.

Assistant equivalent: fx_attribution

curl 'https://ovolos.ai/api/v1/accounts/4/fx-attribution' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/4/fx-attribution", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/4/fx-attribution",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "currency": "USD",
        "display_currency": "EUR",
        "native_change": 20200,
        "display_change": 10100,
        "non_fx_component": 10100,
        "fx_component": 0,
        "fx_pct": 0,
        "start_on": "2024-03-31",
        "end_on": "2026-05-31"
    },
    "meta": {
        "account_id": 4,
        "name": "Global Brokerage",
        "type": {
            "value": "brokerage",
            "label": "Brokerage"
        },
        "currency": "USD",
        "display_currency": "EUR",
        "start_on": "2024-03-31",
        "end_on": "2026-05-31",
        "unavailable": null,
        "note": "non_fx_component and fx_component are both in display_currency and add up to display_change exactly. native_change is the only figure in the account's own currency. fx_component is what the rate did to the stake held at the start of the window, so an account bought part-way through the window has a small one by construction."
    }
}

The groups accounts are filed under — the tabs on the Accounts page — each with how many accounts it holds and what they add up to.

• The totals include anything marked `is_lifestyle` and leave out archived and sold accounts, so they are never net worth.

Assistant equivalent: list_account_groups

curl 'https://ovolos.ai/api/v1/account-groups' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/account-groups", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/account-groups",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 1,
            "name": "Everyday banking",
            "position": 1,
            "accounts_count": 3,
            "totals": {
                "assets": 67350,
                "liabilities": 1920,
                "net": 65430,
                "currency": "EUR"
            }
        }
    ],
    "meta": {
        "currency": "EUR",
        "count": 1
    }
}

Create a group. It is appended to the end of the tab order unless you place it.

• A retry that does not carry the original Idempotency-Key is a second group with the same name.

Assistant equivalent: create_account_group

curl -X POST 'https://ovolos.ai/api/v1/account-groups' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "name": "Long-term holdings"
  }'

const response = await fetch("https://ovolos.ai/api/v1/account-groups", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "name": "Long-term holdings"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/account-groups",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "name": "Long-term holdings",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 2,
        "name": "Long-term holdings",
        "position": 2
    }
}

Rename a group or move it in the tab order. Send only what changes.

Assistant equivalent: update_account_group

curl -X PATCH 'https://ovolos.ai/api/v1/account-groups/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/account-groups/1", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/account-groups/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 1,
        "name": "Everyday banking",
        "position": 1
    },
    "meta": {
        "unchanged": true
    }
}

Delete a group. It removes the label only: every account filed in it survives and becomes ungrouped, `accounts_ungrouped` says how many, and no figure moves.

Takes no query parameters and no body.

Assistant equivalent: delete_account_group

curl -X DELETE 'https://ovolos.ai/api/v1/account-groups/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/account-groups/1", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/account-groups/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true
    },
    "meta": {
        "accounts_ungrouped": 3
    }
}

Position-level holdings for one account: units, cost basis and unrealized gain where known, plus native and display value. Every row carries an id and a `kind`.

• `kind` is `instrument`, `private_company` or `private_fund`, and says which family of writes addresses that row.
• A private position has no symbol because nothing quotes it, so read `kind` rather than inferring the type from that null.

Assistant equivalent: list_holdings

curl 'https://ovolos.ai/api/v1/accounts/4/holdings' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/4/holdings", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/4/holdings",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 1,
            "kind": "instrument",
            "name": "Apple Inc",
            "symbol": "AAPL.US",
            "units": 120,
            "currency": "USD",
            "cost_basis": 17784,
            "value": 25500,
            "unrealized_gain": 7716,
            "cost_basis_display": 8892,
            "value_display": 12750,
            "unrealized_gain_display": 3858
        },
        {
            "id": 2,
            "kind": "instrument",
            "name": "Privateer Industries",
            "symbol": "PRIVX.US",
            "units": 400,
            "currency": "USD",
            "cost_basis": 4800,
            "value": null,
            "unrealized_gain": null,
            "cost_basis_display": 2400,
            "value_display": null,
            "unrealized_gain_display": null
        }
    ],
    "meta": {
        "currency": "EUR",
        "count": 2
    }
}

The instruments this app already knows, matched against free text — a symbol, an ISIN, part of a name — each with the id the attach endpoint takes. Exact symbol and ISIN matches come first, then partial ones, 20 rows in total and no paging.

• A read: it never creates an instrument, and `meta.creates_instruments` is false on every response.
• `priced_nightly: false` means no schedule keeps that row priced: the wallet sync mints those and prices them at 05:15 UTC only while a synced wallet still reports the token, so read `last_priced_on` rather than treating `last_close` as current.

Assistant equivalent: search_instruments

curl 'https://ovolos.ai/api/v1/instruments?q=apple' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/instruments?q=apple", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/instruments?q=apple",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 1,
            "symbol": "AAPL.US",
            "isin": "US0378331005",
            "name": "Apple Inc",
            "currency": "USD",
            "type": "Common Stock",
            "exchange": "US",
            "last_close": 212.5,
            "last_priced_on": "2026-06-12",
            "priced_nightly": true
        }
    ],
    "meta": {
        "count": 1,
        "query": "apple",
        "creates_instruments": false,
        "note": null
    }
}

Open a position: attach an instrument the app already knows, and record the buy that opens it. It creates two rows, and there is no way to create an empty position.

• `instrument_id` only, never a symbol: nothing here creates an instrument, so an id that does not exist is a 422 rather than a row that gets made.
• A retry that does not carry the original Idempotency-Key is a second position; 409 `duplicate_holding` when the account already holds that instrument.
• It pulls no price history — that fetch is billed per instrument per request — so `meta.history_backfilled` is always false and every date before today keeps the shape it had.
• A purchase dated earlier only marks the account (`meta.history_rebuild_queued`); the 05:50 UTC nightly rebuild redraws the curve, and the 04:30 UTC price pull values the current day alone.
• An instrument Ovolos has never priced records nothing: `meta.priced` and `meta.revalued` are false, and the figure does not move until a close is stored.
• `meta.priced_nightly: false` is usually not that case — a wallet-sourced instrument has a close, so the figure moves off a price that may be weeks old and about to freeze.

Assistant equivalent: add_holding

curl -X POST 'https://ovolos.ai/api/v1/accounts/5/holdings' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "instrument_id": 1,
      "units": 40,
      "traded_on": "2026-06-09"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/5/holdings", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "instrument_id": 1,
      "units": 40,
      "traded_on": "2026-06-09"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/5/holdings",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "instrument_id": 1,
        "units": 40,
        "traded_on": "2026-06-09",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "holding": {
            "id": 3,
            "account_id": 5,
            "instrument_id": 1,
            "symbol": "AAPL.US",
            "name": "Apple Inc",
            "label": null,
            "currency": "USD",
            "units": 40,
            "cost_basis": null,
            "opened_on": "2026-06-09"
        },
        "trade": {
            "id": 3,
            "type": "buy",
            "units": 40,
            "price": null,
            "amount": null,
            "traded_on": "2026-06-09"
        }
    },
    "meta": {
        "duplicate_of": null,
        "priced": true,
        "priced_nightly": true,
        "revalued": true,
        "value_before": 12800,
        "value_after": 8500,
        "history_backfilled": false,
        "history_rebuild_queued": true,
        "note": "This endpoint does not pull price history — that call is billed per instrument, per request, so a holdings:write token cannot spend it, and meta.history_backfilled is false because nothing was fetched by THIS request. A write dated before today marks the account instead, and the nightly history rebuild at 05:50 UTC fetches what it needs and redraws the curve from the ledger — once per account per night, however many times you write to it. meta.history_rebuild_queued says whether that happened. Until it runs, the account's value on dates BEFORE today still reflects the position not existing: the 04:30 UTC price pull records the day's close and re-values that day alone. Saving the holding in the Ovolos app rebuilds the curve on the spot if it cannot wait for the night."
    }
}

Append a buy or a sell to a position's ledger. The position is reprojected from the whole ledger, so its units and its average-cost basis both move, and the account is revalued from stored prices.

• Units are a projection and cannot be written directly, here or anywhere: they move by trading or not at all.
• A sale is checked against the lowest running balance from its trade date onwards, so a backdated sell that would leave the ledger negative later is refused rather than clamped.
• A retry that does not carry the original Idempotency-Key is a second purchase.
• A backdated trade changes the units held on every day since and re-values none of them; the 05:50 UTC nightly rebuild redraws those dates.

Assistant equivalent: record_trade

curl -X POST 'https://ovolos.ai/api/v1/accounts/4/holdings/1/trades' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "type": "buy",
      "units": 15,
      "traded_on": "2026-06-10"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/4/holdings/1/trades", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "type": "buy",
      "units": 15,
      "traded_on": "2026-06-10"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/4/holdings/1/trades",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "type": "buy",
        "units": 15,
        "traded_on": "2026-06-10",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "trade": {
            "id": 3,
            "type": "buy",
            "units": 15,
            "price": null,
            "amount": null,
            "traded_on": "2026-06-10"
        },
        "holding": {
            "id": 1,
            "account_id": 4,
            "instrument_id": 1,
            "symbol": "AAPL.US",
            "name": "Apple Inc",
            "label": null,
            "currency": "USD",
            "units": 135,
            "cost_basis": 17784,
            "opened_on": "2024-02-09"
        }
    },
    "meta": {
        "history_rebuild_queued": true
    }
}

Relabel a position — the user's own name for it, and nothing else.

• The label is an override, so one that only restates the instrument's name is stored as null.
• The instrument underneath is shared with every other portfolio holding the symbol, and is not yours to rename.

Assistant equivalent: rename_holding

curl -X PATCH 'https://ovolos.ai/api/v1/accounts/4/holdings/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -H 'If-Match: THE_ETAG_FROM_YOUR_LAST_READ' \
  -d '{
      "name": "Apple — core position"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/4/holdings/1", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
  },
  body: JSON.stringify({
      "name": "Apple — core position"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/accounts/4/holdings/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
        "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
    },
    json={
        "name": "Apple — core position",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "holding": {
            "id": 1,
            "account_id": 4,
            "instrument_id": 1,
            "symbol": "AAPL.US",
            "name": "Apple — core position",
            "label": "Apple — core position",
            "currency": "USD",
            "units": 120,
            "cost_basis": 17784,
            "opened_on": "2024-02-09"
        }
    },
    "meta": {
        "unchanged": false
    }
}

The changes a bank or broker sync wants to make to your positions and will not make on its own — a drifted unit count, a position the feed stopped reporting, a security it could not identify — each with the sentence the app shows in `question`, plus `approvable` and `approve_refusal`.

• Read it before trusting any holdings figure from a synced account: a pending review means Ovolos and the broker disagree about that position, and nothing else on this API says so.
• Pending only — an applied or dismissed review is a decision already taken, and there is no history endpoint.

Takes no query parameters and no body.

Assistant equivalent: sync_reviews

curl 'https://ovolos.ai/api/v1/sync-reviews' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/sync-reviews", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/sync-reviews",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 1,
            "type": "adjust_units",
            "status": "pending",
            "account_id": 4,
            "account_name": "Global Brokerage",
            "connection_id": 1,
            "provider": "lunchflow",
            "provider_name": "Lunch Flow",
            "question": "Lunch Flow reports 132 units of Apple Inc — you have 120. Approve to adjust?",
            "symbol": "AAPL.US",
            "name": "Apple Inc",
            "holding_id": 1,
            "current_units": 120,
            "provider_units": 132,
            "approvable": true,
            "approve_refusal": null,
            "expected_units": 132,
            "account_positions": null,
            "siblings_queued_to_close": null,
            "created_at": "2026-06-15T12:00:00+00:00"
        }
    ],
    "meta": {
        "count": 1,
        "by_type": {
            "adjust_units": 1,
            "close_holding": 0,
            "unmatched_instrument": 0
        },
        "approvable": 1,
        "note": "Approving is not a status change: it appends a trade to the position's ledger at today's close, reprojects its units and average-cost basis, and revalues the account — so net worth moves immediately and every unrealised-gain figure after that date is recomputed. No surface can delete a holding transaction, so an approval cannot be undone here. Rows with approvable false say why in approve_refusal."
    }
}

Apply one pending review. Not a status change: it appends a trade dated today at today's close, reprojects the position's units and its average-cost basis from the whole ledger, and revalues the account.

• Net worth moves immediately, and every unrealized-gain figure after that date is recomputed.
• There is no delete for a holding transaction on any surface, so this cannot be undone through the API at all.
• `expected_units` confirms the figure rather than choosing it — the provider's own is written either way — and a mismatch is 409 `sync_review_figures_moved`, the next sync having rewritten the review.
• `account_positions` and `siblings_queued_to_close` are on every row, so you can judge the empty-feed case that 409 `sync_review_feed_suspect` refuses.

Assistant equivalent: approve_sync_review

curl -X POST 'https://ovolos.ai/api/v1/sync-reviews/1/approve' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "expected_units": 132
  }'

const response = await fetch("https://ovolos.ai/api/v1/sync-reviews/1/approve", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "expected_units": 132
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/sync-reviews/1/approve",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "expected_units": 132,
    },
)

print(response.status_code, response.text)

{
    "data": {
        "review": {
            "id": 1,
            "type": "adjust_units",
            "status": "applied",
            "account_id": 4,
            "account_name": "Global Brokerage",
            "connection_id": 1,
            "provider": "lunchflow",
            "provider_name": "Lunch Flow",
            "question": "Lunch Flow reports 132 units of Apple Inc — you have 120. Approve to adjust?",
            "symbol": "AAPL.US",
            "name": "Apple Inc",
            "holding_id": 1,
            "current_units": 132,
            "provider_units": 132,
            "approvable": false,
            "approve_refusal": "That review is already applied and nothing was applied. A resolved review never reopens: when the figures move again the next sync files a NEW question, so re-read the pending queue rather than retrying this id.",
            "expected_units": 132,
            "account_positions": null,
            "siblings_queued_to_close": null,
            "created_at": "2026-06-15T12:00:00+00:00"
        }
    },
    "meta": {
        "holding": {
            "id": 1,
            "symbol": "AAPL.US",
            "name": "Apple Inc",
            "units_before": 120,
            "units_after": 132,
            "cost_basis": 20334
        },
        "account": {
            "id": 4,
            "name": "Global Brokerage",
            "currency": "USD",
            "value_before": 66200,
            "value_after": 28050
        },
        "remaining": 0
    }
}

Decline one pending review. It moves one column and no money: the position keeps its units, the account keeps its value, and nothing is added to any ledger.

• A dismissed review is never raised again while its figures are unchanged, and the app does not list dismissed suggestions, so a queue emptied this way leaves no trace a user can find.
• It works on all three kinds, including the `unmatched_instrument` one approve refuses.

Takes no query parameters and no body.

Assistant equivalent: dismiss_sync_review

curl -X POST 'https://ovolos.ai/api/v1/sync-reviews/1/dismiss' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/sync-reviews/1/dismiss", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/sync-reviews/1/dismiss",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "review": {
            "id": 1,
            "type": "adjust_units",
            "status": "dismissed",
            "account_id": 4,
            "account_name": "Global Brokerage",
            "connection_id": 1,
            "provider": "lunchflow",
            "provider_name": "Lunch Flow",
            "question": "Lunch Flow reports 132 units of Apple Inc — you have 120. Approve to adjust?",
            "symbol": "AAPL.US",
            "name": "Apple Inc",
            "holding_id": 1,
            "current_units": 120,
            "provider_units": 132,
            "approvable": false,
            "approve_refusal": "That review is already dismissed and nothing was applied. A resolved review never reopens: when the figures move again the next sync files a NEW question, so re-read the pending queue rather than retrying this id.",
            "expected_units": 132,
            "account_positions": null,
            "siblings_queued_to_close": null,
            "created_at": "2026-06-15T12:00:00+00:00"
        }
    },
    "meta": {
        "remaining": 0,
        "note": "Dismissed for as long as the figures hold. The next sync will not re-ask this question while the position and the provider still disagree by the same amount; a different discrepancy files a new review. Nothing in the app shows a dismissed suggestion, so tell the user what was silenced."
    }
}

AI-estimated value bands for a manually-valued asset (property, vehicle, private company): low / base / high with a confidence level, the rationale, and the sources consulted.

• Model estimates, not appraisals.

Takes no query parameters and no body.

Assistant equivalent: ai_valuations

curl 'https://ovolos.ai/api/v1/accounts/9/ai-valuations' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/9/ai-valuations", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/9/ai-valuations",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "low": 420000,
            "base": 448000,
            "high": 476000,
            "currency": "EUR",
            "confidence": "medium",
            "rationale": "Three comparable 120-130 sqm apartments in Kifissia sold between 3,400 and 3,700 per sqm in the last six months.",
            "sources": [
                "https://example.test/comparable-sales",
                "https://example.test/price-index"
            ],
            "model": "claude-sonnet-4-6",
            "as_of": "2026-06-15"
        }
    ],
    "meta": {
        "count": 1,
        "estimate": true,
        "disclaimer": "AI-generated model estimates, not appraisals or financial advice."
    }
}

How an AI valuation run for this asset is going: `pending` with the research angles finished so far, `done` with a band and a `source`, `error` with a message, or `idle`. This is the free poll; the POST on the same path starts a run.

• `meta.dispatched` is always false here: this route reserves no budget and queues no job, so it cannot start the run it reports on.
• `progress` empties once a finished run's fifteen-minute window expires or an estimate is adopted, so read `status` for whether anything is running.

Takes no query parameters and no body.

Assistant equivalent: ai_valuation_status

curl 'https://ovolos.ai/api/v1/accounts/9/ai-valuation' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/9/ai-valuation", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/9/ai-valuation",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "status": "done",
        "estimate": {
            "id": 1,
            "low": 420000,
            "base": 448000,
            "high": 476000,
            "currency": "EUR",
            "confidence": "medium",
            "rationale": "Three comparable 120-130 sqm apartments in Kifissia sold between 3,400 and 3,700 per sqm in the last six months.",
            "sources": [
                "https://example.test/comparable-sales",
                "https://example.test/price-index"
            ],
            "as_of": "2026-06-15"
        },
        "message": null,
        "progress": []
    },
    "meta": {
        "subject": {
            "type": "account",
            "id": 9
        },
        "estimated_on": "2026-06-15",
        "source": "stored",
        "dispatched": false,
        "disclaimer": "AI-generated model estimates, not appraisals or financial advice."
    }
}

Research what a property, vehicle or private holding is worth. A 202 means a run was queued and a 200 means there is already a band.

• The one route here that spends money on demand: about $0.71 of AI research per run, billed to the owner of the acting portfolio and not to you.
• `meta.dispatched` says whether the call cost anything — false when the answer came from a run already in flight, a cached result or a stored estimate.
• There is no `force`, `rerun` or `refresh` parameter, and the body must be empty, so one you send is refused rather than dropped and answered with a cached band.
• Fill in what GET /accounts/{id}/valuation-inputs reports missing first: a blank mileage is a line the researcher never sees, the run is billed either way, and there is no second run to fix it with.
• Do not poll this to watch a run — the GET on the same path is free, while a repeated POST replays one frozen 202 under the same Idempotency-Key and burns the hourly allowance under a rotating one.

Takes no query parameters and no body.

Assistant equivalent: start_ai_valuation

curl -X POST 'https://ovolos.ai/api/v1/accounts/9/ai-valuation' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/9/ai-valuation", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/9/ai-valuation",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "status": "done",
        "estimate": {
            "id": 1,
            "low": 420000,
            "base": 448000,
            "high": 476000,
            "currency": "EUR",
            "confidence": "medium",
            "rationale": "Three comparable 120-130 sqm apartments in Kifissia sold between 3,400 and 3,700 per sqm in the last six months.",
            "sources": [
                "https://example.test/comparable-sales",
                "https://example.test/price-index"
            ],
            "as_of": "2026-06-15"
        }
    },
    "meta": {
        "subject": {
            "type": "account",
            "id": 9
        },
        "dispatched": false,
        "source": "stored",
        "disclaimer": "AI-generated model estimates, not appraisals or financial advice."
    }
}

Adopt a figure from the estimate as the asset's value today, answering with the whole account.

• This moves net worth, and `meta.applied` reports what you asked for against what was written.
• It consumes the cached estimate, so the next start returns the permanently stored band rather than this one.
• 422 when there is no estimate to apply — start a run first.
• 422 when the estimate came back in a different currency from the asset: the figure would be written as-is into the asset's currency, and nothing here converts it. Change the asset's currency or record a converted value yourself.

Assistant equivalent: apply_ai_valuation

curl -X POST 'https://ovolos.ai/api/v1/accounts/9/ai-valuation/apply' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/9/ai-valuation/apply", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/9/ai-valuation/apply",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 9,
        "name": "Kifissia Apartment",
        "institution": null,
        "type": {
            "value": "real_estate",
            "label": "Real Estate",
            "group": "Real estate"
        },
        "category": "asset",
        "group": null,
        "legal_entity": {
            "id": 5,
            "name": "Rivera Family Trust",
            "kind": "trust",
            "is_default": false
        },
        "currency": "EUR",
        "value": {
            "amount": 448000,
            "signed": 448000,
            "currency": "EUR"
        },
        "ownership_pct": 100,
        "liquidity": "illiquid",
        "risk_level": 2,
        "notes": null,
        "account_group_id": null,
        "linked_account_id": 12,
        "is_lifestyle": false,
        "is_linked": false,
        "sync_health": null,
        "last_valued_on": "2026-06-15",
        "is_archived": false,
        "archived_at": null,
        "is_sold": false,
        "sold_at": null,
        "staleness": {
            "stale": false,
            "severe": false,
            "label": null,
            "updates_automatically": false,
            "stale_after_days": 180,
            "severe_after_days": 365
        },
        "loan": null,
        "updated_at": "2026-06-15T12:00:00+00:00",
        "ai_valuation": null
    },
    "meta": {
        "currency": "EUR",
        "applied": {
            "requested": 448000,
            "value": 448000,
            "clamped": false,
            "currency": "EUR",
            "band": {
                "low": 420000,
                "base": 448000,
… 6 more lines, trimmed for reading. The committed capture is whole.

What the AI researcher will be told about this asset and what it will be missing — each field with the key to write it under, its label, its kind, and for a choice the exact values accepted. Property and vehicles only.

• A blank field is a line the researcher never sees: an unknown mileage or condition comes back as a wider band.
• Read `meta.estimate_on_record` before promising an improvement — once a band is stored, filling these in buys nothing, because a start hands the stored band back.
• `meta.estimated_cost_per_run` is what a run costs the portfolio owner in US dollars, and is the configured figure rather than anyone's ledger.

Takes no query parameters and no body.

Assistant equivalent: valuation_inputs

curl 'https://ovolos.ai/api/v1/accounts/9/valuation-inputs' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/9/valuation-inputs", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/9/valuation-inputs",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "fields": [
            {
                "key": "size_sqm",
                "label": "Size (m²)",
                "kind": "number",
                "options": null,
                "value": 128,
                "provided": true
            },
            {
                "key": "year_built",
                "label": "Year built",
                "kind": "number",
                "options": null,
                "value": 2004,
                "provided": true
            },
            {
                "key": "condition",
                "label": "Condition",
                "kind": "select",
                "options": {
                    "excellent": "Excellent",
                    "good": "Good",
                    "fair": "Fair",
                    "poor": "Needs work"
                },
                "value": "good",
                "provided": true
            }
        ],
        "missing": [],
        "complete": true
    },
    "meta": {
        "account_id": 9,
        "account_name": "Kifissia Apartment",
        "account_type": "real_estate",
        "estimated_cost_per_run": 0.71,
        "cost_currency": "USD",
        "estimate_on_record": true,
        "last_estimated_on": "2026-06-15",
        "sharpen_with": "PATCH /api/v1/accounts/9/valuation-inputs",
        "run_with": "POST /api/v1/accounts/9/ai-valuation",
        "note": "An estimate is already on record, and there is no rerun on this surface — a start now hands back the stored band rather than researching again. Filling these in still improves the NEXT run, which is the scheduled one if this asset is on a schedule, and nothing sooner."
    }
}

Record those facts. It costs nothing, researches nothing and starts nothing — it only changes what the next run is told. Omitted fields are left alone and null clears a value.

• Fields are merged one named key at a time, which is why these have their own endpoint: PATCH /accounts/{id} rebuilds `details` whole and clears every key you leave out.
• Send only what the user actually told you — the researcher treats what it is given as fact, so a guessed mileage buys a confident wrong answer.

What this accepts depends on the account type: real_estate, vehicle. Fields marked above with the types they belong to are refused on the others.

Assistant equivalent: set_valuation_inputs

curl -X PATCH 'https://ovolos.ai/api/v1/accounts/9/valuation-inputs' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/9/valuation-inputs", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/accounts/9/valuation-inputs",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "fields": [
            {
                "key": "size_sqm",
                "label": "Size (m²)",
                "kind": "number",
                "options": null,
                "value": 128,
                "provided": true
            },
            {
                "key": "year_built",
                "label": "Year built",
                "kind": "number",
                "options": null,
                "value": 2004,
                "provided": true
            },
            {
                "key": "condition",
                "label": "Condition",
                "kind": "select",
                "options": {
                    "excellent": "Excellent",
                    "good": "Good",
                    "fair": "Fair",
                    "poor": "Needs work"
                },
                "value": "good",
                "provided": true
            }
        ],
        "missing": [],
        "complete": true
    },
    "meta": {
        "account_id": 9,
        "account_name": "Kifissia Apartment",
        "account_type": "real_estate",
        "estimated_cost_per_run": 0.71,
        "cost_currency": "USD",
        "estimate_on_record": true,
        "last_estimated_on": "2026-06-15",
        "sharpen_with": "PATCH /api/v1/accounts/9/valuation-inputs",
        "run_with": "POST /api/v1/accounts/9/ai-valuation",
        "note": "Nothing moved: every value sent was already recorded. An estimate is already stored for this asset, so this does not improve it: POST /accounts/9/ai-valuation hands back the stored band rather than researching again, and there is no flag that changes that. The next run to read these is the scheduled one.",
        "changed": [],
        "unchanged": true
    }
}

The standing arrangement to re-research this asset: whether Ovolos revalues it automatically, how often, where that cadence came from, when the next billed run is due, and whether a finished one is waiting to be answered. Property and vehicles only.

• `next_due_on` is when this arrangement next spends money, not a promise — the owner's monthly AI budget still has to cover it on the day.
• `pending_review` is a run that has already changed the recorded value, so ignoring it keeps the new figure.
• `cadence_source` says which of three layers set the frequency, and changing the portfolio default will not move an asset whose source is "account".

Takes no query parameters and no body.

Assistant equivalent: scheduled_valuation

curl 'https://ovolos.ai/api/v1/accounts/10/scheduled-valuation' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/10/scheduled-valuation", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/10/scheduled-valuation",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "supported": true,
        "enabled": true,
        "cadence": "quarterly",
        "cadence_label": "Quarterly",
        "cadence_source": "account",
        "cadence_override": "quarterly",
        "last_run_on": null,
        "next_due_on": "2026-09-15",
        "is_due": false,
        "pending_review": {
            "alert_id": 2,
            "raised_at": "2026-06-15T12:00:00+00:00",
            "value_before": null,
            "value_after": null,
            "moved_percent": null,
            "currency": "EUR",
            "confidence": null,
            "ai_valuation_id": null,
            "unanswered": 1
        },
        "pending_failure": null
    },
    "meta": {
        "account_id": 10,
        "account_name": "Family Estate Car",
        "account_type": "vehicle",
        "currency": "EUR",
        "estimated_cost_per_run": 0.71,
        "cost_currency": "USD"
    }
}

Turn automatic revaluation on for a property or vehicle, and choose how often. It queues nothing itself — the daily sweep does the spending, at the first sweep on or after `next_due_on`.

• This commits the portfolio owner to recurring spend: about $0.71 of AI research per run, one run every cadence, for as long as it stays on.
• Nothing in the loop reads back, so an unanswered review does not pause the next run or the next charge.
• An asset whose last recorded value is already a cadence old is due at once: `next_due_on` comes back in the past with `is_due` true, and the research runs at tomorrow's sweep.
• There is no `run_now`, `force` or `first_run_at`, and no earlier date is available at any price.

Assistant equivalent: schedule_ai_revaluation

curl -X POST 'https://ovolos.ai/api/v1/accounts/9/scheduled-valuation' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/9/scheduled-valuation", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/9/scheduled-valuation",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "supported": true,
        "enabled": true,
        "cadence": "annually",
        "cadence_label": "Annually",
        "cadence_source": "type",
        "cadence_override": null,
        "last_run_on": null,
        "next_due_on": "2027-05-31",
        "is_due": false,
        "pending_review": null,
        "pending_failure": null
    },
    "meta": {
        "account_id": 9,
        "account_name": "Kifissia Apartment",
        "account_type": "real_estate",
        "currency": "EUR",
        "estimated_cost_per_run": 0.71,
        "cost_currency": "USD",
        "unchanged": false,
        "note": "Scheduled. The first billed research run is the daily sweep on or after 2027-05-31, and one follows every cadence after that until this is turned off. Nothing has been charged by this call."
    }
}

Turn automatic revaluation off. No further billed runs are dispatched for this asset, and the chosen cadence is remembered, so switching it back on later does not fall back to the class default.

• A member the owner withheld AI tools from can still switch this off: nobody should need permission to stop a charge.
• Values already recorded stand, so net worth does not move, and nothing is refunded — past runs were charged when they ran.

Takes no query parameters and no body.

Assistant equivalent: stop_ai_revaluation

curl -X DELETE 'https://ovolos.ai/api/v1/accounts/10/scheduled-valuation' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/10/scheduled-valuation", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/accounts/10/scheduled-valuation",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "supported": true,
        "enabled": false,
        "cadence": "quarterly",
        "cadence_label": "Quarterly",
        "cadence_source": "account",
        "cadence_override": "quarterly",
        "last_run_on": null,
        "next_due_on": null,
        "is_due": false,
        "pending_review": {
            "alert_id": 2,
            "raised_at": "2026-06-15T12:00:00+00:00",
            "value_before": null,
            "value_after": null,
            "moved_percent": null,
            "currency": "EUR",
            "confidence": null,
            "ai_valuation_id": null,
            "unanswered": 1
        },
        "pending_failure": null
    },
    "meta": {
        "account_id": 10,
        "account_name": "Family Estate Car",
        "account_type": "vehicle",
        "currency": "EUR",
        "estimated_cost_per_run": 0.71,
        "cost_currency": "USD",
        "unchanged": false,
        "note": "No further research runs will be dispatched for this asset. Values already recorded stand, and nothing was refunded — past runs were charged when they ran."
    }
}

Keep the value a scheduled run applied, and close the review it raised. It writes no valuation and moves no figure: the sweep applies its result before it asks, so the number is already the asset's value.

• Doing nothing has the identical effect on the books, so `meta.reviews_answered` is the difference between a decision and a silence.
• The review fingerprint is per day, so an asset that moved at two consecutive cadence ticks carries two reviews and this answers all of them.

Takes no query parameters and no body.

Assistant equivalent: accept_scheduled_valuation

curl -X POST 'https://ovolos.ai/api/v1/accounts/10/scheduled-valuation/accept' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/10/scheduled-valuation/accept", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/10/scheduled-valuation/accept",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "supported": true,
        "enabled": true,
        "cadence": "quarterly",
        "cadence_label": "Quarterly",
        "cadence_source": "account",
        "cadence_override": "quarterly",
        "last_run_on": null,
        "next_due_on": "2026-09-15",
        "is_due": false,
        "pending_review": null,
        "pending_failure": null
    },
    "meta": {
        "account_id": 10,
        "account_name": "Family Estate Car",
        "account_type": "vehicle",
        "currency": "EUR",
        "estimated_cost_per_run": 0.71,
        "cost_currency": "USD",
        "reviews_answered": 1,
        "unchanged": false,
        "value": 29000,
        "note": "The auto-applied value stands and the review is closed. Nothing was recorded and nothing was charged."
    }
}

Undo a scheduled revaluation: remove the value it applied today so the previous one stands again, and close the review.

• This moves net worth — a valuation is a point on a curve, so the growth measured across it and the drawdown through it move back with it.
• It is a valuation delete narrowed to today and the `ai_scheduled` source; a scheduled value from an earlier day is an ordinary valuation by now, and is removed by id instead.
• POST /ai-valuation/apply is not a substitute: it clamps a figure into the same band and writes today, where restoring yesterday's value means removing today's point.
• It spends nothing and refunds nothing, and buys no fresh run: the cadence anchor stays where the run put it and the stored estimate survives.

Takes no query parameters and no body.

Assistant equivalent: revert_scheduled_valuation

curl -X POST 'https://ovolos.ai/api/v1/accounts/10/scheduled-valuation/revert' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/10/scheduled-valuation/revert", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/10/scheduled-valuation/revert",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "supported": true,
        "enabled": true,
        "cadence": "quarterly",
        "cadence_label": "Quarterly",
        "cadence_source": "account",
        "cadence_override": "quarterly",
        "last_run_on": null,
        "next_due_on": "2026-08-31",
        "is_due": false,
        "pending_review": null,
        "pending_failure": null
    },
    "meta": {
        "account_id": 10,
        "account_name": "Family Estate Car",
        "account_type": "vehicle",
        "currency": "EUR",
        "estimated_cost_per_run": 0.71,
        "cost_currency": "USD",
        "valuation_deleted": true,
        "affects_net_worth": true,
        "as_of": "2026-06-15",
        "value_before": 29000,
        "value_after": 29000,
        "reviews_answered": 1,
        "unchanged": false,
        "note": "Today's auto-applied value was removed and the previous one stands again. The research it came from was already paid for and the estimate is still on record, so this refunds nothing and buys nothing. The asset stays not due until its next cadence."
    }
}

The portfolio-wide defaults behind those arrangements: how often each class of asset is re-researched, and how far a value must move before the change is held for review. Every field appears three times — the effective value, the stored `overrides`, and the `defaults` that would apply.

• Defaults, not switches: they decide what an opted-in asset inherits and opt nothing in themselves.
• `review_threshold_percent` is measured on the whole asset, before the ownership share, and a run beyond it still applies its value — it decides whether you are asked, not whether it happens.

Takes no query parameters and no body.

Assistant equivalent: ai_valuation_settings

curl 'https://ovolos.ai/api/v1/portfolio/ai-valuation-settings' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/portfolio/ai-valuation-settings", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/portfolio/ai-valuation-settings",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "real_estate_cadence": "annually",
        "vehicle_cadence": "quarterly",
        "review_threshold_percent": 30,
        "overrides": {
            "real_estate_cadence": null,
            "vehicle_cadence": null,
            "review_threshold_percent": null
        },
        "defaults": {
            "real_estate_cadence": "annually",
            "vehicle_cadence": "quarterly",
            "review_threshold_percent": 30
        }
    },
    "meta": {
        "applies_to": [
            "real_estate",
            "vehicle"
        ],
        "estimated_cost_per_run": 0.71,
        "cost_currency": "USD",
        "threshold_note": "review_threshold_percent is measured on the whole asset, before the ownership share, and a run beyond it still applies its value — the threshold decides whether you are asked about it, not whether it happens."
    }
}

Change those defaults. An absent key is left alone and an explicit null clears the override back to the built-in default, so a client nudging the threshold cannot silently reset a cadence it never mentioned.

• The cadence is a spending decision taken for every opted-in asset at once: moving a portfolio's property from annually to monthly multiplies what those assets cost by twelve, from the next sweep on.
• The threshold costs nothing either way — raising it makes Ovolos quieter rather than cheaper.
• It opts nothing in; use POST /accounts/{id}/scheduled-valuation for that.

Assistant equivalent: set_ai_valuation_settings

curl -X PATCH 'https://ovolos.ai/api/v1/portfolio/ai-valuation-settings' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/portfolio/ai-valuation-settings", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/portfolio/ai-valuation-settings",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "real_estate_cadence": "annually",
        "vehicle_cadence": "quarterly",
        "review_threshold_percent": 30,
        "overrides": {
            "real_estate_cadence": null,
            "vehicle_cadence": null,
            "review_threshold_percent": null
        },
        "defaults": {
            "real_estate_cadence": "annually",
            "vehicle_cadence": "quarterly",
            "review_threshold_percent": 30
        }
    },
    "meta": {
        "applies_to": [
            "real_estate",
            "vehicle"
        ],
        "estimated_cost_per_run": 0.71,
        "cost_currency": "USD",
        "threshold_note": "review_threshold_percent is measured on the whole asset, before the ownership share, and a run beyond it still applies its value — the threshold decides whether you are asked about it, not whether it happens.",
        "unchanged": true,
        "note": "Applies to assets already opted in to auto-revaluation; it opts nothing in by itself. Nothing was charged by this call — the cadence decides how often the daily sweep dispatches a billed run for each opted-in asset from here on."
    }
}

The people, companies and trusts your accounts belong to — id, name, kind and how many accounts sit under each. Every account carries its `legal_entity`, so pair the two to group holdings by holder.

Takes no query parameters and no body.

Assistant equivalent: list_legal_entities

curl 'https://ovolos.ai/api/v1/legal-entities' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/legal-entities", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/legal-entities",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 1,
            "name": "Alex Rivera",
            "kind": "personal",
            "kind_label": "Personal",
            "is_default": true,
            "notes": null,
            "accounts_count": 11
        },
        {
            "id": 5,
            "name": "Rivera Family Trust",
            "kind": "trust",
            "kind_label": "Trust",
            "is_default": false,
            "notes": "Holds the property and the mortgage behind it.",
            "accounts_count": 5
        }
    ],
    "meta": {
        "count": 2
    }
}

Record what an account is worth on a day. It answers with the whole account, because the write derives figures you cannot predict — the reporting-currency conversions are baked at that date's exchange rate.

• One row per account per day: posting the same date again replaces that day's figure rather than adding a second.
• 409 `account_sold` on an account frozen at its terminal zero — undo the sale first, or record the value against whatever holds the money now.

Assistant equivalent: record_valuation

curl -X POST 'https://ovolos.ai/api/v1/accounts/1/valuations' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "value": 27100,
      "as_of": "2026-06-15"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/1/valuations", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "value": 27100,
      "as_of": "2026-06-15"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/1/valuations",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "value": 27100,
        "as_of": "2026-06-15",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 1,
        "name": "Everyday Current Account",
        "institution": "Northbank",
        "type": {
            "value": "checking",
            "label": "Checking",
            "group": "Cash & savings"
        },
        "category": "asset",
        "group": {
            "id": 1,
            "name": "Everyday banking"
        },
        "legal_entity": {
            "id": 1,
            "name": "Alex Rivera",
            "kind": "personal",
            "is_default": true
        },
        "currency": "EUR",
        "value": {
            "amount": 27100,
            "signed": 27100,
            "currency": "EUR"
        },
        "ownership_pct": 100,
        "liquidity": "cash",
        "risk_level": 1,
        "notes": "The account salary lands in.",
        "account_group_id": 1,
        "linked_account_id": null,
        "is_lifestyle": false,
        "is_linked": false,
        "sync_health": null,
        "last_valued_on": "2026-06-15",
        "is_archived": false,
        "archived_at": null,
        "is_sold": false,
        "sold_at": null,
        "staleness": {
            "stale": false,
            "severe": false,
            "label": null,
            "updates_automatically": false,
            "stale_after_days": 30,
            "severe_after_days": 90
        },
        "loan": null,
        "updated_at": "2026-06-15T12:00:00+00:00",
        "ai_valuation": null
    },
    "meta": {
        "currency": "EUR"
    }
}

Record many days' values for one account in one call — the same dated upsert as the single write, repeated. Every row comes back in the order you sent it as `index` and `status` (created, updated or unchanged), with `previous_value` where there was one.

• Validated whole, then written whole: one future-dated or negative row is a 422 that stores nothing, and the error bag names every failing index at once.
• On an account whose value is derived from positions this is the wrong tool: `meta.value_derived_from_positions` says so, and rows written here are replaced on the next rebuild.
• A retry without an Idempotency-Key spends the row budget again, even though the upsert writes the same rows.
• 409 `account_sold` refuses the whole batch rather than the rows individually.

Assistant equivalent: record_valuations

curl -X POST 'https://ovolos.ai/api/v1/accounts/2/valuations/batch' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "entries": [
          {
              "value": 40600,
              "as_of": "2026-05-31"
          },
          {
              "value": 41250,
              "as_of": "2026-06-15"
          }
      ]
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/2/valuations/batch", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "entries": [
          {
              "value": 40600,
              "as_of": "2026-05-31"
          },
          {
              "value": 41250,
              "as_of": "2026-06-15"
          }
      ]
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/2/valuations/batch",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "entries": [
            {
                "value": 40600,
                "as_of": "2026-05-31",
            },
            {
                "value": 41250,
                "as_of": "2026-06-15",
            },
        ],
    },
)

print(response.status_code, response.text)

{
    "data": {
        "account_id": 2,
        "name": "Rainy Day Savings",
        "requested": 2,
        "created": 1,
        "updated": 0,
        "unchanged": 1,
        "entries": [
            {
                "index": 0,
                "status": "unchanged",
                "as_of": "2026-05-31",
                "value": 40600,
                "previous_value": 40600
            },
            {
                "index": 1,
                "status": "created",
                "as_of": "2026-06-15",
                "value": 41250,
                "previous_value": null
            }
        ]
    },
    "meta": {
        "currency": "EUR",
        "takes": "entries",
        "max_per_call": 120,
        "value_before": 40600,
        "value_after": 41250,
        "latest_valued_on": "2026-06-15",
        "valuations_total": 9,
        "rows_remaining": 358,
        "rows_per_hour": 360,
        "value_derived_from_positions": false,
        "note": "These rows ARE this account's value history: net worth on each of those dates, and the growth, CAGR, drawdown and FX attribution measured across them, all read them from now on. Nothing else needed rebuilding — net worth is derived from valuations rather than stored."
    }
}

Hide many accounts in one call, by an explicit list of ids. Every id comes back with its own outcome — `archived`, `unchanged`, or `not_found` for one that is not in these books — in the order you sent them.

• Each row carries what that account did to net worth, signed as it counts, so hiding a mortgage reads as a rise; `meta.net_worth_effect` totals only what moved.
• Nothing is deleted and /accounts/bulk/restore brings them back, but to the person reading their net worth a hidden account is indistinguishable from a deleted one.

Assistant equivalent: hide_accounts

curl -X POST 'https://ovolos.ai/api/v1/accounts/bulk/archive' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "ids": [
          5,
          6
      ]
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/bulk/archive", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "ids": [
          5,
          6
      ]
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/bulk/archive",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "ids": [
            5,
            6,
        ],
    },
)

print(response.status_code, response.text)

{
    "data": {
        "hidden": true,
        "requested": 2,
        "changed": 2,
        "unchanged": 0,
        "not_found": 0,
        "accounts": [
            {
                "index": 0,
                "account_id": 5,
                "name": "Direct Equities",
                "status": "archived",
                "reason": null,
                "type": "stocks",
                "counts_as": "asset",
                "currency": "USD",
                "is_linked": false,
                "hidden": true,
                "net_worth_effect": -6400
            },
            {
                "index": 1,
                "account_id": 6,
                "name": "Cold Storage Wallet",
                "status": "archived",
                "reason": null,
                "type": "crypto",
                "counts_as": "asset",
                "currency": "USD",
                "is_linked": false,
                "hidden": true,
                "net_worth_effect": -6200
            }
        ]
    },
    "meta": {
        "currency": "EUR",
        "net_worth_effect": -12600,
        "max_per_call": 50,
        "takes": "ids",
        "accounts_remaining": 148,
        "accounts_per_hour": 150,
        "note": "Nothing was deleted: every hidden account keeps its valuations, holdings and transactions, and POST /api/v1/accounts/bulk/restore brings them all back. What changes is that each balance leaves net worth on EVERY date, not only today — the totals, the asset and liability split, the allocation, the liquidity and risk mix and the account list — and any account with is_linked true stops syncing until it is restored. An id that resolved to nothing is reported rather than dropped, and an account already hidden answers unchanged rather than having its hidden-at timestamp moved."
    }
}

Bring many hidden accounts back — the other half of the pair above, same body and the same per-id report.

• A restored provider-synced account rejoins the daily schedule rather than syncing on the spot, so its balance can lag until then.

Assistant equivalent: hide_accounts

curl -X POST 'https://ovolos.ai/api/v1/accounts/bulk/restore' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "ids": [
          15
      ]
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/bulk/restore", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "ids": [
          15
      ]
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/bulk/restore",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "ids": [
            15,
        ],
    },
)

print(response.status_code, response.text)

{
    "data": {
        "hidden": false,
        "requested": 1,
        "changed": 1,
        "unchanged": 0,
        "not_found": 0,
        "accounts": [
            {
                "index": 0,
                "account_id": 15,
                "name": "Closed Student Account",
                "status": "restored",
                "reason": null,
                "type": "savings",
                "counts_as": "asset",
                "currency": "EUR",
                "is_linked": false,
                "hidden": false,
                "net_worth_effect": 1200
            }
        ]
    },
    "meta": {
        "currency": "EUR",
        "net_worth_effect": 1200,
        "max_per_call": 50,
        "takes": "ids",
        "accounts_remaining": 149,
        "accounts_per_hour": 150,
        "note": "A restored provider-synced account rejoins the daily sync schedule rather than syncing on the spot, so its balance can lag until then. An account already visible answers unchanged."
    }
}

Move accounts out of the portfolio you are acting in and into another portfolio you own, by an explicit list of ids. Structural rather than financial: nothing is deleted and no figure is recomputed.

• Each account leaves with its whole history, so the destination's past net worth changes shape as well as its present, and so does the source's.
• Ownership of both sets of books is checked once and refuses the whole call having touched nothing: 404 for a destination you do not own, 403 `portfolio_forbidden` inside somebody else's.
• `provider_connected`, `liquidated`, `linked_account`, `costs_attributed` and `legal_entity` are per-account refusals that leave the rest moving; each names something a person must fix in Ovolos.
• `refused_while_moving` is the one refusal worth retrying — re-read that account and send just its id again.
• A moved account has left the acting portfolio, so a retry that does not carry the original Idempotency-Key reports `not_found` for every account that in fact moved.

Assistant equivalent: move_accounts

curl -X POST 'https://ovolos.ai/api/v1/accounts/bulk/move' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "ids": [
          5
      ],
      "destination_portfolio_id": 4
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/bulk/move", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "ids": [
          5
      ],
      "destination_portfolio_id": 4
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/bulk/move",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "ids": [
            5,
        ],
        "destination_portfolio_id": 4,
    },
)

print(response.status_code, response.text)

{
    "data": {
        "requested": 1,
        "moved": 1,
        "refused": 0,
        "not_found": 0,
        "destination_portfolio_id": 4,
        "accounts": [
            {
                "index": 0,
                "account_id": 5,
                "name": "Direct Equities",
                "status": "moved",
                "reason": null,
                "message": null,
                "moved_to": 4,
                "legal_entity_id": 4
            }
        ]
    },
    "meta": {
        "destination": {
            "id": 4,
            "name": "Side Ventures",
            "currency": "EUR"
        },
        "legal_entity_id": null,
        "max_per_call": 20,
        "takes": "ids",
        "accounts_remaining": 149,
        "accounts_per_hour": 150,
        "note": "An account arrives with its entire history — every valuation, transaction, holding, private position, sync review, alert and planned item — so the destination portfolio's net worth changes shape retroactively, not just from today, and the portfolio it LEFT loses that history the same way. It also arrives UNGROUPED: account groups belong to the portfolio they were made in. A refused account was not touched at all, and every refusal names something to fix in Ovolos before retrying it."
    }
}

What this portfolio has sold and for how much: price, cost basis, realized gain, where the money went, which debt it cleared, and `reversible` for whether the undo will still accept the row. A sold account leaves GET /accounts entirely, so this is where it is read.

• A debt settled out of a sale is listed with role "settled_liability" and `settled_with_sale_of` naming the asset — undoing that asset's sale is what brings it back.
• Figures inside `sale` are in that account's own currency as recorded on the sale day, and are neither converted nor totalled: pricing a past sale at today's rate reports a number that was never true.
• `?currency=` applies only to `value_today`, which is zero on every row by construction.
• `sale` is null on a row that carries no record of its own, and `sale_detail_unavailable` says which case that is.

Assistant equivalent: list_sold_assets

curl 'https://ovolos.ai/api/v1/accounts/sold' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/sold", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/accounts/sold",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "account_id": 16,
            "name": "Submariner 124060",
            "type": {
                "value": "watch",
                "label": "Watch",
                "group": "Watches"
            },
            "category": "asset",
            "currency": "EUR",
            "sold_on": "2026-05-20",
            "is_archived": false,
            "role": "sold_asset",
            "settled_with_sale_of": null,
            "sale": {
                "sale_date": "2026-05-20",
                "sale_price": 11500,
                "currency": "EUR",
                "cost_basis": 8200,
                "realized_gain": 3300,
                "destination": "withdrawn",
                "net_proceeds": 11500,
                "mortgage_settled": 0,
                "settled_mortgage": null,
                "proceeds_to": null
            },
            "sale_detail_unavailable": null,
            "value_today": 0,
            "reversible": true,
            "not_reversible_reason": null,
            "reverse_with": "DELETE /api/v1/accounts/16/sale"
        }
    ],
    "meta": {
        "currency": "EUR",
        "count": 1,
        "note": "Each sale's figures are in that account's own currency, as recorded on the sale date — they are not converted, and there is deliberately no total: pricing a past sale at today's rate reports a figure that was never true. meta.currency applies only to value_today. A row with role \"settled_liability\" is a debt closed out of another account's sale; it has no sale of its own and is undone by undoing that one."
    }
}

Record that an asset was sold: a terminal zero on the sale date and a sold marker, optionally the proceeds credited to a cash account and the linked debt settled out of them. `meta.accounts_touched` names every account moved, and `meta.net_worth_effect` is the single display-currency figure.

• It deletes every valuation dated after the sale date, on the asset and on a settled debt; only the undo restores them, and `meta.undo_does_not_restore` says what it will not.
• Every earlier value stands. Archiving instead removes the account from every past date and redraws the whole history lower.
• Proceeds are a value bump on the receiving account, never a transaction — do not record one as well.
• That account must be manually-tracked cash, checking or savings: one with a ledger rebuilds its balance from that ledger and erases the credit.
• Settling only ever pays the account's own `linked_account_id`, at that debt's balance on the sale date, and is refused when the proceeds fall short.
• Repayments of a settled debt stay put and stop moving a balance; new links to it are refused while it is settled.

Assistant equivalent: sell_asset

curl -X POST 'https://ovolos.ai/api/v1/accounts/9/sale' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "sale_date": "2026-06-12",
      "sale_price": 455000
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/9/sale", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "sale_date": "2026-06-12",
      "sale_price": 455000
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/9/sale",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "sale_date": "2026-06-12",
        "sale_price": 455000,
    },
)

print(response.status_code, response.text)

{
    "data": {
        "sold": true,
        "account_id": 9,
        "name": "Kifissia Apartment",
        "sale_date": "2026-06-12",
        "sale_price": 455000,
        "currency": "EUR",
        "cost_basis": 380000,
        "realized_gain": 75000,
        "destination": "withdrawn",
        "net_proceeds": 455000,
        "mortgage_settled": 0,
        "settled_mortgage": null,
        "proceeds_to": null
    },
    "meta": {
        "currency": "EUR",
        "accounts_touched": [
            {
                "account_id": 9,
                "name": "Kifissia Apartment",
                "role": "sold_asset",
                "type": {
                    "value": "real_estate",
                    "label": "Real Estate"
                },
                "currency": "EUR",
                "value_before": 436000,
                "value_after": 0,
                "net_worth_change": -436000,
                "valuations_before": 8,
                "valuations_after": 9,
                "is_sold": true
            },
            {
                "account_id": 12,
                "name": "Kifissia Mortgage",
                "role": "linked_liability",
                "type": {
                    "value": "mortgage",
                    "label": "Mortgage"
                },
                "currency": "EUR",
                "value_before": 239800,
                "value_after": 239800,
                "net_worth_change": 0,
                "valuations_before": 8,
                "valuations_after": 8,
                "is_sold": false
            }
        ],
        "net_worth_effect": -436000,
        "history_preserved": true,
        "mortgage_settled": {
            "requested": false,
            "settled": false,
            "account_id": 12,
            "name": "Kifissia Mortgage",
            "amount": 0,
… 10 more lines, trimmed for reading. The committed capture is whole.

Undo a sale: bring the asset back with the value history it had, reopen a debt settled out of the proceeds, and take those proceeds back out of the account they went into. `meta.reversed` reports the three legs separately, because they are not equally exact.

• Exact on the asset and on a settled debt: closing snapshots every valuation it was about to lose, including the one the terminal zero overwrote.
• A delta on the cash leg — only this sale's own credit is subtracted from the sale-date row.
• Two things answer 409 `sale_not_reversible` rather than restoring the asset and leaving the money: anything else recorded on that account for the sale date, and a value recorded there for any later day.
• `meta.not_restored` names what does not come back: positions traded or deleted while the account was sold, and the repayment rebuild on a reopened debt.

Assistant equivalent: undo_sale

curl -X DELETE 'https://ovolos.ai/api/v1/accounts/16/sale' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/16/sale", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/accounts/16/sale",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true,
        "account_id": 16,
        "name": "Submariner 124060",
        "sale_date": "2026-05-20",
        "sale_price": 11500
    },
    "meta": {
        "currency": "EUR",
        "accounts_touched": [
            {
                "account_id": 16,
                "name": "Submariner 124060",
                "role": "restored_asset",
                "type": {
                    "value": "watch",
                    "label": "Watch"
                },
                "currency": "EUR",
                "value_before": 0,
                "value_after": 0,
                "net_worth_change": 0,
                "valuations_before": 1,
                "valuations_after": 0,
                "is_sold": false
            }
        ],
        "net_worth_effect": 0,
        "reversed": {
            "asset": {
                "account_id": 16,
                "restored": true,
                "exact": true
            },
            "mortgage": null,
            "cash": null
        },
        "not_restored": [],
        "note": "The asset is back with its value history exactly as it was, including the value that stood on the sale date itself. It rejoins net worth, the account list and the daily revaluation."
    }
}

Remove one valuation. `meta` says what the account is worth afterwards, so you need not re-read it.

• A valuation is a point on a curve, so removing one moves the account's value, the growth and CAGR measured across it, the drawdown through it, and net worth on that date.
• The POST upserts on the date, so a value recorded against the wrong day is corrected by fixing the right day and removing the wrong one.
• 409 `account_sold`: deleting a point from a sold account would put its previous value back into net worth while it stays off every account list. Undo the sale first.

Takes no query parameters and no body.

Assistant equivalent: delete_valuation

curl -X DELETE 'https://ovolos.ai/api/v1/accounts/1/valuations/94' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/1/valuations/94", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/accounts/1/valuations/94",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true,
        "as_of": "2026-06-14"
    },
    "meta": {
        "latest_valued_on": "2026-05-31",
        "remaining": 8
    }
}

Remove a position, and every buy and sell ever recorded against it — `meta.trades_deleted` says how many went, because a trade cannot outlive its holding.

• Use it for a position attached to the wrong instrument or entered twice; a real sale is a trade, not a delete.
• `meta.revalued` is false where nothing is left to price: when you removed the last position, or on an account already marked sold.
• Values dated before today still include the position that just went; the 05:50 UTC nightly rebuild redraws them, and `meta.history_rebuild_queued` is false when it was the last position, no curve being left to derive.

Takes no query parameters and no body.

Assistant equivalent: delete_holding

curl -X DELETE 'https://ovolos.ai/api/v1/accounts/4/holdings/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/4/holdings/1", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/accounts/4/holdings/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true,
        "id": 1,
        "account_id": 4,
        "instrument_id": 1,
        "symbol": "AAPL.US",
        "name": "Apple Inc",
        "label": null,
        "currency": "USD",
        "units": 120,
        "cost_basis": 17784,
        "opened_on": "2024-02-09"
    },
    "meta": {
        "trades_deleted": 1,
        "remaining": 1,
        "value_before": 66200,
        "value_after": 66200,
        "revalued": false,
        "history_rebuild_queued": true
    }
}

Record the stake in an unlisted company or fund — the position that gives a private company or private fund account its value. The kind comes from the account: a company takes the share purchase that opens the ledger, a fund takes its ownership and optionally a first capital call.

• These are the writes nothing checks: no symbol, no feed and no closing price, so the figure you send is the account's value until somebody changes it.
• `latest_valuation` is what the whole company or fund is worth; `stake` is that times the ownership, and `stake` is what reaches net worth.
• A fund's opening capital call is optional on purpose — an invented one becomes the fund's cost basis and every multiple computed from it.
• No cash moves either way; the bank-side debit is a separate transaction.
• One position per account, because the account is the company: a second is 409 `duplicate_private_position` naming the first.

What this accepts depends on the account type: private_company, private_fund. Fields marked above with the types they belong to are refused on the others.

Assistant equivalent: add_private_holding

curl -X POST 'https://ovolos.ai/api/v1/accounts/11/private-holdings' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "latest_valuation": 6000000,
      "total_shares": 2000000,
      "units": 60000,
      "traded_on": "2026-02-17"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/11/private-holdings", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "latest_valuation": 6000000,
      "total_shares": 2000000,
      "units": 60000,
      "traded_on": "2026-02-17"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/11/private-holdings",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "latest_valuation": 6000000,
        "total_shares": 2000000,
        "units": 60000,
        "traded_on": "2026-02-17",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "private_holding": {
            "id": 3,
            "account_id": 11,
            "kind": "private_company",
            "name": "Northwind Robotics Holding",
            "currency": "USD",
            "latest_valuation": 6000000,
            "ownership_pct": 3,
            "stake": 180000,
            "total_shares": 2000000,
            "units": 60000,
            "committed_capital": null,
            "cost_basis": null,
            "deployed": null,
            "distributed": null,
            "acquired_on": "2026-02-17"
        },
        "ledger": [
            {
                "id": 3,
                "type": "buy",
                "units": 60000,
                "price": null,
                "amount": null,
                "traded_on": "2026-02-17"
            }
        ]
    },
    "meta": {
        "value_before": 0,
        "value_after": 180000,
        "dates_rebuilt": 1,
        "cash_moved": null,
        "note": "This account's value is this position: the whole company or fund valuation × your ownership, converted to the account currency. Nothing prices it — no feed, no market close, no sync — so it stands at that figure until a person or an AI estimate moves it, and a wrong number here moves net worth with nothing downstream to disagree."
    }
}

Correct what the company or fund is worth, or the shape of the stake. Omitted fields keep their stored values.

• `latest_valuation` moves today's figure only — a value that was true on an earlier date is a mark, and using this for one silently restates today instead.
• The ledger is not reachable here: a mark, a capital call and a distribution are dated events with their own endpoints.

What this accepts depends on the account type: private_company, private_fund. Fields marked above with the types they belong to are refused on the others.

Assistant equivalent: update_private_holding

curl -X PATCH 'https://ovolos.ai/api/v1/accounts/7/private-holdings/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -H 'If-Match: THE_ETAG_FROM_YOUR_LAST_READ'

const response = await fetch("https://ovolos.ai/api/v1/accounts/7/private-holdings/1", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/accounts/7/private-holdings/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
        "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "private_holding": {
            "id": 1,
            "account_id": 7,
            "kind": "private_company",
            "name": "Pallma AI Ltd",
            "currency": "GBP",
            "latest_valuation": 12000000,
            "ownership_pct": 4.5,
            "stake": 540000,
            "total_shares": 1000000,
            "units": 45000,
            "committed_capital": null,
            "cost_basis": 90000,
            "deployed": null,
            "distributed": null,
            "acquired_on": "2023-06-01"
        }
    },
    "meta": {
        "unchanged": true,
        "value_before": 0,
        "value_after": 0,
        "dates_rebuilt": 0,
        "note": "This account's value is this position: the whole company or fund valuation × your ownership, converted to the account currency. Nothing prices it — no feed, no market close, no sync — so it stands at that figure until a person or an AI estimate moves it, and a wrong number here moves net worth with nothing downstream to disagree."
    }
}

Record what the whole company or fund was worth on a day — a funding round, a quarterly NAV, an accountant's figure.

• It becomes a point on the account's value curve, so it moves net worth on that date and every growth, CAGR and drawdown figure measured across it.
• One mark per date, upserted rather than appended (`meta.replaced`), so a mistyped figure is corrected by posting the same date again.
• A mark dated today also writes `latest_valuation` (`meta.latest_valuation_updated`): today's point is always read from that column, so a today-mark that did not would move nothing.
• Do not use POST /accounts/{id}/valuations for these accounts — a value written straight onto the account fights the positions rebuild instead of feeding it.

Assistant equivalent: record_private_valuation

curl -X POST 'https://ovolos.ai/api/v1/accounts/7/private-holdings/1/valuations' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "valuation": 13500000,
      "valued_on": "2026-06-10"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/7/private-holdings/1/valuations", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "valuation": 13500000,
      "valued_on": "2026-06-10"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/7/private-holdings/1/valuations",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "valuation": 13500000,
        "valued_on": "2026-06-10",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "mark": {
            "id": 3,
            "valuation": 13500000,
            "valued_on": "2026-06-10"
        },
        "private_holding": {
            "id": 1,
            "account_id": 7,
            "kind": "private_company",
            "name": "Pallma AI Ltd",
            "currency": "GBP",
            "latest_valuation": 12000000,
            "ownership_pct": 4.5,
            "stake": 540000,
            "total_shares": 1000000,
            "units": 45000,
            "committed_capital": null,
            "cost_basis": 90000,
            "deployed": null,
            "distributed": null,
            "acquired_on": "2023-06-01"
        }
    },
    "meta": {
        "replaced": false,
        "latest_valuation_updated": false,
        "marks": 2,
        "value_before": 0,
        "value_after": 540000,
        "dates_rebuilt": 3,
        "note": "This account's value is this position: the whole company or fund valuation × your ownership, converted to the account currency. Nothing prices it — no feed, no market close, no sync — so it stands at that figure until a person or an AI estimate moves it, and a wrong number here moves net worth with nothing downstream to disagree."
    }
}

Record capital a private fund has called. It raises deployed capital, which is the fund's cost basis, so the multiples (DPI, RVPI and TVPI), the unrealized gain and the uncalled commitment all move.

• It does not change what the account is worth — the stake is the fund's valuation times the ownership — so `value_before` and `value_after` are equal on purpose.
• No cash is moved (`meta.cash_moved: false`): the debit on the bank account the money left is a separate transaction.
• The amount is always positive; the direction is the endpoint, never the sign.
• It appends, so a retry that does not carry the original Idempotency-Key is a second draw.

Assistant equivalent: record_capital_call

curl -X POST 'https://ovolos.ai/api/v1/accounts/8/private-holdings/2/capital-calls' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "amount": 75000,
      "traded_on": "2026-06-01"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/8/private-holdings/2/capital-calls", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "amount": 75000,
      "traded_on": "2026-06-01"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/8/private-holdings/2/capital-calls",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "amount": 75000,
        "traded_on": "2026-06-01",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "entry": {
            "id": 3,
            "type": "capital_call",
            "units": 0,
            "price": null,
            "amount": 75000,
            "traded_on": "2026-06-01"
        },
        "private_holding": {
            "id": 2,
            "account_id": 8,
            "kind": "private_fund",
            "name": "Meridian Growth Fund II LP",
            "currency": "USD",
            "latest_valuation": 24000000,
            "ownership_pct": 1.25,
            "stake": 300000,
            "total_shares": null,
            "units": 0,
            "committed_capital": 500000,
            "cost_basis": 275000,
            "deployed": 275000,
            "distributed": 45000,
            "acquired_on": "2024-01-15"
        }
    },
    "meta": {
        "deployed": 275000,
        "distributed": 45000,
        "value_before": 0,
        "value_after": 0,
        "cash_moved": false,
        "note": "No cash was moved. This records the fund event only — the same as the Ovolos app, which writes one ledger row and touches no other account. The matching debit or credit on the bank account the money left or landed in is a separate transaction, and a bank feed will usually bring it in on its own."
    }
}

Record money a private fund paid back. It raises distributed capital, so DPI and TVPI move.

• It does not reduce the commitment, and it does not reduce what the account is worth — a fund marking itself lower after a payout is a separate fact, recorded as a valuation.
• No cash is moved: the credit on the receiving bank account is its own transaction.
• The amount is always positive; the direction is the endpoint, never the sign.
• It appends, so a retry that does not carry the original Idempotency-Key is a second distribution.

Assistant equivalent: record_distribution

curl -X POST 'https://ovolos.ai/api/v1/accounts/8/private-holdings/2/distributions' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "amount": 30000,
      "traded_on": "2026-06-01"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/8/private-holdings/2/distributions", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "amount": 30000,
      "traded_on": "2026-06-01"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/8/private-holdings/2/distributions",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "amount": 30000,
        "traded_on": "2026-06-01",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "entry": {
            "id": 3,
            "type": "distribution",
            "units": 0,
            "price": null,
            "amount": 30000,
            "traded_on": "2026-06-01"
        },
        "private_holding": {
            "id": 2,
            "account_id": 8,
            "kind": "private_fund",
            "name": "Meridian Growth Fund II LP",
            "currency": "USD",
            "latest_valuation": 24000000,
            "ownership_pct": 1.25,
            "stake": 300000,
            "total_shares": null,
            "units": 0,
            "committed_capital": 500000,
            "cost_basis": 200000,
            "deployed": 200000,
            "distributed": 75000,
            "acquired_on": "2024-01-15"
        }
    },
    "meta": {
        "deployed": 200000,
        "distributed": 75000,
        "value_before": 0,
        "value_after": 0,
        "cash_moved": false,
        "note": "No cash was moved. This records the fund event only — the same as the Ovolos app, which writes one ledger row and touches no other account. The matching debit or credit on the bank account the money left or landed in is a separate transaction, and a bank feed will usually bring it in on its own."
    }
}

Remove the position, and with it every hand-entered valuation mark, the whole capital-call and distribution (or share) ledger, and any stored AI valuation runs. The counts are in `meta`.

• The one delete here that can zero an account: a private account's value is this position, so the value history goes with it and the account is worth nothing until something else values it.
• It is not how you record a sale — that is POST /accounts/{id}/sale, which computes the realized gain and leaves every earlier figure where it was.
• It is not how you record a write-off either: a company that failed while the stake is still held is PATCH `latest_valuation` to 0, which keeps the history showing what it was once worth.

Takes no query parameters and no body.

Assistant equivalent: delete_private_holding

curl -X DELETE 'https://ovolos.ai/api/v1/accounts/7/private-holdings/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/7/private-holdings/1", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/accounts/7/private-holdings/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true,
        "id": 1,
        "account_id": 7,
        "kind": "private_company",
        "name": "Pallma AI Ltd",
        "currency": "GBP",
        "latest_valuation": 12000000,
        "ownership_pct": 4.5,
        "stake": 540000,
        "total_shares": 1000000,
        "units": 45000,
        "committed_capital": null,
        "cost_basis": 90000,
        "deployed": null,
        "distributed": null,
        "acquired_on": "2023-06-01"
    },
    "meta": {
        "ledger_entries_deleted": 0,
        "marks_deleted": 1,
        "ai_valuations_deleted": 0,
        "remaining": 0,
        "value_before": 0,
        "value_after": 0,
        "dates_rebuilt": 0,
        "note": "The account's whole value came from this position, so its positions-sourced valuation history went with it. An account with nothing left in it is worth nothing until something else values it — record a valuation against the account, or archive it if the holding is finished."
    }
}

Which institutions this portfolio banks with and whether each link is healthy: the provider, when it last synced, whether a reconnect is due, and the accounts it feeds.

• `needs_reauth` on a row means the figures behind it have stopped moving, so read this before trusting a synced balance.
• Credentials and provider tokens never appear in the payload.

Takes no query parameters and no body.

curl 'https://ovolos.ai/api/v1/connections' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/connections", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/connections",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 1,
            "provider": "lunchflow",
            "provider_name": "Lunch Flow",
            "status": "active",
            "health": "healthy",
            "health_label": "Healthy",
            "needs_reauth": false,
            "consecutive_failures": 0,
            "in_backoff": false,
            "backoff_until": null,
            "connected_at": "2026-02-01T08:00:00+00:00",
            "last_synced_at": "2026-06-15T04:15:00+00:00",
            "last_attempted_at": "2026-06-15T04:15:00+00:00",
            "accounts_live": 1,
            "accounts": [
                {
                    "id": 14,
                    "name": "Northbank Joint Account",
                    "institution": "Northbank",
                    "currency": "EUR",
                    "archived": false,
                    "last_synced_at": "2026-06-15T04:15:00+00:00",
                    "consent_expires_at": null
                }
            ]
        }
    ],
    "meta": {
        "count": 1
    }
}

Ask one connection to re-pull: account discovery first, then a per-account refresh fanned out behind it, with the connection's current `health` alongside.

• The 202 means queued, not synced. Nothing has pulled when this returns; poll the connection list for a moved `last_synced_at`.
• Every call spends a bank aggregator's rate limit, and a retried timeout that does not carry the original Idempotency-Key queues a second pull against a provider that answers that with a block.
• A connection whose credentials the provider has already rejected still queues, and the job will run and fail — read `health` before spending the next call on it.
• A connection the user disconnected answers 200 with `meta.queued: false` and a reason rather than a 202 for a job that provably does nothing.

Takes no query parameters and no body.

curl -X POST 'https://ovolos.ai/api/v1/connections/1/sync' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/connections/1/sync", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/connections/1/sync",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "connection_id": 1,
        "provider": "lunchflow",
        "health": "healthy"
    },
    "meta": {
        "queued": true
    }
}

Refresh one linked account instead of the whole connection, for a client that knows which balance is stale.

• It spends the provider's rate limit like the connection-wide sync, and a retried timeout that drops the original Idempotency-Key queues a second pull.
• An account that is not linked, is archived, or whose connection is disconnected answers 200 with `meta.queued: false` and a reason.

Takes no query parameters and no body.

curl -X POST 'https://ovolos.ai/api/v1/accounts/14/sync' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/accounts/14/sync", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/14/sync",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "account_id": 14,
        "connection_id": 1
    },
    "meta": {
        "queued": true
    }
}

Forget a connection and unlink its accounts. The accounts survive as ordinary manual entries keeping every valuation and transaction already imported, `accounts_unlinked` says how many, and no figure moves.

• `meta.revoked_at_provider: false` means the provider kept its side: the row stays `disconnected` so the revocation can be retried, and the bank has not yet let go of the data.
• The unlink is applied before the provider call, so a failed revocation still leaves the accounts usable.

Takes no query parameters and no body.

curl -X DELETE 'https://ovolos.ai/api/v1/connections/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/connections/1", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/connections/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "connection_id": 1,
        "provider": "lunchflow",
        "accounts_unlinked": 1
    },
    "meta": {
        "revoked_at_provider": true
    }
}

Income, spending, net and the category breakdown for one month, plus the six months of flows ending with it.

• Income and spending honour each category's "counts as an expense" flag rather than the sign, so a transfer between your own accounts is neither. The transactions list totals the same rows by sign.
• `monthly_flows` is anchored on the month you asked for, not on today.

Assistant equivalent: spending_summary

curl 'https://ovolos.ai/api/v1/spending/summary' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/spending/summary", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/spending/summary",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "month": "2026-06",
        "currency": "EUR",
        "summary": {
            "income": 6400,
            "spending": 3201.09,
            "net": 3198.91,
            "count": 8
        },
        "by_category": [
            {
                "category": "housing",
                "label": "Housing",
                "color": "#a98bff",
                "value": 1420,
                "pct": 44.4
            },
            {
                "category": "uncategorized",
                "label": "Uncategorized",
                "color": "#8a94a6",
                "value": 1258.2,
                "pct": 39.3
            },
            {
                "category": "groceries",
                "label": "Groceries",
                "color": "#2ee6b6",
                "value": 420.5,
                "pct": 13.1
            },
            {
                "category": "dining",
                "label": "Dining & Takeout",
                "color": "#ffcc5c",
                "value": 86.4,
                "pct": 2.7
            },
            {
                "category": "entertainment",
                "label": "Entertainment",
                "color": "#ff9f5c",
                "value": 15.99,
                "pct": 0.5
            }
        ],
        "monthly_flows": [
            {
                "month": "2026-01",
                "label": "Jan 26",
                "income": 0,
                "spending": 0
            },
            {
                "month": "2026-02",
                "label": "Feb 26",
                "income": 0,
                "spending": 0
            },
… 27 more lines, trimmed for reading. The committed capture is whole.

Month-by-month flows over a window ending with the month in progress, the headline figures the spending dashboard leads with, the savings rate over time, and the category split across the whole window.

• `headline.average_spend` averages only the completed months that had any spending: a month with nothing spent is absent from the denominator rather than a zero in it.
• `headline.current_delta_pct` compares the partial current month against that average, so early in a month it reads far below.
• `headline.savings_rate_pct` aggregates the whole period including the partial month; `savings_rate_series.average` is the mean of per-month rates, excludes the partial month, and skips months with no income. Name which one you quote.
• The series covers the last N complete months, so it ends one month before `meta.to`; its own bounds are `savings_rate_series.first_month` and `.last_month`.

Assistant equivalent: spending_trends

curl 'https://ovolos.ai/api/v1/spending/trends' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/spending/trends", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/spending/trends",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "headline": {
            "average_spend": 710.59,
            "current_spend": 3201.09,
            "current_delta_pct": 350,
            "highest_month": {
                "label": "Jun 26",
                "spending": 3201.09
            },
            "savings_rate_pct": 76
        },
        "savings_rate_series": {
            "first_month": "2025-06",
            "last_month": "2026-05",
            "series": [
                {
                    "month": "2025-06",
                    "label": "Jun 25",
                    "rate": null
                },
                {
                    "month": "2025-07",
                    "label": "Jul 25",
                    "rate": null
                },
                {
                    "month": "2025-08",
                    "label": "Aug 25",
                    "rate": null
                },
                {
                    "month": "2025-09",
                    "label": "Sep 25",
                    "rate": null
                },
                {
                    "month": "2025-10",
                    "label": "Oct 25",
                    "rate": null
                },
                {
                    "month": "2025-11",
                    "label": "Nov 25",
                    "rate": null
                },
                {
                    "month": "2025-12",
                    "label": "Dec 25",
                    "rate": null
                },
                {
                    "month": "2026-01",
                    "label": "Jan 26",
                    "rate": null
                },
                {
                    "month": "2026-02",
                    "label": "Feb 26",
                    "rate": null
… 151 more lines, trimmed for reading. The committed capture is whole.

The biggest spending destinations by name over the window, each with what was spent there and how many charges made it up, biggest first.

• Charges are grouped by description folded to lower case, so a bank that appends a store number ("TESCO 4471", "TESCO 8890") splits one shop across rows.
• Only categories that count as an expense appear, so a transfer to a named payee or the purchase of an asset is absent here while the transactions list carries it.
• To open a row, pass its `name` through unchanged to GET /spending/transactions as `merchant`.

Assistant equivalent: top_merchants

curl 'https://ovolos.ai/api/v1/spending/merchants' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/spending/merchants", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/spending/merchants",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "name": "Kifissia mortgage",
            "total": 1420,
            "count": 1
        },
        {
            "name": "Supermarket weekly shop",
            "total": 1261.5,
            "count": 3
        },
        {
            "name": "Card payment",
            "total": 1200,
            "count": 1
        },
        {
            "name": "Annual service",
            "total": 640,
            "count": 1
        },
        {
            "name": "Taverna Kifissia",
            "total": 259.2,
            "count": 3
        },
        {
            "name": "Building charges",
            "total": 240,
            "count": 1
        },
        {
            "name": "Insurance",
            "total": 190,
            "count": 1
        },
        {
            "name": "Netflix",
            "total": 63.96,
            "count": 4
        }
    ],
    "meta": {
        "currency": "EUR",
        "months": 12,
        "from": "2025-07-01",
        "to": "2026-06-15",
        "limit": 8,
        "count": 8,
        "grouping": "Charges are grouped by description, folded to lower case and trimmed, so \"TESCO\" and \"Tesco \" are one merchant. `name` is that merchant as it was written on one of the charges. A bank that numbers its descriptions (\"TESCO 4471\") will therefore split across rows — that is the ledger being specific, not a fault in the grouping.",
        "drill_down": "To list the individual charges behind a row, call GET /api/v1/spending/transactions with merchant=<name>, from=2025-07-01 and direction=spend. `merchant` matches on the same folded key this list groups by.",
        "reconciliation": "A row totals only the charges in categories that COUNT AS AN EXPENSE, so a transfer or an asset purchase to the same payee is excluded here and included by the transactions list, whose meta.totals goes by sign alone. Merchant totals also convert each charge at its own date's rate, where meta.totals converts at today's. In a single-currency portfolio only the first difference can bite."
    }
}

Budgets with live over/under state, the rollup, and categories spending without a budget.

Assistant equivalent: budgets

curl 'https://ovolos.ai/api/v1/spending/budgets' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/spending/budgets", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/spending/budgets",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "month": "2026-06",
        "currency": "EUR",
        "budgets": [
            {
                "id": 1,
                "category": "groceries",
                "label": "Groceries",
                "color": "#2ee6b6",
                "limit": 600,
                "actual": 420.5,
                "remaining": 179.5,
                "pct": 70.1,
                "state": "under",
                "projectedEndOfMonth": 841,
                "rollover": false,
                "is_active": true
            },
            {
                "id": 2,
                "category": "dining",
                "label": "Dining & Takeout",
                "color": "#ffcc5c",
                "limit": 250,
                "actual": 86.4,
                "remaining": 163.6,
                "pct": 34.6,
                "state": "under",
                "projectedEndOfMonth": 172.8,
                "rollover": true,
                "is_active": true
            }
        ],
        "summary": {
            "totalLimit": 850,
            "totalActual": 506.9,
            "totalRemaining": 343.1,
            "overCount": 0
        },
        "unbudgeted": [
            {
                "category": "housing",
                "label": "Housing",
                "color": "#a98bff",
                "actual": 1420
            },
            {
                "category": "uncategorized",
                "label": "Uncategorized",
                "color": "#8a94a6",
                "actual": 1258.2
            },
            {
                "category": "entertainment",
                "label": "Entertainment",
                "color": "#ff9f5c",
                "actual": 15.99
            }
        ]
… 2 more lines, trimmed for reading. The committed capture is whole.

A suggested monthly limit for every category with spending in the last three completed months — what the app's one-click "Build my budget" would write, without writing it.

• The divisor is a fixed three whatever the category did, so something bought once in those months is suggested at a third of its price.
• The month in progress is excluded, and there is no window parameter.
• Only categories with spending in that window appear: a category you budget for and did not spend in is simply absent, which is not a suggestion to remove its budget.
• `current_limit` is what the matching PUT would replace, null where the category has no budget yet, and `current_rollover` must be resent with the limit or the flag is silently cleared.
• Figures are whole units, not cents.

Takes no query parameters and no body.

Assistant equivalent: suggested_budgets

curl 'https://ovolos.ai/api/v1/spending/budgets/suggestions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/spending/budgets/suggestions", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/spending/budgets/suggestions",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "category": "groceries",
            "label": "Groceries",
            "color": "#2ee6b6",
            "suggested": 280,
            "current_limit": 600,
            "current_rollover": false
        },
        {
            "category": "transport",
            "label": "Transport",
            "color": "#5cb2ff",
            "suggested": 277,
            "current_limit": null,
            "current_rollover": null
        },
        {
            "category": "housing",
            "label": "Housing",
            "color": "#a98bff",
            "suggested": 80,
            "current_limit": null,
            "current_rollover": null
        },
        {
            "category": "dining",
            "label": "Dining & Takeout",
            "color": "#ffcc5c",
            "suggested": 58,
            "current_limit": 250,
            "current_rollover": true
        },
        {
            "category": "entertainment",
            "label": "Entertainment",
            "color": "#ff9f5c",
            "suggested": 16,
            "current_limit": null,
            "current_rollover": null
        }
    ],
    "meta": {
        "currency": "EUR",
        "count": 5,
        "new_budgets": 3,
        "replaces_existing": 2,
        "window": {
            "from": "2026-03",
            "to": "2026-05",
            "months": 3
        },
        "basis": "Each suggestion is that category's total spend over the three COMPLETED months above, divided by three and rounded to a whole unit. The divisor is a fixed three whatever the category did: something bought once in one of those months is suggested at a third of its price, not at its price. The month in progress is excluded entirely, so a suggestion does not move as the month goes on. There is no month or window argument — the app has none either, and one here would only be a way for the two to disagree.",
        "coverage": "Only categories with spending in that window appear, so a category the user budgets for and did not spend in is absent — that is not a suggestion to remove its budget. Suggestions that round to zero are dropped, because a limit of zero is a budget that is permanently over.",
        "apply": "These are a proposal; nothing is written until you write it. Apply one with set_budget (MCP) or PUT /api/v1/spending/budgets/{category} (REST), sending limit_amount: <suggested> and the row's `category` as the key. Where current_limit is not null the write REPLACES that limit — say so before doing it — and because every writer rebuilds the whole row, resend rollover: <current_rollover> or the flag is cleared. Nothing here writes anything and calling it twice changes nothing."
    }
}

Transactions over any date window, newest first, with search, amount, direction and category filters, in native signed amounts. Each row carries the asset a cost belongs to and the loan a payment pays down, with its principal/interest split.

• `reduces_loan_balance`, not `principal_amount > 0`, says whether the row really moved a debt: a payment dated on or before the loan's newest hand-entered valuation reports false.
• `interest_amount` is recorded and totalled nowhere in Ovolos, on any surface.
• `meta.totals` covers the whole filtered set rather than the page, so never build a total by adding up `data`.
• `meta.totals` goes by each amount's sign and converts at today's rate; /spending/summary and /spending/trends go by the category's expense flag and convert at each transaction's date.
• Under the default `moves=exclude` those two rules see the same rows, so `meta.totals.net` equals the net /spending/summary reports over the same dates. `moves=include` counts a transfer on both sides and breaks that.
• `meta.totals.unconverted` lists source currencies that had no rate on file and were added at face value; while it is non-empty the three money figures are a mixed-currency sum under one label.

Assistant equivalent: list_transactions

curl 'https://ovolos.ai/api/v1/spending/transactions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/spending/transactions", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/spending/transactions",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 21,
            "made_on": "2026-06-12",
            "description": "PADDLE.NET* SOFTWARE",
            "amount": -58.2,
            "currency": "EUR",
            "category": {
                "value": "uncategorized",
                "label": "Uncategorized"
            },
            "pending": false,
            "category_source": "rules",
            "account": {
                "id": 1,
                "name": "Everyday Current Account"
            },
            "asset_account_id": null,
            "linked_asset": null,
            "loan_account_id": null,
            "linked_loan": null,
            "principal_amount": null,
            "interest_amount": null,
            "reduces_loan_balance": false,
            "updated_at": "2026-06-15T12:00:00+00:00"
        },
        {
            "id": 14,
            "made_on": "2026-06-11",
            "description": "Taverna Kifissia",
            "amount": -86.4,
            "currency": "EUR",
            "category": {
                "value": "dining",
                "label": "Dining & Takeout"
            },
            "pending": false,
            "category_source": "user",
            "account": {
                "id": 13,
                "name": "Everyday Credit Card"
            },
            "asset_account_id": null,
            "linked_asset": null,
            "loan_account_id": null,
            "linked_loan": null,
            "principal_amount": null,
            "interest_amount": null,
            "reduces_loan_balance": false,
            "updated_at": "2026-06-15T12:00:00+00:00"
        },
        {
            "id": 4,
            "made_on": "2026-06-10",
            "description": "Northbank salary",
            "amount": 5200,
            "currency": "EUR",
            "category": {
                "value": "income",
… 190 more lines, trimmed for reading. The committed capture is whole.

Detected recurring charges — subscriptions and standing payments — each with name, category, cadence, monthly-equivalent cost and how many times it has been seen.

• A row's `key` only means anything inside the window it was listed in, so send the same `months` back to POST /spending/subscriptions/{key}/plan.

Assistant equivalent: list_subscriptions

curl 'https://ovolos.ai/api/v1/spending/subscriptions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/spending/subscriptions", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/spending/subscriptions",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "currency": "EUR",
        "months": 12,
        "min_occurrences": 3,
        "count": 3,
        "total_monthly": 522.89,
        "subscriptions": [
            {
                "key": "supermarket weekly shop",
                "name": "Supermarket weekly shop",
                "category": {
                    "value": "groceries",
                    "label": "Groceries"
                },
                "amount": 420.5,
                "currency": "EUR",
                "cadence": {
                    "value": "monthly",
                    "label": "Monthly"
                },
                "monthly_equivalent": 420.5,
                "occurrences": 3,
                "first_date": "2026-04-03",
                "last_date": "2026-06-02"
            },
            {
                "key": "taverna kifissia",
                "name": "Taverna Kifissia",
                "category": {
                    "value": "dining",
                    "label": "Dining & Takeout"
                },
                "amount": 86.4,
                "currency": "EUR",
                "cadence": {
                    "value": "monthly",
                    "label": "Monthly"
                },
                "monthly_equivalent": 86.4,
                "occurrences": 3,
                "first_date": "2026-04-12",
                "last_date": "2026-06-11"
            },
            {
                "key": "netflix",
                "name": "Netflix",
                "category": {
                    "value": "entertainment",
                    "label": "Entertainment"
                },
                "amount": 15.99,
                "currency": "EUR",
                "cadence": {
                    "value": "monthly",
                    "label": "Monthly"
                },
                "monthly_equivalent": 15.99,
                "occurrences": 4,
                "first_date": "2026-03-08",
… 5 more lines, trimmed for reading. The committed capture is whole.

Recategorise one transaction, answering with the whole updated row.

• The write marks the category as chosen by a person, which is what stops the next provider sync reverting it.

Assistant equivalent: categorize_transaction

curl -X PATCH 'https://ovolos.ai/api/v1/spending/transactions/21' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "category": "shopping"
  }'

const response = await fetch("https://ovolos.ai/api/v1/spending/transactions/21", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "category": "shopping"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/spending/transactions/21",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "category": "shopping",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 21,
        "made_on": "2026-06-12",
        "description": "PADDLE.NET* SOFTWARE",
        "amount": -58.2,
        "currency": "EUR",
        "category": {
            "value": "shopping",
            "label": "Shopping"
        },
        "pending": false,
        "category_source": "user",
        "account": {
            "id": 1,
            "name": "Everyday Current Account"
        },
        "asset_account_id": null,
        "linked_asset": null,
        "loan_account_id": null,
        "linked_loan": null,
        "principal_amount": null,
        "interest_amount": null,
        "reduces_loan_balance": false,
        "updated_at": "2026-06-15T12:00:00+00:00"
    }
}

Recategorise an explicit list of transactions, all to the same category, reporting how many rows moved.

• Each row is marked as a person's decision and survives the next sync, exactly as the single write does.
• `updated` is reported separately from `requested`: an id belonging to another portfolio does not match, and is absent rather than refused.

Assistant equivalent: categorize_transactions

curl -X POST 'https://ovolos.ai/api/v1/spending/transactions/categorize' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "ids": [
          21
      ],
      "category": "shopping"
  }'

const response = await fetch("https://ovolos.ai/api/v1/spending/transactions/categorize", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "ids": [
          21
      ],
      "category": "shopping"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/spending/transactions/categorize",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "ids": [
            21,
        ],
        "category": "shopping",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "updated": 1,
        "category": "shopping"
    },
    "meta": {
        "requested": 1
    }
}

Set a category's monthly limit, returning the stored budget.

• The category is the natural key, so this is an upsert and repeating it changes nothing.
• Deleting is the only way to stop one: nothing on any surface switches a budget off, so a limit set against the wrong category keeps counting until it goes.

Assistant equivalent: set_budget

curl -X PUT 'https://ovolos.ai/api/v1/spending/budgets/groceries' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "limit_amount": 650
  }'

const response = await fetch("https://ovolos.ai/api/v1/spending/budgets/groceries", {
  method: "PUT",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "limit_amount": 650
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.put(
    "https://ovolos.ai/api/v1/spending/budgets/groceries",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "limit_amount": 650,
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 1,
        "category": {
            "value": "groceries",
            "label": "Groceries"
        },
        "limit_amount": 650,
        "rollover": false,
        "is_active": true,
        "updated_at": "2026-06-15T12:00:00+00:00"
    }
}

Stop tracking a category against a limit, keyed on the category exactly like the PUT above — there is no id to hold.

• It removes a plan, never a measurement: the transactions, the totals and every historical figure are untouched.
• Safe-to-spend goes up, because an unspent budget counts as committed.
• 404 tells "you have no limit on that category" apart from "that is not one of your categories".

Takes no query parameters and no body.

Assistant equivalent: delete_budget

curl -X DELETE 'https://ovolos.ai/api/v1/spending/budgets/dining' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/spending/budgets/dining", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/spending/budgets/dining",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true,
        "category": {
            "value": "dining",
            "label": "Dining & Takeout"
        },
        "limit_amount": 250
    },
    "meta": {
        "currency": "EUR",
        "remaining": 1,
        "remaining_total_limit": 600
    }
}

Record one payment or deposit that has already happened, on the account the money moved through — optionally filed against the asset it was spent on, or pointed at the loan it pays down.

• `amount` is always positive and `direction` (out | in) carries the sign; the row is stored in the account's currency whatever you quote.
• `asset_account_id` files the cost against a physical asset and moves no money — the debit still comes out of the account in the path.
• `loan_account_id` does move a figure: the loan's balance comes down by `principal_amount` and nothing else. Send neither part of the split and Ovolos derives it as the app does.
• `interest_amount` is recorded for the user and moves nothing: no report, total or budget in Ovolos adds interest paid up.
• Read `meta.loan` rather than assuming: a payment dated on or before the loan's newest hand-entered valuation is already inside that balance and reports `reduces_loan_balance` false.
• 409 `account_sold` on an account marked sold: undo the sale with DELETE /accounts/{id}/sale, or record this against whatever account holds the money now.
• 409 `account_has_no_ledger` on anything but checking, savings, cash and credit card.

Assistant equivalent: add_transaction

curl -X POST 'https://ovolos.ai/api/v1/accounts/1/transactions' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "made_on": "2026-06-13",
      "direction": "out",
      "amount": 148.6,
      "category": "health"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/1/transactions", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "made_on": "2026-06-13",
      "direction": "out",
      "amount": 148.6,
      "category": "health"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/1/transactions",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "made_on": "2026-06-13",
        "direction": "out",
        "amount": 148.6,
        "category": "health",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 22,
        "made_on": "2026-06-13",
        "description": null,
        "amount": -148.6,
        "currency": "EUR",
        "category": {
            "value": "health",
            "label": "Health"
        },
        "pending": false,
        "category_source": "user",
        "account": {
            "id": 1,
            "name": "Everyday Current Account"
        },
        "asset_account_id": null,
        "linked_asset": null,
        "loan_account_id": null,
        "linked_loan": null,
        "principal_amount": null,
        "interest_amount": null,
        "reduces_loan_balance": false,
        "updated_at": "2026-06-15T12:00:00+00:00"
    }
}

Import a statement: many transactions onto one account in one call, as rows rather than a file, validated to exactly the standard of the single write above.

• The amount is a direction plus an unsigned figure, not whatever sign the file carried, and a future-dated row is refused.
• Validated whole, then written whole: one bad row refuses the file and imports nothing, naming every failing index at once.
• Duplicates are skipped and reported with the id they matched — same day, same signed amount to the cent, same description, no time limit, bank-synced rows included.
• Two genuinely separate identical payments look like a repeat, and `allow_duplicates` is for that case only.
• A row carrying a category is stamped as the user's own decision and never re-categorised, so leave it out unless the source really says what the payment was.
• An imported row carries no links: a mortgage payment lands as ordinary spending and reduces no debt until the PATCH below points it at its loan.
• 409 `account_has_no_ledger` on anything but checking, savings, cash and credit card: it writes one valuation per transaction day, which elsewhere overwrites a hand-built value history irrecoverably.
• 409 `account_sold` on an account marked sold.

Assistant equivalent: import_transactions

curl -X POST 'https://ovolos.ai/api/v1/accounts/1/transactions/import' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "rows": [
          {
              "made_on": "2026-06-01",
              "direction": "out",
              "amount": 62.4,
              "description": "Bakery",
              "category": "groceries"
          },
          {
              "made_on": "2026-06-02",
              "direction": "in",
              "amount": 120.0,
              "description": "Refund",
              "category": "shopping"
          }
      ]
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/1/transactions/import", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "rows": [
          {
              "made_on": "2026-06-01",
              "direction": "out",
              "amount": 62.4,
              "description": "Bakery",
              "category": "groceries"
          },
          {
              "made_on": "2026-06-02",
              "direction": "in",
              "amount": 120.0,
              "description": "Refund",
              "category": "shopping"
          }
      ]
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/accounts/1/transactions/import",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "rows": [
            {
                "made_on": "2026-06-01",
                "direction": "out",
                "amount": 62.4,
                "description": "Bakery",
                "category": "groceries",
            },
            {
                "made_on": "2026-06-02",
                "direction": "in",
                "amount": 120.0,
                "description": "Refund",
                "category": "shopping",
            },
        ],
    },
)

print(response.status_code, response.text)

{
    "data": {
        "account_id": 1,
        "name": "Everyday Current Account",
        "imported": 2,
        "skipped_duplicate": 0,
        "requested": 2,
        "rows": [
            {
                "index": 0,
                "status": "imported",
                "transaction_id": 22,
                "made_on": "2026-06-01",
                "amount": -62.4,
                "description": "Bakery",
                "category": "groceries",
                "duplicate_of": null
            },
            {
                "index": 1,
                "status": "imported",
                "transaction_id": 23,
                "made_on": "2026-06-02",
                "amount": 120,
                "description": "Refund",
                "category": "shopping",
                "duplicate_of": null
            }
        ]
    },
    "meta": {
        "currency": "EUR",
        "takes": "rows",
        "max_per_call": 500,
        "account_currency": "EUR",
        "value_before": 26750,
        "value_after": 26750,
        "earliest_row": "2026-06-01",
        "latest_row": "2026-06-02",
        "ledger_size": 19,
        "rows_remaining": 1498,
        "rows_per_hour": 1500,
        "duplicate_rule": "A row is a duplicate of one already on this account with the same day, the same signed amount to the cent, and the same description — including when both descriptions are absent. It has no time limit, so re-sending last year's statement imports nothing, and it compares against bank-fed rows too, so a payment the feed already holds is not duplicated. Two genuinely separate same-day payments of the same amount with no description are indistinguishable from a repeat: send allow_duplicates: true for that case only.",
        "note": "Every row landed with category_source \"import\" unless it named a category, in which case it is stamped as the user's own choice and the AI categoriser will preserve it. Leave category out to have Ovolos classify the row later. Imported rows carry no asset attribution and no loan link: a repayment imported here is ordinary spending until it is pointed at its loan with PATCH /api/v1/accounts/1/transactions/{id}."
    }
}

Correct one transaction. A partial edit: every field you leave out keeps its stored value, the links included — a PATCH that says nothing about the loan does not detach the repayment.

• Sending `loan_account_id: null` detaches the payment and puts the loan's balance back up by the principal it was repaying. Moving it to another loan corrects both balances.
• `meta.loan` reports the balance either side of the edit for the loan the row now points at, and is absent on a detach — where the figure going back up belongs to the loan the row is leaving.
• 409 `provider_sourced` for a change to the amount, date or description of a bank-fed row, which the next sync would undo. The category, the asset and the loan split are yours on any row.
• 409 `account_sold` on an account marked sold, checked before the provider rule because only the sale has an undo.

Assistant equivalent: update_transaction

curl -X PATCH 'https://ovolos.ai/api/v1/accounts/1/transactions/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -H 'If-Match: THE_ETAG_FROM_YOUR_LAST_READ' \
  -d '{
      "description": "Northbank salary (revised)"
  }'

const response = await fetch("https://ovolos.ai/api/v1/accounts/1/transactions/1", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
  },
  body: JSON.stringify({
      "description": "Northbank salary (revised)"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/accounts/1/transactions/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
        "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
    },
    json={
        "description": "Northbank salary (revised)",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 1,
        "made_on": "2026-03-25",
        "description": "Northbank salary (revised)",
        "amount": 5200,
        "currency": "EUR",
        "category": {
            "value": "income",
            "label": "Income"
        },
        "pending": false,
        "category_source": "user",
        "account": {
            "id": 1,
            "name": "Everyday Current Account"
        },
        "asset_account_id": null,
        "linked_asset": null,
        "loan_account_id": null,
        "linked_loan": null,
        "principal_amount": null,
        "interest_amount": null,
        "reduces_loan_balance": false,
        "updated_at": "2026-06-15T12:00:00+00:00"
    }
}

Remove one manually entered transaction. The account's balance history is rebuilt in the same database transaction, because removing a row moves every derived balance after its date.

• A row that was paying down a loan takes its repayment with it, so that debt goes back up by the principal; `meta` says by how much and where the balance landed.
• 409 `provider_sourced` for a row that came from a bank feed, which the next sync upserts straight back. Change those at the source; the category is still yours.
• 409 `account_sold` on an account marked sold — undo the sale first.

Takes no query parameters and no body.

Assistant equivalent: delete_transaction

curl -X DELETE 'https://ovolos.ai/api/v1/accounts/1/transactions/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/accounts/1/transactions/1", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/accounts/1/transactions/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true,
        "id": 1
    },
    "meta": {
        "loan_account_id": null,
        "principal_restored": null,
        "loan_balance_after": null
    }
}

Pair up money moved between the user's own accounts so both legs stop counting as spending and as income.

• It usually removes money that was never really spent, so spending totals, the category breakdown, budgets and safe-to-spend all move.
• It considers only rows nobody has categorised by hand, so a category the user chose is never overwritten.
• A second run finds only what is newly pairable, so it is safe to repeat.
• `linked_legs` and `linked_pairs` are one result counted two ways.

Takes no query parameters and no body.

Assistant equivalent: find_transfers

curl -X POST 'https://ovolos.ai/api/v1/spending/find-transfers' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/spending/find-transfers", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/spending/find-transfers",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "linked_legs": 2,
        "linked_pairs": 1
    },
    "meta": {
        "unchanged": false
    }
}

Turn a recurring charge the detector already found into a planned expense, which moves the cash-flow projection, safe-to-spend, the runway and the upcoming feed immediately.

• Nothing about the plan comes from the request: the name, amount, currency, category and cadence are all the detector's.
• `{key}` is what GET /spending/subscriptions returned, it may contain slashes, and it only means anything inside the window it was listed in — so send back the same `months` and `min_occurrences`.
• Planning the same subscription twice hands back the plan that already exists rather than adding a second.

Assistant equivalent: plan_subscription

curl -X POST 'https://ovolos.ai/api/v1/spending/subscriptions/netflix/plan' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/spending/subscriptions/netflix/plan", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/spending/subscriptions/netflix/plan",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 3,
        "name": "Netflix",
        "direction": "expense",
        "amount": 15.99,
        "signed_amount": -15.99,
        "currency": "EUR",
        "category": {
            "value": "entertainment",
            "label": "Entertainment"
        },
        "cadence": "monthly",
        "interval": 1,
        "anchor_date": "2026-07-08",
        "day_rule": "exact",
        "ends_on": null,
        "occurrences_cap": null,
        "notes": null,
        "is_active": true,
        "updated_at": "2026-06-15T12:00:00+00:00"
    },
    "meta": {
        "unchanged": false
    }
}

Hand the still-uncategorised transactions to Claude and let it label them. It answers 202 and means it: nothing is categorised when it returns.

• This spends the portfolio owner's money — it bills an AI pass, so a retry that does not carry the same Idempotency-Key buys a second pass over the same rows.
• `pending` is counted with exactly the job's own filter, so it is the number of rows that will really be looked at.
• It takes no ids and no filter: the set is derived from the acting portfolio, and a row somebody categorised by hand is never touched.

Takes no query parameters and no body.

curl -X POST 'https://ovolos.ai/api/v1/spending/auto-categorize' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/spending/auto-categorize", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/spending/auto-categorize",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "status": "queued",
        "pending": 3
    },
    "meta": {
        "queued": true
    }
}

A month-by-month cash-flow projection: the seed balance and the date it was taken from, projected inflow, outflow and net per month, the running end balance, the low-water point, and the recurring monthly totals feeding it.

• It seeds from liquid cash at `seed.date`, the most recent liquid-cash valuation date and not necessarily today. /planning/runway starts from a wider pool, so the two opening figures differ.
• The lowest point ahead is always reported; `low_water.is_negative` and `low_water.shortfall` are what say whether it goes under.

Assistant equivalent: cash_flow_projection

curl 'https://ovolos.ai/api/v1/planning/cash-flow' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/planning/cash-flow", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/planning/cash-flow",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "currency": "EUR",
        "months": 12,
        "seed": {
            "date": "2026-06-14",
            "balance": 75950
        },
        "end_balance": 118790,
        "net_monthly": 3570,
        "low_water": {
            "date": "2026-06-18",
            "amount": 75550,
            "is_negative": false,
            "shortfall": 0
        },
        "by_month": [
            {
                "month": "2026-06",
                "label": "Jun 26",
                "inflow": 5200,
                "outflow": 400,
                "net": 4800,
                "end_balance": 80750
            },
            {
                "month": "2026-07",
                "label": "Jul 26",
                "inflow": 5200,
                "outflow": 2030,
                "net": 3170,
                "end_balance": 83920
            },
            {
                "month": "2026-08",
                "label": "Aug 26",
                "inflow": 5200,
                "outflow": 2030,
                "net": 3170,
                "end_balance": 87090
            },
            {
                "month": "2026-09",
                "label": "Sep 26",
                "inflow": 5200,
                "outflow": 2030,
                "net": 3170,
                "end_balance": 90260
            },
            {
                "month": "2026-10",
                "label": "Oct 26",
                "inflow": 5200,
                "outflow": 2030,
                "net": 3170,
                "end_balance": 93430
            },
            {
                "month": "2026-11",
                "label": "Nov 26",
… 70 more lines, trimmed for reading. The committed capture is whole.

What is discretionary this month after known commitments: projected income, the committed total, the free remainder, and an itemised breakdown of what made up `committed`.

• `committed` is planned outgoings, liability payments, and the still-unspent limit of any budgeted category no occurrence already covers.
• A planned item and a liability's own `monthly_payment` are counted separately: nothing records that they are the same debt, so entering both counts it twice. `exclude_from_plan` on the account drops the derived one.
• A description of this month's arithmetic, not advice.

Assistant equivalent: safe_to_spend

curl 'https://ovolos.ai/api/v1/planning/safe-to-spend' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/planning/safe-to-spend", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/planning/safe-to-spend",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "month": "2026-06",
        "currency": "EUR",
        "income": 5200,
        "committed": 2880,
        "free": 2320,
        "breakdown": [
            {
                "label": "Planned & liability outgoings",
                "amount": 2030
            },
            {
                "label": "Budgeted (uncommitted categories)",
                "amount": 850
            }
        ]
    }
}

Recurring income derived from the accounts themselves — rent from a property marked as a rental, and interest from a term deposit that pays out — each as a monthly equivalent at your ownership share, with the rolled-up total.

• `meta.monthly_total` is not all the recurring income there is: a salary is a planned item, and this list and the plan list never overlap by construction.
• Read `meta.manual_income_overlap` before quoting `meta.monthly_total`: an active planned income item can double-count the same rent or interest and overstate every forward figure.
• That flag compares no names and no amounts; `meta.manual_income_warning` is the sentence to relay.
• A source whose currency has no rate on file is dropped rather than summed raw, so the total never quietly mixes currencies.

Assistant equivalent: income_sources

curl 'https://ovolos.ai/api/v1/planning/income-sources' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/planning/income-sources", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/planning/income-sources",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [],
    "meta": {
        "currency": "EUR",
        "count": 0,
        "monthly_total": 0,
        "manual_income_overlap": false,
        "manual_income_warning": null
    }
}

How long the liquid and marketable assets would last with zero income, drawn down at the recent average spend: a status, months remaining, the depletion month, the liquid pool and the spend average. `meta` carries a rule string behind each figure.

• Read `status`, not `months`: `months` is null both for `sustainable` and for `no_data`, which are opposites, so branching on null alone reports "no runway" for the portfolio doing best.
• Money moved into investments is not spend — it changed form, and the assets it became are already inside `liquid`.
• `growth.rate_pct` and `growth.annual_amount` are null with `requested: true` when there is no usable recent return: that is none on record, not a return of zero.
• Growth compounds the marketable slice only, at its own trailing twelve-month return; that twelve is fixed and is not `window`.

Assistant equivalent: survival_runway

curl 'https://ovolos.ai/api/v1/planning/runway' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/planning/runway", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/planning/runway",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "status": "depleting",
        "months": 171.2,
        "depletion_month": "2040-09",
        "depletion_label": "Sep 2040",
        "liquid": 121650,
        "monthly_spend": 710.59,
        "months_counted": 3,
        "growth": {
            "requested": false,
            "rate_pct": null,
            "annual_amount": null
        }
    },
    "meta": {
        "currency": "EUR",
        "window_months": 6,
        "status_rule": "status is \"depleting\" (months is a real number), \"sustainable\" (growth covers the withdrawals, so months is null because the runway does not end) or \"no_data\" (no recent spending to average, so months is null because it is unknown). months is null in TWO of those three and they mean opposite things — read status, not months, to decide what to say.",
        "spend_rule": "monthly_spend averages the last 6 COMPLETED months, dropping the month in progress and counting only months that had any spending — an empty tracking month is absent from the denominator rather than counted as a zero. Money moved into investments is not spending and is excluded from the burn: it changed form, and the assets it became are already in `liquid`. months_counted says how many months actually went into the average, so a 1 there is a runway resting on one month of history.",
        "liquid_rule": "liquid is cash plus marketable assets — what could realistically be raised — from the net-worth side, not the cash balance the cash-flow projection seeds from. Property, vehicles and other illiquid holdings are excluded.",
        "growth_rule": "With growth requested, only the MARKETABLE slice compounds, at its own trailing-12-month organic return (cash is treated as flat), and only a POSITIVE return is applied, so this can never shorten the runway. That 12-month window is fixed and is NOT the `window` argument, which governs the spend average alone. annual_amount is roughly a year of growth on the marketable balance at rate_pct. An illustration that assumes recent returns continue, not a forecast.",
        "depletion_rule": "depletion_month (YYYY-MM) is when the balance reaches zero at that spend; depletion_label is the same instant as a display string. Both are null when the runway is under half a month, when it is sustainable, and when there is no data — a date is not information in any of those."
    }
}

Planned income and bills falling due within a window, dated ascending, each with its amount, category and where it came from.

• Amounts are signed — income positive, outgoings negative — and `is_income` says which without reading the sign.
• `planned_item_id` is the handle every write on a row needs, and is null for derived rows (rent, term-deposit interest, liability payments), which therefore cannot be skipped.

Assistant equivalent: upcoming_items

curl 'https://ovolos.ai/api/v1/planning/upcoming' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/planning/upcoming", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/planning/upcoming",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "date": "2026-06-18",
            "name": "Everyday Credit Card payment",
            "amount": -400,
            "currency": "EUR",
            "is_income": false,
            "category": "fees",
            "category_label": "Fees & Charges",
            "source": "liability",
            "planned_item_id": null
        },
        {
            "date": "2026-06-25",
            "name": "Salary",
            "amount": 5200,
            "currency": "EUR",
            "is_income": true,
            "category": "income",
            "category_label": "Income",
            "source": "planned",
            "planned_item_id": 2
        },
        {
            "date": "2026-07-05",
            "name": "Building service charge",
            "amount": -210,
            "currency": "EUR",
            "is_income": false,
            "category": "housing",
            "category_label": "Housing",
            "source": "planned",
            "planned_item_id": 1
        },
        {
            "date": "2026-07-05",
            "name": "Kifissia Mortgage payment",
            "amount": -1420,
            "currency": "EUR",
            "is_income": false,
            "category": "housing",
            "category_label": "Housing",
            "source": "liability",
            "planned_item_id": null
        }
    ],
    "meta": {
        "currency": "EUR",
        "count": 4,
        "days": 30,
        "from": "2026-06-15",
        "to": "2026-07-15"
    }
}

The alert inbox newest first — runway shortfalls, budget overruns, risk findings, big moves, stale data, AI budget warnings and auto-revaluation outcomes — with the unread total beside it.

• `meta.unread` counts the whole inbox, not the page you are reading.
• `account_id` names the asset when an alert is about one, and `data` carries the figures the body describes in prose; both are null on the alerts about the whole portfolio.
• Only `ai_valuation_review` and `ai_valuation_failed` can be acted on — everything else is a notification whose one affordance is reading it.

Assistant equivalent: list_alerts

curl 'https://ovolos.ai/api/v1/alerts' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/alerts", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.get(
    "https://ovolos.ai/api/v1/alerts",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": [
        {
            "id": 3,
            "type": "weekly_move",
            "severity": {
                "value": "info",
                "label": "Info"
            },
            "title": "Net worth up 1.4% in the week to 9 Jun 2026",
            "body": "Up 12,400.00 EUR over the seven days to 9 Jun 2026. Driven by the brokerage account.",
            "url": null,
            "account_id": null,
            "data": null,
            "is_read": true,
            "read_at": "2026-06-09T08:00:00+00:00",
            "created_at": "2026-06-15T12:00:00+00:00",
            "updated_at": "2026-06-15T12:00:00+00:00"
        },
        {
            "id": 2,
            "type": "ai_valuation_review",
            "severity": {
                "value": "warning",
                "label": "Warning"
            },
            "title": "Family Estate Car was revalued 6% lower",
            "body": "The scheduled research put the car at 29,000 EUR, down from 30,900 EUR.",
            "url": null,
            "account_id": 10,
            "data": {
                "account_id": 10
            },
            "is_read": false,
            "read_at": null,
            "created_at": "2026-06-15T12:00:00+00:00",
            "updated_at": "2026-06-15T12:00:00+00:00"
        },
        {
            "id": 1,
            "type": "stale_account",
            "severity": {
                "value": "warning",
                "label": "Warning"
            },
            "title": "Kifissia Apartment may be out of date",
            "body": "It hasn't been valued since 31 May 2026 — record a fresh value to keep your net worth accurate.",
            "url": null,
            "account_id": 9,
            "data": {
                "account_id": 9,
                "days_since": 15
            },
            "is_read": false,
            "read_at": null,
            "created_at": "2026-06-15T12:00:00+00:00",
            "updated_at": "2026-06-15T12:00:00+00:00"
        }
    ],
    "links": {
… 37 more lines, trimmed for reading. The committed capture is whole.

Create a planned income or expense — amount, direction, category and the recurrence behind it — returning the stored plan.

• Nothing dedups plans: two copies of one rent both count, and the runway, safe-to-spend and the upcoming feed all move until one is deleted.

Assistant equivalent: create_planned_item

curl -X POST 'https://ovolos.ai/api/v1/planning/items' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -d '{
      "name": "Gym membership",
      "direction": "expense",
      "amount": 55,
      "currency": "EUR",
      "category": "health",
      "cadence": "monthly",
      "interval": 1,
      "anchor_date": "2026-07-01"
  }'

const response = await fetch("https://ovolos.ai/api/v1/planning/items", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
  body: JSON.stringify({
      "name": "Gym membership",
      "direction": "expense",
      "amount": 55,
      "currency": "EUR",
      "category": "health",
      "cadence": "monthly",
      "interval": 1,
      "anchor_date": "2026-07-01"
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.post(
    "https://ovolos.ai/api/v1/planning/items",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
    json={
        "name": "Gym membership",
        "direction": "expense",
        "amount": 55,
        "currency": "EUR",
        "category": "health",
        "cadence": "monthly",
        "interval": 1,
        "anchor_date": "2026-07-01",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 3,
        "name": "Gym membership",
        "direction": "expense",
        "amount": 55,
        "signed_amount": -55,
        "currency": "EUR",
        "category": {
            "value": "health",
            "label": "Health"
        },
        "cadence": "monthly",
        "interval": 1,
        "anchor_date": "2026-07-01",
        "day_rule": null,
        "ends_on": null,
        "occurrences_cap": null,
        "notes": null,
        "is_active": true,
        "updated_at": "2026-06-15T12:00:00+00:00"
    }
}

Edit a plan, including pausing it with `is_active: false`. Returns the stored plan.

• Fields you omit keep their stored values, and the cross-field rules are checked against those stored values rather than against your payload alone.

Assistant equivalent: update_planned_item

curl -X PATCH 'https://ovolos.ai/api/v1/planning/items/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES' \
  -H 'If-Match: THE_ETAG_FROM_YOUR_LAST_READ' \
  -d '{
      "amount": 1465
  }'

const response = await fetch("https://ovolos.ai/api/v1/planning/items/1", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
  },
  body: JSON.stringify({
      "amount": 1465
  }),
});

console.log(response.status, await response.text());

import requests

response = requests.patch(
    "https://ovolos.ai/api/v1/planning/items/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
        "If-Match": "THE_ETAG_FROM_YOUR_LAST_READ",
    },
    json={
        "amount": 1465,
    },
)

print(response.status_code, response.text)

{
    "data": {
        "id": 1,
        "name": "Building service charge",
        "direction": "expense",
        "amount": 1465,
        "signed_amount": -1465,
        "currency": "EUR",
        "category": {
            "value": "housing",
            "label": "Housing"
        },
        "cadence": "monthly",
        "interval": 1,
        "anchor_date": "2026-06-05",
        "day_rule": "exact",
        "ends_on": null,
        "occurrences_cap": null,
        "notes": "Fixed until 2029.",
        "is_active": true,
        "updated_at": "2026-06-15T12:00:00+00:00"
    }
}

Delete a plan and the schedule behind it, reporting how many hand-made occurrence overrides went with it and how much monthly cash flow left the forecast.

• Occurrences somebody individually skipped or adjusted are deleted with the plan; `meta.skipped_occurrences_removed` is the only record that they existed.
• Pausing is not removing — `is_active: false` leaves the row standing in the user's list.
• `meta.monthly_equivalent` is signed and in the plan's own currency, and is zero for a paused plan, which was already contributing nothing.

Takes no query parameters and no body.

Assistant equivalent: delete_planned_item

curl -X DELETE 'https://ovolos.ai/api/v1/planning/items/1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN'

const response = await fetch("https://ovolos.ai/api/v1/planning/items/1", {
  method: "DELETE",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.delete(
    "https://ovolos.ai/api/v1/planning/items/1",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "deleted": true,
        "id": 1,
        "name": "Building service charge"
    },
    "meta": {
        "skipped_occurrences_removed": 0,
        "monthly_equivalent": -210,
        "affected_projection": true
    }
}

Drop one dated instance of a plan out of the forecast, leaving the plan itself alone.

• Keyed on (plan, date), so repeating it changes nothing.
• `meta.unchanged` comes from a real before-and-after diff, so replacing an adjusted occurrence with a skip counts as a change even though no row is created.

Takes no query parameters and no body.

Assistant equivalent: skip_occurrence

curl -X PUT 'https://ovolos.ai/api/v1/planning/items/1/occurrences/2026-07-05' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ovo_YOUR_TOKEN' \
  -H 'Idempotency-Key: A_UUID_YOU_KEEP_ACROSS_RETRIES'

const response = await fetch("https://ovolos.ai/api/v1/planning/items/1/occurrences/2026-07-05", {
  method: "PUT",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer ovo_YOUR_TOKEN",
    "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
  },
});

console.log(response.status, await response.text());

import requests

response = requests.put(
    "https://ovolos.ai/api/v1/planning/items/1/occurrences/2026-07-05",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ovo_YOUR_TOKEN",
        "Idempotency-Key": "A_UUID_YOU_KEEP_ACROSS_RETRIES",
    },
)

print(response.status_code, response.text)

{
    "data": {
        "planned_item_id": 1,
        "occurrence_date": "2026-07-05",
        "status": "skipped"
    },
    "meta": {
        "unchanged": false
    }
}

Add a category to this portfolio's own spending vocabulary — the one every category write on this API validates against — returning its slug, label, colour and whether it counts toward spending.

• The slug is derived from the label and returned as `value`: it is what transactions, budgets and planned items are keyed on, and a second "Boat fund" becomes `boat_fund_2`.
• It recategorises nothing — existing transactions stay where they are.
• Nothing dedups categories, so a duplicate leaves the user's spending split across two similar ones.