AI Power Ups

Menu

Contents

Concepts

Stability and versioning

Which parts of a response are contract, which are documented behaviour, and which are shaped by the provider. Honest labels, so that you can decide what to type and what to pass through.

Three stability tiers

TierMeaningCovers today
StableRequests and response envelopes covered by the API contract and published in the public OpenAPI document. Contract changes are dated in the changelog.Transport, auth, the error envelope, catalog and inspect responses, all 29 request bodies, the execute and record follow-up envelopes, the follow-up request, the Sharpen request and response, the account response.
DocumentedKeys listed on the capability page, produced deterministically by our adapter, omitted when the source has no value. The wire schema still allows additional keys, so treat them as optional and ignore unknown ones.Result-record keys and the detail objects explicitly documented on each capability page.
Provider-shapedPassed through from the source with light normalisation; may change when the provider changes. Produced deliberately and covered by the same error contract, but not something to branch on.Other record detail objects, notes[] strings, filters[] labels.

"Unsupported" is reserved for things the API refuses: more on a single-result capability, a record action the catalog does not list, an unknown key.

Versioning

  • The path prefix is /v1. Changes we treat as additive: new capabilities, new optional request fields, new record keys, new record actions, new notes strings, new x-aipa-* extensions.
  • Changes we treat as breaking: removing or renaming a key, changing a type, tightening required, changing an action's semantics or cost class. These are announced through the deprecation mechanism below before they happen.
  • The public OpenAPI document carries info.version and info.x-aipa-contract-date (currently 2026-09-22); generated clients should record the date they were built from. Every contract change is listed on the changelog.

Deprecation mechanism

How a breaking change is announced:

  1. The operation is marked deprecated: true in the public OpenAPI document and the change is posted on the changelog with the planned sunset date, when known.
  2. Affected calls carry a Deprecation header (RFC 9745, @<unix-seconds>) and, once the date is fixed, a Sunset header (RFC 8594, HTTP-date). Nothing is deprecated today, so no call carries them yet.
CI checks the generated OpenAPI document against a committed snapshot. A change requires updating that snapshot; this detects drift but does not prove compatibility. Documented record and detail schemas are checked against fixtures, without adding validation to live responses. No minimum sunset notice period is currently promised; consult the changelog and response headers for each change.

Current behaviour

  • No idempotency key. Execute is not idempotent and a retry after a client-side timeout can bill twice under the conditions described under retries. The one-call-per-account admission limits concurrent work; it does not deduplicate retries. The API does not support an Idempotency-Key header.
  • Response record schemas. The documented keys of every capability are published as <Name>Record components (optional properties, extra keys allowed). Existing source fixtures check these schemas, but do not cover every capability or provider path. The schemas are not yet used to validate responses on the wire. The record actions whose detail our code builds in full (route details, YouTube details and transcript, flight details, SEC filing and fact views, legal.read chunks) are published the same way as <Name><Action>Detail components; other details remain provider-shaped. Promoting any of these to the stable tier is a later decision.
  • Cache-only details. Record actions served from the search snapshot (markets.quote, jobs.search, news.search, trends.search, transit.routes, fitness.exercises, legal.read, navigation.route) answer 410 session_expired when the stored detail is gone; executing the search again resolves it. This replaced three capability-specific codes on 2026-09-22.

Machine-readable sources