/ docs · functional specification

The full platform
functional reference.

Every functional area of AI API Mapper documented at implementation depth so architects, security reviewers, and platform engineers can evaluate the product with real technical context.

Changelog · Changelog

Changelog

This page summarises each platform release. Full technical detail is available in the repository.


Version 1.1.6 — 2026 Q2

Downstream client certificate (mTLS) authentication. Administrators can now bind a downstream target authentication profile to a client certificate, so the Runtime authenticates to the downstream API via mutual TLS instead of a bearer token or header.

This release also makes semantic enrichment resilient to interruption. An enrichment run that stops partway — a worker crash, or a run outliving the message broker's delivery window — is now detected, re-queued, and resumed from the last completed chunk, instead of leaving the mapping locked with a frozen progress bar and no error.

Changes in this release:

  • New ClientCertificate downstream authentication strategy, alongside the existing API key, Basic, bearer, OAuth, workflow, and SOAP strategies
  • Auth profile form: upload a PFX/PKCS#12 certificate file directly, select the secret holding its private key password, and optionally enter an expected certificate thumbprint
  • Uploading a certificate creates a new secret in the existing secret store and selects it automatically — no separate binary-secret workflow to learn
  • Client certificates are presented on the TLS handshake for both REST/OpenAPI/OData tools and SOAP tools
  • Governance audit captures for client-certificate-authenticated invocations never contain the certificate or password material
  • Mapping editor: editing is now strictly limited to Draft/Proposed mappings (no more silent auto-clone-to-draft on Approved/Published), and "Cancel draft" is now "Cancel version," available from Draft through Approved
  • Mapping editor: semantic enrichment warnings are shown as their own alert instead of being folded into the change-summary text, and reference attachments can now be attached when creating a mapping proposal, not just when re-requesting enrichment
  • Trusted Identity Providers page redesign: a sectioned provider details view, a searchable claim mapping profile picker, a combined name-or-issuer search box, and refresh/loading indicators matching the rest of the portal
  • The built-in platform identity provider (used for device flow and web session sign-in) is now flagged as a system provider at the database level and shown with a "System" badge; it can no longer be edited or deleted from the admin UI
  • Claim Mapping Profiles page redesign to match: a sectioned profile details view (claims shown as badges instead of raw JSON), a redesigned enabled/disabled toggle, a debounced server-side name search, and the same refresh/loading indicators
  • The built-in "default" global claim mapping profile is now flagged as a system profile at the database level and shown with a "System" badge; it can no longer be edited or deleted from the admin UI
  • Credential Workflows page refresh: debounced name search, a searchable tenant filter, and isFetching-driven refresh/loading indicators matching the rest of the portal
  • Credential Workflows step editor: bigger, easier-to-hit move-up/move-down/delete buttons; the BuildCredentialSet step's collapsed summary now shows extra headers/query parameters/cookies when no auth scheme is selected; and BuildCredentialSet must now be the workflow's last step, with the editor enforcing that automatically
  • Fixed a shared searchable-dropdown bug where an open menu pushed surrounding layout taller and could render behind other panels, affecting every page using the searchable tenant/entity picker
  • Secret Store page refresh: debounced name search, isFetching-driven refresh/loading indicators, and an "Add connection" button matching the other primary create actions
  • Secret Store grid: Store info, Created at, and Updated at are now combined into a single Details column placed after Tenant, matching the more compact activity-column layout used elsewhere
  • Secret details modal redesign: a sectioned view (store type and tenant scope badges, then a details grid) instead of a flat key/value list with raw JSON
  • Key Vault connection modal: the Enabled checkbox is now a labeled toggle card consistent with the enabled/disabled switches used on other pages
  • Outbound Allowlist page refresh: debounced host/name search and isFetching-driven refresh/loading indicators matching the rest of the portal
  • Outbound Allowlist grid: the Description column was dropped in favor of showing the description beneath the entry name, and Subdomains/Status are now badges instead of plain text
  • Allowlist entry details modal redesign: a sectioned view (active/scope/subdomains badges, then a details grid, then the description) instead of a flat key/value list with raw JSON
  • Create/Edit allowlist entry modal: the Allow subdomains and Entry active checkboxes are now labeled toggle cards consistent with the enabled/disabled switches used on other pages
  • LLM Connections page refresh: connection name/status/provider filtering moved server-side with a debounced name search, plus isFetching-driven refresh/loading indicators matching the rest of the portal
  • LLM Connections: new connection details view — a sectioned, read-only summary (scope/status badges, provider, credential handling, model profiles, tenant assignments, timestamps) opened from a new "View details" row action
  • LLM Connections: the tenant assignments "Remove" action is now a proper button instead of a link-styled button, and the connection/model profile Enabled checkboxes are now labeled toggle cards consistent with other pages
  • Client Applications page refresh: debounced name/client ID search and isFetching-driven refresh/loading indicators matching the rest of the portal
  • Client application details modal redesign: a sectioned view (status badge, tenant, timestamps, then dedicated description and system prompt sections) instead of a flat key/value list with raw JSON
  • Create/Edit client application modal: the Active checkbox is now a labeled toggle card consistent with the enabled/disabled switches used on other pages
  • API Key management page refresh: debounced name/description search and isFetching-driven refresh/loading indicators matching the rest of the portal
  • API key details modal redesign: a sectioned view (overview with status badge and timestamps, description, and claims shown as badges) instead of a flat key/value list
  • Edit API key modal: the Active checkbox is now a labeled toggle card consistent with the enabled/disabled switches used on other pages
  • Target Systems page refresh: debounced name search and isFetching-driven refresh/loading indicators on both the target systems grid and the auth profiles grid, matching the rest of the portal
  • Target system and auth profile details modals redesign: sectioned views with status/strategy/tenant badges instead of a flat key/value list, and the auth profile modal now shows the strategy's additional configuration and credential caching settings as structured fields instead of raw JSON
  • Create/Edit target system and auth profile modals: the Active checkbox is now a labeled toggle card consistent with the enabled/disabled switches used on other pages, and the auth profile form's raw-JSON "Preview generated configuration" section has been removed
  • Tools Management page refresh: debounced mapping/toolset name search and isFetching-driven refresh/loading indicators matching the rest of the portal
  • Tools Management: new read-only toolset details view — a sectioned summary (identity, default downstream settings and policy, client assignments, per-endpoint effective routing and access policy) opened from a new "View details" row action, available to every user regardless of manage access
  • Updated inline help content for the Client Applications, API Key management, Target Systems, and Tools Management pages to describe the new search, refresh, details, and toggle behavior
  • Monitoring Dashboard: the Reset filters and Search buttons now show icons, the audit table groups Category and Action into a single column, and the audit event detail view is now organized into sections (Overview, Actor, Request context) with status/category/action shown as badges instead of a flat field list
  • Monitoring Dashboard: audit event dimensions that contain JSON-encoded values are now pretty-printed instead of showing as a raw string
  • Monitoring Dashboard: CSV/JSON export now asks for confirmation before running when the matching result set is larger than the 200-row export limit, stating the total match count so a truncated export is never triggered by mistake
  • Updated inline help content for the Monitoring Dashboard to describe the new column layout, detail view, and export truncation confirmation
  • Enrichment Dashboard: the Reset filters and Search buttons now show icons, matching the Monitoring Dashboard
  • Enrichment Dashboard: added a Tenant column using the shared tenant display, and combined the Status and Progress columns into a single "Status & Progress" column
  • Enrichment Dashboard: added a selectable auto refresh interval (off, 3, 5, 10, 30, or 60 seconds); each refresh is now scheduled after the previous request finishes instead of on a fixed clock, so a slow request can no longer overlap the next poll
  • Updated inline help content for the Enrichment Dashboard to describe the new Tenant and Status & Progress columns and the auto refresh control
  • Call Flow page: the Reset filters and Search buttons now show icons, matching the Monitoring and Enrichment dashboards
  • Call Flow page: added a Tenant column using the shared tenant display, and combined the Type and Tool/Mapping columns into a single column
  • Updated inline help content for the Call Flow page to describe the new Type/Tool/Mapping and Tenant columns
  • Semantic enrichment now survives interruption: a run that stops because its worker crashed, or because the message broker withdrew the job for running longer than its maximum unacknowledged time, is automatically re-queued and resumes from the last completed chunk instead of restarting from the beginning
  • Enrichment runs report liveness on a timer while they are being processed, so a run that is merely slow is no longer mistaken for one that has stopped
  • A run whose worker is still running but stops making progress — stuck waiting on an LLM call that never returns — is now detected as hung and recovered, instead of appearing healthy indefinitely
  • Recovery signals the stuck attempt to stop before re-queueing the run, so an abandoned run stops consuming its LLM budget
  • Every completed enrichment pass is now recorded, so a resumed run only pays for the chunks it never finished — a 29-chunk run interrupted after 7 chunks resumes at chunk 8
  • A scheduled sweep releases enrichment runs that cannot be recovered, marking them failed with the number of chunks completed and unlocking the mapping, so a wedged run no longer needs manual database intervention
  • The sweep also reports how many enrichment runs are in progress and how recently each reported liveness, making a slow run distinguishable from a stuck one in the logs
  • Raised the RabbitMQ maximum unacknowledged-delivery time from 30 minutes to 3 hours, so a long enrichment run against a slow LLM is no longer withdrawn mid-run

