---
title: "AIR API: A Shared Retrieval Backbone for AI-Assisted Workflows at Spotware"
description: "AIR API is an AI-driven retrieval platform built at Spotware that serves grounded answers from corporate knowledge sources to AI assistants, support automation, and day-to-day workflows — exposed via a REST API and an MCP server so every AI tool in the company can reach the same trusted information."
date: "2025-02-01T07:00:00Z"
last_updated: "2026-07-27"
build_time: "2026-08-25T06:39:07Z"
project_name: "AIR API — AI Retrieval API"
project_description: "An AI-driven retrieval platform that serves grounded answers from corporate knowledge sources (Help Centre + cTrader Admin Guide) to any AI assistant, support automation, or team workflow inside Spotware — through a REST API and a standards-compliant MCP server, with automatic twice-daily content refresh."
status: "Active"
period_from: "2025-04-10"
client: "[Spotware Systems](https://www.spotware.com/)"
related_skills: ["artificial-intelligence","product-management","project-management","system-analysis","stakeholder-management","software-development","python","quality-assurance","rest-api","openapi-specification","databases","docker","devops","kubernetes","mcp"]
related_projects: ["aila","youtrack-mcp-server","agile-coach-pro"]
related_experience: ["ai-product-manager-at-spotware"]
keywords: ["AI Retrieval","Retrieval-Augmented Generation","RAG","LangGraph","LangChain","Vector Search","Embeddings","Cross-Encoder Reranking","Query Decomposition","Structured Output","LangSmith","Model Context Protocol","MCP Server","FastAPI","Python","Kubernetes","Knowledge Base Automation","AI Product Management"]
license: "https://creativecommons.org/licenses/by/4.0/"
canonical: "https://www.alexfeel.info/projects/air-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: 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.
- **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, 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 and timings for calibration.

## 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, so teams get grounded, source-linked answers directly in the assistant they already use.
- **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](https://www.spotware.com/news/2025-highlights/): _"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](/experience/ai-product-manager-at-spotware/).


## Site index

- [llms.txt](https://www.alexfeel.info/llms.txt)
- [Complete index](https://www.alexfeel.info/llms-index.txt)