Skip to main content
This page records changes to the Onsomble API contract. The current version is v1, served from https://api.onsomble.ai/v1.

​
Versioning policy

The major version appears in the URL. Additive changes do not create a new major version. This includes new optional response fields and new endpoints. A breaking change creates a new major version and an entry on this page. Breaking changes include removing or renaming an endpoint, removing or renaming a response field, changing a field’s meaning or type, changing authentication behaviour, or changing a stable error code.

​
Upcoming contract change

​
Reports keep working for Sites with many Scans

The overview, scorecard, timeline, references, prompt results, prompt result trends and narratives reports look up when each Scan finished. That lookup sent every Scan’s ID in the request address, which becomes too long once a Site has enough Scans, and the report then failed with an error. The lookup now sends the IDs in the request body, so these reports work however many Scans a Site has. No fields changed. Implemented in development, not yet deployed to production.

​
Exact Scan finish times beside Scan dates

Every report field that gives a Scan’s day stays the UTC calendar day, and its description now says so. Each gains an optional ISO 8601 timestamp of when the Scan finished, so a client can show the day in its own time zone:
  • completedAt on the overview (plus previousCompletedAt), on scorecard, timeline and prompt-result-trend points, and on references trend points.
  • scanCompletedAt on prompt results, narratives and narrative claims.
  • firstSeenCompletedAt and lastSeenCompletedAt on discovered competitors.
The startDate and endDate filters are UTC calendar days. MCP summary lines now mark their day as “(UTC)”. These are additive changes; no field changed meaning. Implemented in development, not yet deployed to production.

​
Scan order in reports

The overview, scorecard, timeline and references reports now put Scans in the order they finished. Before this fix, two Scans on the same day could be put in the wrong order, and the overview could treat the earlier one as the latest and report its changes backwards. No fields changed. Implemented in development, not yet deployed to production.

​
Discovered competitors include recent Scans

The discovered-competitors report now lists brands found in every completed Scan. Since early September it had missed brands found in newer Scans, so a Site first scanned after that returned an empty list. It also no longer counts Scans that failed. No fields changed. Implemented in development, not yet deployed to production.

​
Failed Scans left out of reports

The overview, scorecard, timeline and references reports no longer include Scans that failed, matching the other reports and the app. A failed Scan that had already produced results appeared as a point in the scorecard and timeline, and its citations were counted in the references totals. No fields changed. Implemented in development, not yet deployed to production.

​
Account setup, Site editing, and a region catalogue from an AI assistant

The MCP gains four tools that round out account and Site setup:
  • get_account and update_account read and edit the account itself — its name, type (business or agency), website, description, services, and default industry and country. Pass only the fields you want to change. Switching the type (business ↔ agency) is only allowed while the account is empty — no Clients and no Sites — and moves the account onto the matching free tier; the other fields can change any time. update_account needs a new account:write scope, which every credential holds today.
  • manage_site edits a live Site’s details after creation — the same settings the app’s Site-settings page edits: name, industry, description, market, operating regions, and brand aliases (other brand names, short names/abbreviations, other web domains). Pass only the fields to change; aliases are edited per group with add/remove.
  • list_regions returns the regions a Scan can run in — countries and cities, each with the exact ref that manage_regions and manage_prompts accept, plus the default worldwide scope. manage_regions now validates a region on add and refuses an unrecognised or non-selectable ref, pointing the caller at list_regions.
These are MCP-only. Implemented in development, not yet deployed to production.

​
Connect from your AI tool without an existing account

Creating an Onsomble account from inside an AI tool’s connection flow now returns you to the tool: sign up by password, by a sign-in provider, or by magic link, approve the connection, and you are connected. If the tool’s request can no longer be loaded when you get back, the approve page tells you you’re all set and to go back to the tool and connect. The consent screen now says what the tool can do with your account. On connect, the MCP tells the assistant that an account with no Sites is new and to offer first-site setup; the connect-time instructions were also corrected (they no longer describe the tools as read-only). MCP-only. Implemented in development, not yet deployed to production.