Version 1.1.5 — 2026 Q2

OData/CSDL + Microsoft Graph API onboarding. Administrators can now onboard OData v4 services — including Microsoft Graph — as first-class imported APIs alongside OpenAPI and SOAP/WSDL, with a shared preview/curation workflow that also now protects OpenAPI and WSDL imports from metadata explosion.

Changes in this release:

  • New OData contract protocol with Generic and MicrosoftGraph import dialects; CSDL XML import from uploaded content or a remote metadata URL
  • CSDL is parsed into a canonical semantic model (entity types, complex types, enums, entity sets, singletons, navigation, actions/functions) before any translation, so OData semantics survive rather than being flattened directly into the import model
  • Entity sets and singletons materialize into constrained CRUD operations that honor InsertRestrictions/UpdateRestrictions/DeleteRestrictions OData capability annotations — read-only entity sets no longer get mutating tools generated for them
  • Bound/unbound actions and functions become first-class operations; single-hop navigation properties can be optionally included
  • Microsoft Graph dialect applies Graph-aware naming, permission hints, and conservative v1.0-only defaults
  • New standardized curation stage shared by OpenAPI, WSDL, and OData imports: an operation deny-list, an allow-list/explicit-selection mode, a tag/group allow-list, a path-prefix allow-list, a maximum-persisted-operation-count guardrail, and a mandatory explicit-selection step for oversized contracts, enforced before anything is persisted
  • New Portal import UX: dialect selector, a "Preview operations" action showing the full candidate catalog with inclusion/exclusion reasons, and a selection checklist for committing only the chosen operations. The wizard's own curation controls are just the checkbox-based preview selection plus, for OData, generation-time namespace/entity-set/path-prefix allow-lists — the tag/group allow-list, path-prefix allow-list, and deny-list remain available on the curation service/API but are not surfaced as separate wizard inputs, since the checkbox selection already covers the same need
  • Enum members, entity keys, and optimistic-concurrency tokens are now preserved on the imported schema instead of being flattened to plain strings
  • Stable OperationKey format so mapping version upgrades correctly preserve endpoint identity across re-imports
  • Structured logs, import metrics, and governance audit entries for every import mode, including the two new-version import endpoints which previously had no audit coverage
  • Hardened CSDL XML parsing against DTD/external-entity expansion; remote metadata fetches continue to go through the platform's outbound URL validator

