API changelog

This page documents all changes to the Portfolio Tracker Consumer API. We follow semantic versioning. Breaking changes are announced at least 90 days.

Last reviewed

November 2026: Overlap when you rotate a webhook signing secret

Additive, and no action is required. Rotating a webhook signing secret no longer cuts off the old one at once: by default it keeps working for an overlap, and you can still choose to end it straight away.

  • Two signatures during the overlap: webhook-signature carries one space-separated v1, value per live secret, so a receiver on the old or the new secret verifies. Standard Webhooks libraries already accept this form.
  • grace on rotate: POST /api/v1/portfolio/webhooks/{id}/rotate-secret/ accepts grace (24h, the default, or none) and returns previous_secret_valid_until.
  • Legacy header is replayable: X-Webhook-Signature signs the body only, so a captured delivery can be replayed and still verify. It stays deprecated and is signed with the new secret only.

v1.4.0: Income, costs, tax, household, cash, write and news endpoints (October 2026)

Most of what the Portfolio Tracker shows you can now be read through the API, and watchlists, accounts, imports and corporate actions can be changed through it. Every new endpoint sits under /api/v1/portfolio/ext/ and needs portfolio:read, or portfolio:write for a write. Released 21 October 2026.

  • Reference per brand: the API reference lists only the endpoints this site offers, and its capability list matches.
  • Estate scopes follow your estate link: where your estate plan is held on a linked service, a key can hold estate:read, residency:read or documents:read, and an AI agent sees the estate tools, only once you have linked it.
  • Income and costs: income/ with yield, calendar, forecast and reinvestment preferences, and costs/ with cost types, account charges, currency conversion costs and margin interest.
  • Returns and allocation: analytics/ gains periods, returns, benchmark, attribution, risk, portfolio history and allocation by sector, region and currency; holdings/valuations/ lists saved valuations. Benchmark answers give computed figures only, never the index series itself.
  • Tax figures: tax/ gains disposals, dividends, section 104 pools, tax years, losses carried forward and wash sales, plus tax/lots/ and tax/documents/. Figures are estimates, not tax returns.
  • Family, cash and export: family members, households, shares, snapshots, pending transactions and transfers (read only), cash balances and movements, leveraged positions and their fills, and export/ for your whole portfolio in one file.
  • Writes: create watchlists and add securities to them, add and change accounts, review, map and confirm imports, and confirm or undo corporate actions. Every write accepts an Idempotency-Key header; reversing an import or undoing a corporate action also needs "confirm": true.
  • Sector news: news/articles/ (filter by topic, country or featured) and news/topics/. Each article is a headline with a link to its source.
The API version stays at v1. See the Code Examples page for a request to each new group.

v1.3.0: API-Version header and legacy webhook headers deprecated (October 2026)

Every response now says which API version answered it, and the old webhook signature headers are on their way out.

  • API-Version header: every response from the API and the MCP server, errors included, carries API-Version: 1. It tells you which version answered; you do not need to send it.
  • Deprecated: legacy webhook headers: webhook deliveries will stop sending X-Webhook-Signature, X-Webhook-ID, X-Webhook-Timestamp and X-Webhook-Event on 11 January 2027. Verify deliveries with the Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature), which every delivery already carries. Until then, responses from /api/v1/portfolio/ext/webhooks/ carry the Deprecation and Sunset headers.
The API version stays at v1. If your webhook receiver checks X-Webhook-Signature, switch it to webhook-signature before 11 January 2027.

v1.2.0: Estate and residency agent tools (September 2026)

Two new read-only tools on the MCP server, each behind its own scope. Neither scope is added to an existing key: tick it on the Developer Page when you create or edit a key.

  • get_estate_status (estate:read): which estate documents you have on TheWILL.ai, the status of each and a suggested next step as a link. Statuses only, never document content.
  • get_residency_day_counts (residency:read): days present per country over a date range, with threshold proximity, from Expat183. Counts only, never your location history.