​
Manage Client Portfolios from an AI assistant

The MCP gains three tools for agency Client Portfolios (an account-level collection of Clients): list_portfolios lists them with their client and site counts; get_portfolio opens one to its Clients and their Sites; and manage_portfolio creates one, renames or re-describes it, and adds or removes Clients (operation: create | update | add_clients | remove_clients, with clientIds from list_sites). Agency accounts only; there is no delete through the API. MCP-only. Implemented in development, not yet deployed to production.

​
Work recommendations from an AI assistant

The MCP gains three tools for the recommendation board: transition_recommendation moves a recommendation across the board (approve, decline, start work, publish, confirm, archive, restore, acknowledge review — an illegal move is refused with the reason); create_recommendation raises a new recommendation the Scan did not, anchored to a narrative (the assistant writes the title, buyer question and proposed work), which enters at the review stage under the user and is tracked by every later Scan like a Scan-raised one; and edit_recommendation changes a recommendation the user raised — any of its title, buyer question, proposed work, shortfall, pages, grades, or its pinned evidence quotes (a claimId[] from get_narrative_claims). Scan-raised recommendations cannot be edited, nor can one that has been confirmed or archived; an edit changes the content only, never the standing or board position. get_narrative_claims now returns a claimId per quote so an assistant can pin it as evidence when creating or editing. Untracking a prompt and putting a retired one back is a prompt-manager action, handled by manage_prompts: removing a prompt retires it, and adding a prompt whose text matches one retired earlier reactivates that prompt in place and keeps its earlier scan history instead of creating a duplicate (a new reactivate operation does this explicitly). These are MCP-only. Implemented in development, not yet deployed to production.

​
Create a Site from an AI assistant

The MCP gains three write tools for bringing a new Site into Onsomble, the same way the app’s create-site flow does: research_site researches a website and returns the proposed business profile; create_site activates a Site from a profile — either the researched one, or a profile the assistant writes itself for a URL; and manage_client lets an agency account add or update the Clients its Sites sit under. create_site takes a Site slot on the account (or the Client) and stops where the app’s confirm stops — the Site is live with its profile and the default AI models and nothing else, so a scan cannot run until prompts are added; the tool returns an explicit next step for the assistant to set the scan up with the user. There is no delete for a Site or a Client through the API. These are MCP-only for now — no REST endpoint. Implemented in development, not yet deployed to production.

​
Configure a Site from an AI assistant, and Scans run the current setup

The MCP gains eight write tools that edit a Site’s working configuration — the same setup the app’s Prompt library, Models, Competitors and Schedule pages edit: manage_personas, manage_products, manage_journey_stages, manage_prompts, manage_competitors, manage_models, manage_regions, and manage_schedule. Each is task-shaped (operation: add | update | remove, or a direct edit for models and schedule) and returns the updated scan configuration. A prompt added through manage_prompts has its persona, product and journey-stage references validated against the Site’s strategy, so an assistant cannot create a prompt the prompt matrix cannot place. There is no separate publish step: a change is live once a Scan runs. Behaviour change to POST /v1/sites/{siteId}/scans. Starting a Scan through the API (or the MCP trigger_scan tool) now publishes the Site’s working configuration before running, when that working configuration is newer than the last published version — so an API-triggered Scan runs the current setup, matching the app’s scan button. Previously an API-triggered Scan ran the last published version, which could be older than the Site’s live setup. The endpoint’s request and response are unchanged; only which configuration the Scan runs changes. The endpoint also gains two entry-validation rejections, both 409: scan_not_ready when the Site has no enabled prompts or no enabled AI models to scan (previously a no-models trigger returned a generic 500), and a new scan_already_running code when a Scan for the Site is still in flight — a fresh trigger is refused until it finishes. The in-flight rule is enforced by the database (one active run per Site), so it holds for every way a Scan can start; a scheduled Scan whose slot falls while another run is active skips that occurrence. These writes are MCP-only for now — there is no REST endpoint for them yet. All of this is implemented in development and has not yet been deployed to production.