Version 1.1.4 — 2026 Q2

Device Authorization Grant (RFC 8628) plus browser-based runtime OAuth authorization hardening. AI agents and CLI tools can now authenticate and receive portal-equivalent credentials through operator-approved browser flows, and the browser authorization path now supports external-provider sign-in, MFA, and explicit consent.

Changes in this release:

  • Agents call a new initiation endpoint and receive a short user code (XXXX-YYYY) to display to the operator alongside a verification URL
  • A new /device page in Portal.Web lets operators look up the active session, sign in if not already authenticated, and approve or deny the request with a single action
  • The agent polls a dedicated token endpoint and receives an access token and refresh token once the operator approves
  • Runtime OAuth browser authorization now reuses the full Portal login experience instead of a separate minimal login page
  • OAuth authorization requests survive external-provider redirects, MFA verification, and tenant/context handoff so the flow can complete for accounts that require those steps
  • Already-authenticated operators must explicitly confirm runtime access before the authorization callback is completed
  • All device flow events — initiated, approved, denied, and token issued — are written to the governance audit trail with a shared session identifier for lifecycle correlation
  • Stale sessions (pending past expiry) are expired nightly; terminal sessions are purged after a configurable retention window by the existing data lifecycle job
  • Revoking a session — from the Portal UI, an administrator action, or an automatic response to detected refresh-token theft — now takes effect immediately against the Runtime, not just against future token refreshes. A revoked session's access token is rejected on its next use, on every host, rather than remaining valid until its own natural expiry

