AIR API — AI Retrieval API

Overview

AIR API is a shared AI retrieval platform built at Spotware to answer a simple but high-impact question: how do you let every AI tool in the company reach the same trusted knowledge without each team reinventing its own retrieval stack?

The platform serves grounded answers from corporate knowledge sources — the public Help Centre and the cTrader Admin Guide — through two interchangeable interfaces: a REST API for general AI systems and a standards-compliant MCP (Model Context Protocol) server for MCP-aware AI clients. Content is refreshed twice daily, so answers stay current without manual effort.

The Problem

Large corpora of documentation create three failure modes for AI-assisted work:

• Keyword search misses intent. Traditional search returns pages, not answers, and struggles with paraphrase, translation, and multi-part questions.
• Models can't ingest everything. AI systems cannot load a full knowledge corpus into context. Without a grounding layer, they hallucinate.
• Knowledge fragments per tool. Different teams use different AI tools (general-purpose assistants, agentic coding IDEs, bespoke apps). Without a shared retrieval layer, each re-indexes the same content and the company ends up with several competing, drifting copies of its own knowledge.

AIR API was built to solve all three at once — as a single retrieval backbone the rest of the company can plug into.

The Solution

AIR API exposes a compact, extensible retrieval surface:

• Two interchangeable interfaces: REST API + MCP server. The REST API integrates with general-purpose AI systems and custom applications; the MCP server integrates with MCP-aware AI clients. Both interfaces serve the same underlying capabilities, so teams can adopt whichever matches their stack.
• Multiple knowledge sources out of the gate. The initial rollout covers the public Help Centre and the cTrader Admin Guide, with the platform designed so additional corporate sources can be onboarded without rebuilding the core.
• Automatic twice-daily refresh. Content is ingested on a schedule so retrieval stays current as documentation evolves.
• Advanced retrieval quality. Questions arrive paraphrased, in different languages, and often several to a message — the platform handles all three, casts a wide net for recall, and returns the larger parent documents users actually need rather than isolated fragments, de-duplicated so a document is never returned twice for the same query.

Under the Hood

The retrieval surface is deliberately plain. The engineering behind it is not.

• A LangGraph pipeline, not a single call. Each request runs through a compiled StateGraph in Python — on the current LangChain/LangGraph v1 ecosystem, migrated as the frameworks moved: language detection, translation into the corpus language, complexity analysis and query decomposition, multi-rewrite expansion, multi-query ensemble retrieval with reciprocal rank fusion, cross-encoder reranking, and parent-document resolution — with conditional edges that skip translation for a query already in the corpus language and skip decomposition for a simple one. Every stage that calls a model asks for a Pydantic-validated structured output and carries an explicit fallback, so a bad generation degrades one stage instead of failing the request.
• Small models where they suffice, larger ones where they earn it. Each pipeline stage runs on the cheapest model that does its job — the quick classification and rewriting steps on small, fast models, translation and decomposition on a larger one — and query embeddings are cached (queries only, never documents), so a repeated question costs almost nothing to embed. These are the concrete mechanisms behind the platform's cost profile, not an accounting afterthought.
• Ingestion that writes documentation as well as reading it. Content is ingested idempotently on the twice-daily schedule, and part of the corpus is generated during ingestion itself: API reference documentation extracted from the trading platform's own SDK assembly and protocol definitions, folded into the retrievable corpus beside the hand-authored docs — so the retrieval layer answers questions no human ever sat down to document.
• Vector retrieval with a resilient embedding layer. Content is chunked, embedded, and stored in a vector database behind a fully asynchronous wrapper, with the parent documents held in a separate document store. The embedder tries providers in priority order and switches on the first soft failure, putting the failed provider on a five-minute cooldown, so one provider having a bad day does not take retrieval down with it. Child chunks are matched for precision and resolved to parent documents for usefulness, with a FlashRank cross-encoder re-scoring the candidates in between and folding each chunk's score back onto its parent.
• Served as an async FastAPI application. One process mounts the REST router and the MCP endpoints behind a composed lifespan — with REST and MCP authentication independently controlled, a deliberate design decision rather than one switch for both — runs on Gunicorn with a Uvicorn worker in a container, and deploys to Kubernetes as a Helm release with horizontal pod autoscaling, health probes, and the ingestion jobs as scheduled cron workloads — behind a GitLab CI pipeline where linting and the pytest suite have to pass before an image is ever built.
• Traced end to end. LangSmith tracing has been wired into the service since its first commit, so per-request traces, stage latency, and token usage are observable rather than inferred — and the retrieval stages log their own score distributions, deduplication counts, and percentile bands, telemetry built specifically so retrieval quality can be calibrated from production evidence instead of intuition.