This change is additive. Existing tools, scopes and keys are unchanged, and the API version stays at v1.

v1.1.0: Namespaced scopes and developer hub (June 2026)

This release tidies up API key scopes and gives the developer tools a canonical home. Neither change affects your existing integrations.

  • Namespaced scopes: API key scopes are now namespaced, so read becomes portfolio:read and write becomes portfolio:write. This is a non-breaking change. Existing keys were updated automatically, so no action is required.
  • Developer hub: the developer tools now have a canonical home at /account/developer. The old Portfolio Tracker routes /assets/portfolio/developer and /assets/portfolio/api-docs now redirect there (the latter to the API Docs tab), so your bookmarks will continue to work.
These changes are additive and backwards-compatible. The API version stays at v1, and no endpoint paths or response shapes have changed.

v1.0.0: Initial release (April 2026)

This is the initial public release of the Portfolio Tracker Consumer API. The following endpoints and features are now available:

  • Holdings endpoint: Read-only aggregated holdings with their latest prices
  • Transaction endpoints: Record, view, change and delete transactions such as buys, sells, dividends and transfers
  • Analytics endpoints: Portfolio allocation and performance
  • Import endpoints: Upload broker statements for automatic parsing and check how far each import has got
  • Webhook endpoints: Register HTTPS endpoints for real-time event notifications on webhook-enabled plans
  • Security and watchlist endpoints: Look up securities, retrieve prices, and view or add items to your watchlists
  • Account endpoints: List and view your tracked portfolio accounts (read-only)
  • Tax endpoints: Read your tax calculation for a year and the disposals behind it
  • Authentication: Personal API keys with Argon2 hashing and Bearer token auth
  • Rate limiting: Tier-based rate limits; the figures at release were Silver: 50/hr, Gold+: 2,000/hr, VIP: unlimited (historical, see the live Rate limits section for current figures)

Versioning and deprecation policy

The Portfolio Tracker Consumer API uses URL versioning: every endpoint is prefixed with /api/v1/portfolio/ext/. The same rules apply to every external API, including the tools our MCP server offers AI assistants.

What counts as a breaking change

  • Additive (not breaking): new fields on responses, new endpoints, new optional query parameters, new webhook events and new MCP tools. These can arrive at any time and do not change the version.
  • Breaking: a removed or renamed field, endpoint or MCP tool, a changed field type, a new required parameter, or a change to how you authenticate.

Notice and support periods

  • A breaking change is announced at least 90 days before it takes effect.
  • When a new API version is released, the previous version keeps working at least 180 days afterwards.
  • Security fixes and legal requirements may need shorter notice; we will say so here and explain why.

How you are told

  • This changelog: every deprecation is listed here with its retirement date.
  • Response headers: every response from a deprecated path carries Deprecation, Sunset (the retirement date) and a Link header with rel="deprecation" pointing back to this page.
  • Machine-readable policy: /api/v1/api-policy/ returns these periods and every live deprecation as JSON.

At the retirement date

From the date in the Sunset header, the retired path answers 410 Gone with the code api_sunset and the replacement to move to. Your API key keeps working for everything that has not been retired.

Have your integration ignore fields it does not recognise, and log any response that carries a Deprecation header. Together they keep an additive change from breaking you and make sure a deprecation does not go unnoticed.

Staying informed

There are several ways to stay up to date with changes to the API:

  • This page: Bookmark this changelog and check back regularly for updates
  • Webhooks: Webhook subscriptions notify your application about activity in your portfolio, such as new transactions, corporate actions and completed imports. They do not carry API version or deprecation notices, so use this page for those. The webhook reference below lists every event you can subscribe to
  • Contact support: If you have questions about upcoming changes or need migration assistance, reach out via the contact form
Breaking changes are always announced at least 90 days before they take effect. We recommend reviewing this changelog at least once a month.

Related topics

Can’t find what you’re looking for?

Our support team is here to help. Contact us and we’ll get back to you as soon as possible.

Contact us

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.