​
Read a Site’s scan configuration

GET /v1/sites/{siteId}/scan-config returns a Site’s setup: its business profile, personas, products, journey stages, the AI models it scans (each with an on/off flag), region codes, schedule (frequency, enabled, nextRunAt), and the counts of prompts and tracked competitors (list those via the prompts and competitors endpoints). The MCP gains get_scan_config for the same, plus get_scorecard and get_model_breakdown tools over report endpoints that already existed. Additive; implemented in development and not yet deployed to production.

​
Claims gain drivers, narrative-attributes is retired, and the timeline is re-sourced

  • Claims gain drivers. Each claim from GET /v1/sites/{siteId}/narratives/{narrativeId}/claims now carries a drivers array: the factors behind the claim — factor, factorType (decision_criterion, feature, friction, trust_signal), polarity (positive, neutral, negative, mixed), relevance (0–1), evidence, and the brandId/brandName the driver is about (null for a market-level driver). This is additive. The MCP get_narrative_claims tool returns them too.
  • Removed: GET /v1/sites/{siteId}/reports/narrative-attributes. The narrative model (narratives, claims, and now claim drivers) supersedes the flat attribute dump. There was no MCP tool for it.
  • Timeline re-sourced. GET /v1/sites/{siteId}/reports/timeline keeps the same contract but is computed from the same metrics the scorecard reads, so a timeline point and a scorecard point for the same Scan now coincide. Two consequences: groupBy=brand returns the Site’s brand and its tracked competitors only — discovered brands are no longer emitted as series (track a brand to see it); and Scans are selected and dated exactly as the scorecard and overview select them.
Removing narrative-attributes and the timeline’s discovered-brand series are breaking changes; the claim drivers are additive. All of this is implemented in development and has not yet been deployed to production.

​
Competitors become two catalogues, and a competitorId filter

The three competitor reports are replaced by two paginated catalogues, and competitor metrics move onto the metric reports behind a new filter:
  • GET /v1/sites/{siteId}/competitors lists the Site’s tracked competitors — each with a stable competitorId, name, domain, description, the reason it is tracked, its aliases, domains, and ambiguousAliases, and trackedSince. Cursor-paginated (limit, cursor), returning data, total, and nextCursor. No metrics.
  • GET /v1/sites/{siteId}/discovered-competitors lists the brands AI answers mention that the Site does not track — each with a competitorId, name, inferred domain, kind (direct_competitor, category_alternative, channel_or_broker), reasoning, confidence, and how often it has been seen (firstSeenAt, lastSeenAt, scansSeen). Filter by kind and scanId. Cursor-paginated. No metrics.
  • competitorId is a new repeatable filter on the metric reports (overview, scorecard, timeline, model-breakdown). It takes tracked competitorIds and returns that competitor’s numbers, combining with the existing brand filter. It is tracked competitors only — a discovered competitorId is rejected with validation_failed; track the brand in Onsomble to measure it, after which it appears in the tracked catalogue under the same competitorId.
Removed: GET /v1/sites/{siteId}/reports/competitors, GET /v1/sites/{siteId}/reports/competitors/{competitorId}, and GET /v1/sites/{siteId}/reports/discovered-competitors. Their metrics are now reached by filtering a metric report by competitorId. The MCP get_competitor_insights tool is replaced by list_competitors and list_discovered_competitors, and the report tools gain a competitorId argument. Removing the three reports is a breaking change; the two catalogues and the filter are new. All of this is implemented in development and has not yet been deployed to production.

​
Recommendations move to the durable model, and gain a write surface

