> ## Documentation Index
> Fetch the complete documentation index at: https://handbook.aiql.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Middleware API

> Ingestion that turns sources into structured, queryable knowledge

The **Middleware API** at [api.aiql.io](https://api.aiql.io) turns documents and other sources into a structured knowledge layer, then answers natural-language questions over that layer. [Studio](/products/studio), [Observatory](/products/observatory), the [Python SDK](/products/python-sdk), and the [TypeScript SDK](/products/typescript-sdk) call it. Developer reference lives at [docs.aiql.io](https://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](/products/artifacts-api).

## The pipeline

Ingestion is four steps from source to structured records.

<Steps>
  <Step title="Convert">
    Normalize diverse sources into clean, machine-readable text. The formats convert accepts are listed below.
  </Step>

  <Step title="Split">
    Break that text into pieces that preserve document structure — sections and headings — so later steps see coherent units rather than arbitrary cuts.
  </Step>

  <Step title="Shape">
    Discover the schema of the content: classes, properties, and relationships. A customer can also supply a schema and skip discovery.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.

<Columns cols={2}>
  <Card title="Documents" icon="file-lines">
    `PDF`, Word (`docx`), PowerPoint (`ppt`, `pptx`), Markdown (`md`), and plain text (`txt`).
  </Card>

  <Card title="Scans and images" icon="image">
    `JPEG`, `PNG`, `TIFF`, `WebP`, `GIF`, and `BMP`.
  </Card>

  <Card title="Spreadsheets" icon="table">
    Excel (`xls`, `xlsx`) and `CSV`.
  </Card>

  <Card title="Structured data" icon="code">
    `JSON`, JSON Lines (`jsonl`, `ndjson`), `HTML`, and `XML`.
  </Card>

  <Card title="Mail and transcripts" icon="envelope">
    Email (`eml`) and captions (`vtt`).
  </Card>

  <Card title="Engineering models" icon="cube">
    `IFC` building models and `BCF` issue packages (`bcf`, `bcfzip`).
  </Card>

  <Card title="Audio and video" icon="video">
    Audio (`mp3`, `wav`, `m4a`) and video (`mp4`, `mov`).
  </Card>
</Columns>

Convert uses [layout](/products/models-layout) and [OCR](/products/models-ocr). Shape and extract use [pipeline](/products/models-pipeline) language models. Queries use [answer](/products/models-answers) models over [embeddings](/products/models-embeddings). See [Models](/products/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](/products/studio). External systems brought in through the [Connectors API](/products/connectors-api) feed this same ingestion.

Queries and [Observatory](/products/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](https://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](https://docs.aiql.io/mcp/overview). This handbook does not reproduce that setup.

## How it is offered

Typed clients are the [Python SDK](/products/python-sdk) and [TypeScript SDK](/products/typescript-sdk). Hosting follows [self-service SaaS](/commercial/saas) or a [custom deployment](/commercial/custom) in a [data region](/commercial/data-regions).

Related APIs: [Artifacts API](/products/artifacts-api), [Connectors API](/products/connectors-api), [Ontologies API](/products/ontologies-api), [Terminology API](/products/terminology-api).