Version 1.1.3 — 2026 Q2

Semantic Enrichment Attachments. Administrators can now attach reference documents to an enrichment request to give the LLM additional context beyond the imported API definition.

Changes in this release:

  • Attach up to 5 reference files (.txt, .md, .pdf) per enrichment request with a combined size limit of 1 MB
  • Uploaded content is automatically scanned for prompt injection before the enrichment job is submitted; suspicious content is rejected before any processing begins
  • Reference documents are distilled once into a compact glossary, and only the entries relevant to each operation are injected into that operation's LLM pass — keeping large documents within the prompt budget instead of re-sending them on every chunk (configurable; falls back to verbatim injection)
  • File names, sizes, and content fingerprints are recorded on the enrichment run and visible in the run detail view
  • Attachment controls are available in both the standalone enrichment request modal and the new-version enrichment flow in the mapping editor
  • Files can be added across multiple picks and removed individually before submitting

Version 1.1.2 — 2026 Q2

Mapping annotation hint management. Administrators can now set MCP behavioral annotation hints per endpoint directly in the mapping editor, receive LLM-inferred hints through the semantic enrichment pipeline, and review proposed hints in the enrichment proposal panel before applying them to the draft.

Changes in this release:

  • Four per-endpoint annotation hints: Read-only, Destructive, Idempotent, and Open-world — each tri-state (Yes / No / Not set)
  • New "Endpoint annotation hints" enrichment target in the semantic enrichment request modal
  • LLM prompt and response schema updated to generate and receive annotation hints
  • Annotation diffs shown in the enrichment proposal panel alongside name and description changes
  • Inline help updated with annotation hint field documentation

Version 1.1.1 — 2026 Q2

MCP 2025-11-25 protocol compliance. The Runtime now advertises and implements the full MCP 2025-11-25 specification, including prompts, cursor-based pagination, and tool annotation hints on the wire.

Changes in this release:

  • Protocol version bumped to 2025-11-25 on the MCP initialize response
  • New ping handler returning an empty object as required by the specification
  • prompts/list and prompts/get expose toolset system prompts as user-controlled prompts (slash-command / menu items) alongside the existing resources surface
  • Tool annotation hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) emitted on the MCP wire for each tool; per-toolset annotation overrides configurable from the Portal
  • Cursor-based pagination on tools/list, resources/list, and prompts/list with configurable page sizes

Version 1.1.0 — 2026 Q2

API Onboarding Versioning release. Introduces API definition families that group multiple imported versions of the same downstream API, per-revision version labels and current-version designation, version compatibility reports, version-aware mapping draft creation that preserves endpoint IDs where operations match across API versions, and durable external governance audit delivery.

Changes in this release:

  • API definition families with multi-revision tracking and current-version promotion
  • Import new API version flow (URL and content) with version label and set-as-current options
  • Family Versions panel on API cards listing all revisions
  • Version compatibility view comparing two revisions with breaking-change classification
  • Delete protection for imported API definitions referenced by mapping versions
  • API-version-targeted mapping draft creation with endpoint GUID stability
  • External audit delivery fan-out with REST, syslog, SQL Server, and PostgreSQL compliance targets plus operational target monitoring/management in the Portal

Version 1.0.0 — 2026 Q1

First stable release. Full foundational platform including Portal, Portal API, Runtime, Jobs Worker, Gateway, and Database Migrator. Multi-tenant architecture, OpenAPI and SOAP/WSDL import, mapping proposal workflow, LLM-powered semantic enrichment, MCP toolset authoring, downstream authentication strategies, governance audit trail, area-based role model, and external identity provider federation.