Skip to main content
The Middleware API at api.aiql.io turns documents and other sources into a structured knowledge layer, then answers natural-language questions over that layer. Studio, Observatory, the Python SDK, and the TypeScript SDK call it. Developer reference lives at docs.aiql.io. This handbook does not reproduce that reference.

​
What it covers

  • Workspaces — the container for ingested data, members, and downstream work.
  • Ingestion — a managed job that runs convert, split, shape, and extract, then loads the result into a workspace.
  • Queries — natural-language questions over already ingested workspace data.
  • Sources — inspection of ingested documents and derived structure.
Observatory work products — canvases, dashboards, documents, and presentations — are the Artifacts API.

​
The pipeline

Ingestion is four steps from source to structured records.
1

Convert

Normalize diverse sources into clean, machine-readable text. The formats convert accepts are listed below.
2

Split

Break that text into pieces that preserve document structure — sections and headings — so later steps see coherent units rather than arbitrary cuts.
3

Shape

Discover the schema of the content: classes, properties, and relationships. A customer can also supply a schema and skip discovery.
4

Extract

Pull matching facts and links as structured records. The output is entities and relationships shaped by that schema, not a bag of retrieved passages.
Ingestion runs the four steps as one managed job and loads the result into a workspace. Each step is also callable as a standalone tool.

​
Source formats

Convert accepts the formats below. A ZIP archive of supported files is unpacked; each file inside is ingested as its own source. Web pages can be passed as URLs.

Documents

PDF, Word (docx), PowerPoint (ppt, pptx), Markdown (md), and plain text (txt).

Scans and images

JPEG, PNG, TIFF, WebP, GIF, and BMP.

Spreadsheets

Excel (xls, xlsx) and CSV.

Structured data

JSON, JSON Lines (jsonl, ndjson), HTML, and XML.

Mail and transcripts

Email (eml) and captions (vtt).

Engineering models

IFC building models and BCF issue packages (bcf, bcfzip).

Audio and video

Audio (mp3, wav, m4a) and video (mp4, mov).
Convert uses layout and OCR. Shape and extract use pipeline language models. Queries use answer models over embeddings. See Models.

​
What lands in the workspace

Sources stay inspectable. Encoded facts sit in the workspace with lineage back to the source they came from. The schema can keep being refined in Studio. External systems brought in through the Connectors API feed this same ingestion. Queries and Observatory reason over that layer rather than searching documents and guessing.

​
MCP

The same Middleware API is offered as a Model Context Protocol (MCP) server at api.aiql.io/mcp. Compatible agents and clients call convert, split, shape, extract, workspaces, ingestions, and queries without a custom integration. Authentication is an API key, or OAuth for interactive clients. The same key works on the HTTP API and on MCP. Developer setup lives at docs.aiql.io/mcp/overview. This handbook does not reproduce that setup.

​
How it is offered

Typed clients are the Python SDK and TypeScript SDK. Hosting follows self-service SaaS or a custom deployment in a data region. Related APIs: Artifacts API, Connectors API, Ontologies API, Terminology API.