Integrations

AIR API was designed from day one as a shared backbone, and in its first year it became the common retrieval layer behind several distinct workflows inside Spotware:

• AI-assisted development and analysis. Engineers, analysts, and product managers reach AIR API from MCP-aware tools such as Claude Code and Windsurf — the same retrieval surface powers coding, documentation, specification, and discovery workflows.
• Corporate ChatGPT, including as a Company Knowledge source. AIR API's MCP server meets the standards-compliant search and fetch method requirements needed to register as a Company Knowledge source in corporate ChatGPT — served from a dedicated endpoint designed for ChatGPT's knowledge and deep-research surfaces, running every knowledge source in parallel and degrading per source rather than failing the query — so teams get grounded, source-linked answers directly in the assistant they already use.
• Behind the corporate MCP Gateway. AI clients reach AIR API's MCP surface through the MCP Gateway — corporate sign-in, per-user authorization before every tool call, audited invocations — so the retrieval backbone inherits the company's tool-access security model instead of maintaining its own perimeter.
• Grounded ChatGPT assistant. Dedicated cTrader Support assistant is grounded on AIR API's retrieval, giving users direct, source-backed answers instead of raw documentation pages.
• Trader-support automation. AIR API serves retrieval for automated responses in the trader-support pipeline — a capability Spotware referenced publicly in its 2025 highlights announcement: "an AI-driven automation solution integrated with our internal knowledge base analyses incoming enquiries and generates responses automatically. As a result, 60% of trader enquiries are resolved by AI in an average of three minutes."

Measurable Impact — 2025 Year-End Results

Scoped to calendar year 2025, based on production observations:

• 8,000+ retrieval requests served.
• ~5 seconds average response time per request.
• Zero errors across the observed production volume.
• Under $8 total retrieval cost across that volume.

The low cost reflects a deliberate design choice: rather than pushing every query at a premium model, AIR API uses a layered retrieval pipeline that resolves most requests with inexpensive operations and reserves heavier AI calls for the parts of the query that actually need them.

Business Outcomes

• A single retrieval backbone that teams can plug into instead of each building their own. New AI use cases get grounded answers on day one, not after a multi-week retrieval project.
• Immediate unlock for downstream automation — including grounded assistants, agentic developer tooling, and automated trader support in Spotware's 2025 operations.
• Scalability by design. Additional corporate knowledge sources can be onboarded without rebuilding the core platform, so the retrieval layer grows with the company rather than being recreated.

My Role

As AI Product Manager at Spotware, I led AIR API from concept to production — framing it as a shared retrieval platform rather than a single-app tool, defining the quality bar and impact goals, picking the interfaces (REST + MCP) that would maximize downstream adoption, aligning engineering and the consuming teams (Support, analysts, developers, PMs), and driving integration into concrete workflows across the company. I also built it: the LangGraph retrieval pipeline, the embedding and reranking layers, the FastAPI and MCP surfaces, and the test suite are code I wrote and keep maintaining, and I own the CI pipeline and the deployment configuration alongside our platform engineers — the fixes as much as the roadmap. For the broader role context, see AI Product Manager at Spotware.