The recommendations report is rebuilt on the durable recommendations model and, for the first time, the API can write.
  • GET /v1/sites/{siteId}/reports/recommendations now returns the Site’s current recommendations, not a per-scan list. Each is a persistent item with a title, topic, and question; its target, current, and baseline standing; impact, effort, and confidence; the narrative it addresses; and its prompt references by scan. Filter by platform, region, persona, product, stage, brand-mention, narrative, board status, and movement since the last scan. The former per-scan shape (date, scanId, summary, actions) is gone; there is no scanId parameter.
  • GET /v1/sites/{siteId}/recommendations/{recommendationId} returns one recommendation’s brief (what to do and why, with the plan), its standing history, and the evidence quotes.
  • Actions and notes are read-write. GET/POST /…/recommendations/{id}/actions, PATCH/DELETE /…/actions/{activityId}, and the same four for /notes, are full CRUD.
The writes are the API’s first beyond starting a scan. They require the new recommendations:create, recommendations:update, and recommendations:delete scopes, and a change is attributed to the user who minted the key. Two current limits: every key holds all scopes until per-key permissions ship, so the write scopes are not yet real gates; and a key minted before creator capture is refused writes until it is re-created. The MCP get_recommendations tool returns the new list, get_recommendation opens one, and manage_recommendation_action and manage_recommendation_note perform the writes. This is a breaking change to the recommendations report and a new write surface, implemented in development and not yet deployed to production.

​
Narratives become a list plus a claims-by-narrative drill-in

The single narrative-claims report (GET /v1/sites/{siteId}/reports/narrative-claims), which returned every narrative with all its claims nested in one payload, is replaced by a UUID-keyed pair:
  • GET /v1/sites/{siteId}/reports/narratives lists the narratives for one Scan, each with a stable narrativeId, a claim count, a relevance, and — where the Scan has it — the tracked brand’s standing on a five-rung ladder (Absent, Criticised, Mentioned, Cited as authority, Recommended) with the previous Scan’s rung and a trend. Filter by the full classification vocabulary, platform, region, and scanId. Standing is present only when the filter matches a computed scope and the Scan ran the readings model; it is null otherwise.
  • GET /v1/sites/{siteId}/narratives/{narrativeId}/claims returns every claim for one narrative in a Scan — the quotes, platform, region, per-brand stances, and cited sources — looked up by the narrativeId from the list. Each claim carries only its promptId, not the verbatim prompt text (a large narrative repeated a handful of prompts across thousands of claims).
New alongside them, GET /v1/sites/{siteId}/prompts and GET /v1/sites/{siteId}/prompts/{promptId} list the Site’s prompt catalogue — each question’s text, category, tags, products, personas, and journey stages, keyed by promptId. This is the resolver for the promptIds returned by prompt-results, narratives, and claims. The MCP get_narratives tool changes to return the list, and new get_narrative_claims and get_prompts tools are added. The former claims-unavailable fallback to narrative attributes is removed: a Scan with no claims returns an empty list. Removing the combined narrative-claims endpoint is a breaking change; the two replacements are new. All of this is implemented in development and has not yet been deployed to production.

​
Dashboard-parity filters, a discovery endpoint, and the regions report is retired

Every metric report now accepts the dashboard’s full filter vocabulary, resolved by the same engine the dashboard uses:
  • New query parameters on the metric reports (overview, scorecard, timeline, prompt-results, references): promptId, tag, category, product, persona, stage, and brandMention (mentions_tracked_brand or does_not_mention_tracked_brand), each repeatable and optional. They resolve to the set of prompts they match, and the report is computed over that slice. overview, scorecard, and timeline additionally accept brand (brand identity ids), which limits which brands are returned without changing a Share of Voice denominator.
  • New discovery endpoint: GET /v1/sites/{siteId}/filters lists the values each filter accepts for a Site — tags, categories, products, personas, journey stages, regions, platforms, tracked brands, and brand-mention tokens — each paired with a human label. Pass scanId to narrow the values to one Scan.
  • Removed endpoint: GET /v1/sites/{siteId}/reports/regions. Region is now a filter on every report: for a region breakdown, filter any report by region; for a region trend, use the timeline report with groupBy=region; to discover a Scan’s region codes, use the new filters endpoint.
