AI assistant (MCP) reference
Model Context Protocol endpoint for AI agents. A single JSON-RPC 2.0 endpoint serves initialize, tools/list and tools/call; there is no path namespacing by design.
Authenticate with a personal API key sent as Authorization: Bearer twai_… (legacy keys: pk_…). The key's scopes decide which tools the agent may call.
- Let an AI assistant look up your accounts
- Let an assistant summarise how your portfolio is spread across…
- Choose which tools the assistant may use through the scopes…
1 operation · 34 tools · version 1.0.0
How to authenticate
Personal API key for portfolio consumer API. Format: Bearer twai_… (legacy keys: pk_…)
Authorization: Bearer twai_<prefix><secret><checksum>
mcp
The Model Context Protocol endpoint an AI agent connects to. One JSON-RPC 2.0 request per call, carrying the read-only tools the calling key's scopes allow.
One Model Context Protocol request per POST, as a JSON-RPC 2.0 envelope. The method field names the operation and the result carries the payload; a failure comes back as a JSON-RPC error object rather than as a bare HTTP status, so read the body either way.
Methods
initialize— negotiate the protocol version and read the server's capabilities. Call this first.tools/list— list the tools the calling key may use, each with a title, a JSON Schema for its arguments andannotationsmarking it read-only (readOnlyHint: true). A tool appears only when the key holds its scope and your plan includes the feature it needs, so every listed tool is one the key can call.tools/call— run one tool by name, passing its arguments as an object.
Tools
list_holdings— List the user's aggregated portfolio holdings with live prices. Returns securities, quantities, market value, cost basis, and unrealised gain/loss. Mirrors GET /api/v1/portfolio/ext/holdings/. Requires theportfolio:readscope.list_transactions— List the user's portfolio transactions (buys, sells, dividends, transfers). Optional filters: account_id, security_id, date range, limit. Mirrors GET /api/v1/portfolio/ext/transactions/. Requires theportfolio:readscope.get_analytics_summary— Return a combined snapshot of portfolio analytics — sector/currency allocation plus performance over the requested period. Combines /analytics/allocation/ and /analytics/performance/. Requires theportfolio:readscope.list_watchlists— List the user's watchlists and their items (securities being tracked, alert thresholds). Mirrors GET /api/v1/portfolio/ext/watchlists/. Requires theportfolio:readscope.get_practice_profile— Return your own professional profile and practice details: the firm's name, trading name, type and regulatory registration, or a null practice for a sole practitioner. Mirrors GET /api/v1/pro/ext/me/. Requires thepro:readorpro:practice:readscope.list_appointments— List the appointments booked with you, most recently scheduled first: the client, status, type, scheduled start and end, how the appointment is held and whether it was paid for. Paginated. Mirrors GET /api/v1/pro/ext/appointments/. Requires thepro:readorpro:matters:readscope.list_client_approaches— List the enquiries directed at you, newest first: the kind of approach and its status, urgency, source, the services asked about, any fee you have quoted and the jurisdiction the work falls in. Paginated. Mirrors GET /api/v1/pro/ext/approaches/. Requires thepro:readorpro:clients:readscope.list_engagement_letters— List your engagement letters with the status of each, newest first. Paginated. Mirrors GET /api/v1/pro/ext/engagement-letters/. Requires thepro:readorpro:clients:readscope.list_matters— List your matters that have a client with an account, newest first. Carries no client name, contact detail or free text; brief_available says whether the client currently consents to you reading their file for that matter. Paginated; pass updated_since to fetch only what changed. Mirrors GET /api/v1/pro/ext/matters/. Requires thepro:readorpro:matters:readscope.get_matter_brief— Return the client's file for one matter, only while the client's consent to share it is live; the consent is checked on every call. A matter that is not yours, does not exist or has no live consent all answer 404 alike. Each call counts against the same client-file allowance as the REST route. Mirrors GET /api/v1/pro/ext/matters/{id}/brief/. Requires thepro:readorpro:matters:readscope.list_clients— List your current clients, most recently changed first. A client who withdraws leaves the list and is reported as deleted to an updated_since fetch. Paginated. Mirrors GET /api/v1/pro/ext/clients/. Requires thepro:readorpro:clients:readscope.list_client_wills— List the wills on your dashboard's client wills list, most recently changed first: the wills you drafted for clients and your clients' own wills you are reviewing, with their status. Paginated; pass updated_since to fetch only what changed. Mirrors GET /api/v1/pro/ext/wills/. Requires thepro:readorpro:clients:readscope.list_invoices— List every invoice you have raised, drafts included, newest first. Amounts are decimal strings in the invoice's currency; tax_info names the tax charged, so never assume a label or rate. Paginated; pass updated_since to fetch only what changed. Mirrors GET /api/v1/pro/ext/invoices/. Requires thepro:readorpro:billing:readscope.list_conversations— List the message conversations you can read, most recently active first. Paginated; pass updated_since to fetch only what changed. Mirrors GET /api/v1/pro/ext/conversations/. Requires thepro:readorpro:clients:readscope.list_conversation_messages— List the messages in one conversation, oldest first. A conversation you cannot read answers 404. Paginated; pass updated_since to fetch only messages sent, edited or deleted since then. Mirrors GET /api/v1/pro/ext/conversations/{id}/messages/. Requires thepro:readorpro:clients:readscope.get_practice_dashboard— Return the practice-overview figures your dashboard shows: new business, work in hand, revenue, open complaints and wills held over a reporting window of period days, each with its value for the previous window where there is one. Mirrors GET /api/v1/pro/ext/dashboard/. Requires thepro:readorpro:practice:readscope.get_estate_status— Summarise the user's estate documents: how many wills are completed or in progress, whether a letter of wishes exists, each power of attorney by type and status, and how many documents are stored in the vault. Counts and statuses only, never document content. Includes a suggested next step as a path on the site the user signed up on. Requires theestate:readscope.get_residency_day_counts— Count the days the user was present in each country between two dates (inclusive, at least 28 days and at most three years apart; the window is widened to whole calendar months), from their confirmed presence records, plus how close they are today to each day-count threshold we track for those countries (always as of today, whatever the window). Counts only, never a location history, and informational only: it does not determine tax residence. Requires theresidency:readscope.list_estate_wills— List each will the user has started: its state, whether it is finalised and how far through the will-writing steps they are, never its content. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/wills/. Requires theestate:readscope.list_estate_other_assets— List the assets the user has recorded for their estate outside their investment portfolio, with the value they estimated for each. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/other-assets/. Requires theestate:readscope.list_estate_relationships— List the people in the user's estate plan and how they relate to the user, by name only. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/relationships/. Requires theestate:readscope.list_estate_guardians— List each dependant the user has appointed a guardian for, with the primary and backup guardian. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/guardians/. Requires theestate:readscope.list_estate_gifts— List the specific gifts made in the user's wills. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/gifts/. Requires theestate:readscope.list_estate_trusts— List the trusts in the user's estate plan. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/trusts/. Requires theestate:readscope.list_estate_powers_of_attorney— List the user's powers of attorney and advance decisions by type and status, never the document content. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/powers-of-attorney/. Requires theestate:readscope.list_estate_funeral_wishes— List the user's recorded funeral wishes. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/funeral-wishes/. Requires theestate:readscope.list_estate_organ_donation— List the user's organ donation preferences, one per jurisdiction. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/organ-donation/. Requires theestate:readscope.list_estate_vault_documents— List metadata of the documents in the user's personal vault, never the files themselves. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/vault-documents/. Requires theestate:readscope.list_estate_appointments— List the user's appointments with professionals. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/appointments/. Requires theestate:readscope.list_estate_engagement_letters— List the engagement letters professionals have sent the user. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/engagement-letters/. Requires theestate:readscope.list_estate_residency_stays— List the user's confirmed presence records from the residency tracker. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/residency/stays/. Requires theestate:readscope.list_estate_residency_journeys— List the journeys recorded in the user's residency tracker. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/residency/journeys/. Requires theestate:readscope.list_estate_residency_accommodation— List the accommodation stays recorded in the user's residency tracker. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/residency/accommodation/. Requires theestate:readscope.list_estate_todos— List the user's personal to-do items with their section, priority and state. Mirrors GET /api/v1/portfolio/ext/estate/todos/. Requires theestate:readscope.
Every tool in this version is read-only; none of them changes your data.
Authenticate with a personal API key created under Account → Developer, sent as Authorization: Bearer twai_… (legacy keys: pk_…). A key only ever reaches the data of the member who created it, and the key's scopes decide which tools the agent may call.
Rate limits
Agent calls have their own hourly allowance, separate from your REST API traffic, so an agent cannot use up the allowance your own integrations rely on. The allowance is the same hourly rate your plan grants the REST API — the personal API rate for a personal key, the professional API rate for a professional key (read it as rate_limit from the developer usage endpoint) — applied on a one-hour sliding window with a per-minute burst cap derived from that hourly rate. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for this allowance; a throttled call returns 429 with a Retry-After header. Plans with unlimited API access are not throttled.
Errors
Each refusal has its own JSON-RPC error code, and its data.reason names the refusal, so an agent can decide what to do without parsing the message:
-32001(unauthenticated, HTTP401) — the key is missing, invalid, revoked or expired. Stop and ask the user for a valid key.-32002(scope, HTTP403) — the key does not hold the scope this call needs;data.required_scopenames it (or, when the key holds none of the scopes this endpoint serves,data.accepted_scopeslists them). Retrying cannot succeed: the user must create a key with that scope.-32003(entitlement, HTTP403) — the user's plan does not include the feature this tool needs;data.featurenames it anddata.required_plannames a plan that does, when there is one. Ask the user to upgrade.-32004(rate_limit, HTTP429) — the hourly or per-minute allowance is spent. Waitdata.retry_afterseconds (also sent asRetry-After), then retry.-32005(ai_switched_off, HTTP403) — AI is switched off for this account (by the person, their organisation or us);datacarries the AI policy (code,reason_code,decided_by). Retrying cannot succeed until AI is switched back on in Settings.-32010— the tool itself failed. The call may succeed if repeated later.
Request body
application/json{}Responses
{}Portfolio
List the user's aggregated portfolio holdings with live prices. Returns securities, quantities, market value, cost basis, and unrealised gain/loss. Mirrors GET /api/v1/portfolio/ext/holdings/.
What the assistant can send
Nothing: the assistant calls this tool without any input.
List the user's portfolio transactions (buys, sells, dividends, transfers). Optional filters: account_id, security_id, date range, limit. Mirrors GET /api/v1/portfolio/ext/transactions/.
What the assistant can send
account_idstring (uuid)security_idstring (uuid)date_fromstring (date)ISO 8601 date (YYYY-MM-DD), inclusive.
date_tostring (date)ISO 8601 date (YYYY-MM-DD), inclusive.
limitinteger
{
"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"security_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"date_from": "2026-01-31",
"date_to": "2026-01-31",
"limit": 0
}Return a combined snapshot of portfolio analytics — sector/currency allocation plus performance over the requested period. Combines /analytics/allocation/ and /analytics/performance/.
What the assistant can send
periodone of 8 values
{
"period": "1y"
}List the user's watchlists and their items (securities being tracked, alert thresholds). Mirrors GET /api/v1/portfolio/ext/watchlists/.
What the assistant can send
Nothing: the assistant calls this tool without any input.
Estate plan
Summarise the user's estate documents: how many wills are completed or in progress, whether a letter of wishes exists, each power of attorney by type and status, and how many documents are stored in the vault. Counts and statuses only, never document content. Includes a suggested next step as a path on the site the user signed up on.
What the assistant can send
Nothing: the assistant calls this tool without any input.
List each will the user has started: its state, whether it is finalised and how far through the will-writing steps they are, never its content. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/wills/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the assets the user has recorded for their estate outside their investment portfolio, with the value they estimated for each. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/other-assets/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the people in the user's estate plan and how they relate to the user, by name only. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/relationships/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List each dependant the user has appointed a guardian for, with the primary and backup guardian. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/guardians/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the specific gifts made in the user's wills. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/gifts/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the trusts in the user's estate plan. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/trusts/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the user's powers of attorney and advance decisions by type and status, never the document content. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/powers-of-attorney/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the user's recorded funeral wishes. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/funeral-wishes/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the user's organ donation preferences, one per jurisdiction. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/organ-donation/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List metadata of the documents in the user's personal vault, never the files themselves. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/vault-documents/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the user's appointments with professionals. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/appointments/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the engagement letters professionals have sent the user. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/engagement-letters/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the user's personal to-do items with their section, priority and state. Mirrors GET /api/v1/portfolio/ext/estate/todos/.
What the assistant can send
statusone of: all, completed, hidden, snoozedall(the default) returns every item that is neither hidden nor snoozed; the other values return only the items in that state.
{
"status": "all"
}Residency tracker
Count the days the user was present in each country between two dates (inclusive, at least 28 days and at most three years apart; the window is widened to whole calendar months), from their confirmed presence records, plus how close they are today to each day-count threshold we track for those countries (always as of today, whatever the window). Counts only, never a location history, and informational only: it does not determine tax residence.
What the assistant can send
date_fromstring (date) · requiredISO 8601 date (YYYY-MM-DD), inclusive.
date_tostring (date) · requiredISO 8601 date (YYYY-MM-DD), inclusive.
{
"date_from": "2026-01-31",
"date_to": "2026-01-31"
}List the user's confirmed presence records from the residency tracker. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/residency/stays/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the journeys recorded in the user's residency tracker. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/residency/journeys/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the accommodation stays recorded in the user's residency tracker. Only the user's own records are returned. Mirrors GET /api/v1/portfolio/ext/estate/residency/accommodation/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}Your practice
Return your own professional profile and practice details: the firm's name, trading name, type and regulatory registration, or a null practice for a sole practitioner. Mirrors GET /api/v1/pro/ext/me/.
What the assistant can send
Nothing: the assistant calls this tool without any input.
List the appointments booked with you, most recently scheduled first: the client, status, type, scheduled start and end, how the appointment is held and whether it was paid for. Paginated. Mirrors GET /api/v1/pro/ext/appointments/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
{
"page": 0
}List the enquiries directed at you, newest first: the kind of approach and its status, urgency, source, the services asked about, any fee you have quoted and the jurisdiction the work falls in. Paginated. Mirrors GET /api/v1/pro/ext/approaches/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
{
"page": 0
}List your engagement letters with the status of each, newest first. Paginated. Mirrors GET /api/v1/pro/ext/engagement-letters/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
{
"page": 0
}List your matters that have a client with an account, newest first. Carries no client name, contact detail or free text; brief_available says whether the client currently consents to you reading their file for that matter. Paginated; pass updated_since to fetch only what changed. Mirrors GET /api/v1/pro/ext/matters/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}Return the client's file for one matter, only while the client's consent to share it is live; the consent is checked on every call. A matter that is not yours, does not exist or has no live consent all answer 404 alike. Each call counts against the same client-file allowance as the REST route. Mirrors GET /api/v1/pro/ext/matters/{id}/brief/.
What the assistant can send
matter_idstring (uuid) · requiredA matter id from list_matters.
{
"matter_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}List your current clients, most recently changed first. A client who withdraws leaves the list and is reported as deleted to an updated_since fetch. Paginated. Mirrors GET /api/v1/pro/ext/clients/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the wills on your dashboard's client wills list, most recently changed first: the wills you drafted for clients and your clients' own wills you are reviewing, with their status. Paginated; pass updated_since to fetch only what changed. Mirrors GET /api/v1/pro/ext/wills/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List every invoice you have raised, drafts included, newest first. Amounts are decimal strings in the invoice's currency; tax_info names the tax charged, so never assume a label or rate. Paginated; pass updated_since to fetch only what changed. Mirrors GET /api/v1/pro/ext/invoices/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the message conversations you can read, most recently active first. Paginated; pass updated_since to fetch only what changed. Mirrors GET /api/v1/pro/ext/conversations/.
What the assistant can send
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}List the messages in one conversation, oldest first. A conversation you cannot read answers 404. Paginated; pass updated_since to fetch only messages sent, edited or deleted since then. Mirrors GET /api/v1/pro/ext/conversations/{id}/messages/.
What the assistant can send
conversation_idstring (uuid) · requiredA conversation id from list_conversations.
pageintegerPage number of the result set, starting at 1.
updated_sincestring (date-time)Only rows changed at or after this ISO 8601 date or date-time (UTC when no offset is given).
{
"conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"page": 0,
"updated_since": "2026-01-31T09:00:00Z"
}Return the practice-overview figures your dashboard shows: new business, work in hand, revenue, open complaints and wills held over a reporting window of period days, each with its value for the previous window where there is one. Mirrors GET /api/v1/pro/ext/dashboard/.
What the assistant can send
periodone of: 7, 30, 90Reporting window in days.
{
"period": 30
}
