Skip to Content
APIVersioning and upgrades

Versioning and upgrades

The API version is in the URL.

https://api.askylabs.com/v1/brands

Your integration is pinned by the path it calls. Nothing changes underneath you until you change that path, so there is no version header to set and no account-level version to keep track of.

What we may change within v1

These are additive changes. They ship continuously, without notice, and your integration must tolerate them.

  • New endpoints
  • New fields on existing response objects
  • New optional query parameters
  • New values in an enumerated field, such as a new AI engine or a new opportunity type
  • New error codes within an existing HTTP status

Write your client so unknown fields are ignored rather than rejected. Parsers configured to fail on unrecognised properties, which is the default in some strongly-typed clients, will break on an additive change that every other integration absorbs silently.

Handle unknown enum values too. If you switch on engine and we add one, the sensible default is to pass it through or skip it, not to throw.

What counts as breaking

These would not ship inside v1. They require a new version.

  • Removing an endpoint, a field, or a query parameter
  • Renaming anything
  • Changing a field’s type, or the meaning of an existing value
  • Changing a default, such as the page size
  • Adding a required parameter to an existing endpoint
  • Tightening validation so a previously accepted request is refused

How a new version would work

If we introduce v2, both versions run side by side. v1 continues to serve your integration unchanged while you migrate on your own schedule, and you migrate by changing the path, one endpoint at a time if you prefer, since the versions are independent.

We would publish what changed and why, a mapping from each v1 endpoint to its v2 equivalent, and a deprecation timeline with a minimum of 12 months of continued v1 support from the announcement. Deprecated endpoints also return a Deprecation header with the sunset date, so you can detect them from your own logs rather than tracking our announcements.

Watching for changes

  • The changelog below records every additive change.
  • The OpenAPI specification  is generated from the definitions that serve the API. Diffing it between deploys is a reliable way to catch new fields and endpoints programmatically.

Building an integration that survives

A few habits that make version changes uneventful:

Select the fields you need. Store the fields your integration uses rather than mirroring whole response objects into your warehouse schema. New fields then never require a schema migration on your side.

Do not depend on field order or on the number of keys in an object. Neither is part of the contract.

Do not parse identifiers. Ids are opaque strings. Their length and internal format may change.

Do not depend on pagination cursors being stable across versions. A cursor is valid only for continuing the list you were walking. See pagination.

Pin the version, not the host. Call https://api.askylabs.com/v1/... rather than constructing the path from configuration that might drift.

Changelog

Changes to v1, newest first.

DateChange
2026-11-18Prompt Type: List prompts adds prompt_types (brand, competitor, organic or unclassified, as the app shows them), prompt_types_corrected, automatic_prompt_types on corrected prompts, mentioned_competitors and family_id, and a prompt_type filter. New Set prompt types endpoint. mentions_own_brand stays, as detection’s flag alone.
2026-11-17Crawler endpoints (summary, timeseries, top paths, visits) count the visits to the brand’s own pages by default, plus robots.txt, llms.txt and sitemaps, as Crawler Logs does: requests for anything else, such as old links and scanners probing for .env files under a crawler’s name, are left out. For a brand with no pages listed, both scopes count every request. Pass scope=all for every request: what these endpoints returned before, plus paths containing insights, which they used to leave out. Each response adds meta.scope. This changes a default, which What counts as breaking says needs a new version; it ships in v1 as a deliberate exception, because the requests it leaves out are not visits to your pages, and scope=all keeps the previous figures one parameter away.
2026-11-12Brand Alignment: the narrative endpoint lists position.answers from the reading that works most against the entry: counter, partly, then says for a Should Say entry, and says, partly, then counter for a Should Not Say one, with absent last. Before, every entry listed says, counter, partly, then absent.
2026-11-11List responses: every row adds elements, what the answer drew besides its text (a map, places, products, a follow-up form). New element and exclude_elements parameters filter on them, include_element_counts adds meta.element_counts, and include_products returns the products each answer drew, each with its level (name_only, priced or feed), plus meta.product_levels.
2026-11-09Brand Alignment: the positioning endpoint adds narrative_read and each summary’s narrative, what it says about your narrative. Asky no longer compares summaries with the Brand Profile positioning statement, so brand_positioning and note are always null and comparisons is always empty.
2026-11-08Brand Alignment: new narrative endpoint: what your brand tracks as Should Say or Should Not Say, how often the answers in a scan say each one, and the answers behind it.
2026-11-09Brand Alignment: new endpoints to add, edit and remove entries in the narrative.
2026-11-04Brand Alignment: an answer’s citations include the pages the engine linked in its text (for example a ChatGPT answer naming its source as a link), as Asky’s monitoring always counted them. This adds pages to an answer’s cited_sources and to sources, for new scans and for answers already collected, so past scans’ source counts can rise.
2026-11-02Brand Alignment: changes are given against the previous scan even where the monitoring setup changed between the two, as the app now compares: history’s outcomes_change, fact history’s outcomes_change and source history’s change are null for the first scan only, and perception’s comparable_with_previous is true whenever there is a previous scan, with change_since_previous filled in. setup_changed and perception_change_reason still mark where the setup or Asky’s analysis changed.
2026-11-01Brand Alignment: source history adds mentions to each scan (and to by_engine), the mentions of your tracked attributes that trace back to the source, by sentiment.
2026-11-01Brand Alignment: where no check ran on an answer, a passage about an attribute falls back to the engine’s citation next to it, as a statement does: an answer’s traits on placement, and the mentions of sources and source history.
2026-11-01Brand Alignment: each source adds mentions, the mentions of your tracked attributes that trace back to the page, by sentiment. The attribute sentiment response’s counts is renamed counted: whether the answer still counts for the attribute.
2026-11-01Brand Alignment: each passage of a perception mention adds reason, Asky’s reason for reading it in its sentiment, on answers analyzed from this date.
2026-11-01Brand Alignment: history adds perception_change_reason to each scan, telling a break in the perception trend that your setup caused (setup) from one where Asky changed how it reads answers (analysis).
2026-10-30List responses: each citation in segments carries start and end, where its marker sits in full_response, counted in Unicode code points. New include_citations parameter returns every source an answer carries, including the ones the engine did not place in the text, with whether the page mentions your brand and which competitors it names.
2026-10-30Brand Alignment: the answer endpoint’s traits lists every trait a cited page carries, whatever its sentiment, no longer only the negative or mixed ones. New attribute sentiment endpoint to correct the sentiment Asky read for an attribute in an answer. Attribute counts are mentions, one per passage: perception sentiment counts and from_scan_questions/from_tracked_prompts count mentions, and new mention_count fields join mentioned_in (answers) in attributes, by_engine and change_since_previous; the sentiment filter returns answers with a passage in that sentiment. History adds each trended attribute’s mention_count, and its sentiment shares are of mentions. Scans from before passages hold one passage per answer, so their numbers are unchanged.
2026-10-29Brand Alignment: a statement’s sources in the answer and fact endpoints are the sources behind it (the pages the answer cited that state it), no longer the citations the engine placed beside it, except on a page Asky has not read. The answer endpoint adds traits, the negative or mixed traits the answer gave your brand that a cited page carries, with the sources behind each. Both add sources_checked.
2026-10-11Products & services: the kind values line and service are removed. Existing rows were migrated to category and product; product covers products and services alike, and a category is the one grouping level. parent_product_id now names a category only.
Pending launchInitial release
Last updated on