The MCP server changes in step with the REST API: the report tools gain the same filter arguments, a new get_filter_options tool returns the discovery payload, and the get_region_visibility tool is removed (filter any report by region, or use get_visibility_timeline with groupBy region). Removing the regions endpoint and the region tool is a breaking change; adding the filter parameters, the discovery endpoint, and the discovery tool is additive. All of this is implemented in development and has not yet been deployed to production. The Prompt Results report (GET /v1/sites/{siteId}/reports/prompt-results) now returns one Scan’s results, paginated, instead of every result across every Scan in one response.
  • New query parameters: scanId (omit for the latest completed Scan), promptId (limit to one prompt, for example the same prompt across every platform), limit (default 25, max 100), and cursor.
  • Removed query parameters: startDate and endDate on this endpoint. scanId replaces the date window; the References report keeps its date window.
  • Response gains: scanId and scanDate (the Scan the results are from), total (results in that Scan matching the filters), nextCursor (pass back as cursor, null on the last page), and a stable id on each result.
  • Response loses: the trends array, and the per-result date and scanId (now echoed once at the top).
  • New endpoint: GET /v1/sites/{siteId}/reports/prompt-results/{resultId}/trends returns the change over time for one result, its prompt, platform, and region across every Scan.
These are breaking response-contract changes. They are implemented in development and have not yet been deployed to production.

​
References filters by Scan and prompt, not by date

The References report (GET /v1/sites/{siteId}/reports/references) drops the startDate and endDate query parameters and adds scanId and promptId, each repeatable (?scanId=…&scanId=…) and optional. Omitting them covers every Scan, as before. To cover a date period, resolve the Scans for that period from the scans endpoint and pass their ids as scanId. The response’s filters object now echoes platform, region, scanId, and promptId instead of the date window. The domain rows are unchanged. This is a breaking query- and response-contract change, implemented in development only.

​
v1

​
MCP server and GPT Actions schema — August 2026

Onsomble now runs a hosted MCP server at https://mcp.onsomble.ai/mcp for AI assistants and agent platforms. It authenticates with the same API keys, shares the account rate limit with the REST API, and exposes a curated tool set rather than mirroring endpoints. Connection guides for Claude, OpenAI, Cursor, Windsurf, and VS Code live in the new Connect AI assistants section, together with an installable Agent Skill that teaches agents to interpret the results. A GPT Actions schema is published at /openapi/gpt-actions-v1.json: a curated subset of the full OpenAPI document generated from it, covering Sites, Scan control, and the headline reports. The full document is unchanged; the subset exists because Action tool selection works best with a small surface.

​
Insight report expansion — August 2026

Six additive report endpoints bring the deeper dashboard insights to the API:
  • GET /v1/sites/{siteId}/reports/overview — the latest Scan’s brand and competitor metrics with change against the previous Scan.
  • GET /v1/sites/{siteId}/reports/timeline — metric trends across Scans, one series per brand, platform, or region.
  • GET /v1/sites/{siteId}/reports/competitors and GET /v1/sites/{siteId}/reports/competitors/{competitorId} — tracked competitors with latest-Scan metrics, and a side-by-side comparison against the brand.
  • GET /v1/sites/{siteId}/reports/discovered-competitors — brands AI answers mention that are not tracked yet, ranked by discovery signal.
  • GET /v1/sites/{siteId}/reports/model-breakdown — one metric for one brand across every measured platform.
  • GET /v1/sites/{siteId}/reports/narrative-claims — the narratives AI answers build around the brand, with verbatim quotes and citations as evidence.
Timeline and model-breakdown endpoints take a metric parameter (visibility, shareOfVoice, sentiment, gap) matching the Scorecard field names. Reports with latest-Scan semantics (competitors, discovered competitors, model breakdown, narrative claims) take no date parameters; the others use the standard report filters.

​
Initial API

v1 provides read access to Clients, Sites, Scans, and discoverability reports. It can also start a Scan for an existing Site. Report filters and responses identify AI platforms with stable IDs such as chatgpt_app and state whether Onsomble collected the answer from the web or an API. Future additive v1 changes will be documented here without changing the /v1 URL. A breaking change will appear as a new major-version section before the new version is released.