Environment:Neuml Txtai API Server Configuration

Knowledge Sources	txtai txtai API Docs
Domains	Infrastructure, API
Last Updated	2026-02-10 00:00 GMT

Overview

FastAPI-based API server environment with YAML configuration, token authorization, and MCP integration support.

Description

The txtai API server runs on FastAPI with uvicorn. Configuration is loaded from a YAML file specified via the `CONFIG` environment variable. The server supports token-based authorization (SHA-256 hashed), custom dependency injection, API extensions, distributed embeddings clustering, and Model Context Protocol (MCP) integration. Routes are conditionally included based on which components are configured in the YAML file.

Usage

Use this environment when deploying txtai as a REST API service, including Docker deployments, AWS Lambda (via Mangum), and distributed cluster configurations. Required for the API Deployment workflow.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	Linux recommended for production
Python	>= 3.10	Same as core
Network	HTTP port (default 8000)	Configurable via uvicorn

Dependencies

Python Packages

`fastapi` >= 0.94.0
`fastapi-mcp` >= 0.2.0
`uvicorn` >= 0.12.1
`aiohttp` >= 3.8.1
`httpx` >= 0.28.1
`pillow` >= 7.1.2
`python-multipart` >= 0.0.7

Credentials

The following environment variables control API server behavior:

`CONFIG`: Path to YAML configuration file for the API application
`API_CLASS`: Custom API class to instantiate (fully qualified Python class path)
`TOKEN`: SHA-256 hash of the authorization token for API access
`DEPENDENCIES`: Comma-separated list of custom FastAPI dependency classes
`EXTENSIONS`: Comma-separated list of API extension classes to execute at startup

Database Connection Variables

`SCORING_URL`: PostgreSQL connection URL for scoring backend
`ANN_URL`: Connection URL for ANN backend (pgvector)
`GRAPH_URL`: Connection URL for graph database backend
`CLIENT_URL`: Connection URL for client-server database

Cloud Storage Variables

`ACCESS_KEY`: Cloud provider access key for object storage
`ACCESS_SECRET`: Cloud provider access secret for object storage

Quick Install

# Install API dependencies
pip install txtai[api]

# Start the API server
CONFIG=config.yml uvicorn txtai.api:app

# With authentication
TOKEN=$(echo -n "your-secret-token" | sha256sum | cut -d' ' -f1) CONFIG=config.yml uvicorn txtai.api:app

Code Evidence

Configuration loading from `api/application.py:87-91`:

config = Application.read(os.environ.get("CONFIG"))
api = os.environ.get("API_CLASS")
INSTANCE = APIFactory.create(config, api) if api else API(config)

Token authorization from `api/application.py:39-42`:

token = os.environ.get("TOKEN")
if token:
    dependencies.append(Depends(Authorization(token)))

Authorization validation from `api/authorization.py:16-24`:

def __init__(self, token=None):
    self.token = token if token else os.environ.get("TOKEN")

def __call__(self, authorization: str = Header(default=None)):
    if not authorization or self.token != self.digest(authorization):
        raise HTTPException(status_code=401, detail="Invalid Authorization Token")

Extensions loading from `api/application.py:110-115`:

extensions = os.environ.get("EXTENSIONS")
if extensions:
    for extension in extensions.split(","):
        extension = APIFactory.get(extension.strip())()
        extension(application)

Common Errors

Error Message	Cause	Solution
`401 Invalid Authorization Token`	Missing or incorrect Bearer token	Ensure token matches SHA-256 hash in `TOKEN` env var
`No CONFIG environment variable`	YAML config path not set	Set `CONFIG=path/to/config.yml`
API routes not appearing	Component not configured in YAML	Add the component to your YAML config file

Compatibility Notes

Docker: Official Docker images include API dependencies. Use `CONFIG` env var to mount config.
AWS Lambda: Use `mangum` adapter with the FastAPI app for serverless deployment.
Distributed: Use `cluster` configuration for distributed embeddings across multiple nodes.
MCP: Set `mcp: true` in YAML config to enable Model Context Protocol endpoint.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment