---

name: api-and-deployment description: "Configure and deploy txtai Application/API services, OpenAI-compatible endpoints, MCP, auth, custom routes, clusters, containers, cloud patterns, observability, and console caveats." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

API and Deployment

Use this sub-skill when the user wants to run txtai as a configured application, FastAPI service, OpenAI-compatible endpoint, MCP server, secured internal service, custom API, distributed embeddings cluster, container/cloud deployment, or console-driven index explorer.

Route away from this sub-skill when the user is asking for detailed index/query authoring, pipeline design, or agent prompting internals:

• Use ../embeddings-search/SKILL.md for Embeddings indexing, SQL, hybrid, graph, object, and search-query design.
• Use ../pipelines-and-workflows/SKILL.md for pipeline selection, workflow task authoring, scheduling, and generator consumption.
• Use ../agents-and-llm-orchestration/SKILL.md for LLM, RAG, Agent tools, prompts, templates, and model backend behavior.

Fast Path

1. Install API support in the target environment.

   pip install "txtai[api]"
   

2. Generate a safe starter config without launching a server.

   python skills/txtai/sub-skills/api-and-deployment/scripts/api_config_template.py \
     --template secure-readonly --output app.yml
   python skills/txtai/sub-skills/api-and-deployment/scripts/api_config_template.py --validate app.yml
   

3. Start FastAPI/Uvicorn from the directory that contains app.yml.

   CONFIG=app.yml uvicorn "txtai.api:app" --host 127.0.0.1 --port 8000
   

4. Inspect live route docs at http://127.0.0.1:8000/docs and smoke-test a route enabled by the config.

   curl "http://127.0.0.1:8000/count"
   

Configuration Model

The API is backed by Application(config, loaddata=True). The config can be a YAML file path, YAML string, or dict. When loaddata=True, a saved index at top-level path is loaded if it exists; otherwise models/components are constructed from config.

Core top-level YAML keys:

• path: saved embeddings index path for API load/save; one API process serves one primary index path.
• writable: false by default; required for /add, /index, /upsert, /delete, and /reindex.
• reindex: false by default; only enable for trusted admin clients because /reindex accepts new config.
• embeddings: creates/loads an embeddings index and enables embeddings/search routes.
• Pipeline keys such as summary, labels, textractor, llm, rag, translation: create matching pipeline instances and routes.
• workflow: defines named workflows and enables /workflow.
• agent: defines named agents and enables /agent.
• openai: true enables /v1/... OpenAI-compatible routes.
• mcp: true or a dict enables /mcp and exports enabled API routes as MCP tools.
• cluster: configures an API aggregator over shard URLs.

See references/configuration-and-routes.md for route families, request shapes, response formats, auth, MCP, custom endpoint hooks, and Application details.

Safe Service Patterns

Prefer a two-process or two-config deployment for mutable indexes:

• Admin/build process: private network, writable: true, optional /add and /index, no public ingress.
• Public query service: writable: false, reindex: false, token auth, TLS at a reverse proxy, only route keys needed by clients.
• Treat /reindex as a trust boundary even when token auth is enabled; it accepts config and optional function names.
• Keep model and index caches on persistent volumes in containers/serverless to avoid repeated downloads and cold starts.

Token auth uses a SHA-256 digest in TOKEN, while clients send the raw token in the Authorization header:

TOKEN="$(python -c 'import hashlib; print(hashlib.sha256(b"change-me").hexdigest())')" \
CONFIG=app.yml uvicorn "txtai.api:app" --host 127.0.0.1 --port 8000

curl -H "Authorization: Bearer change-me" "http://127.0.0.1:8000/count"

For TLS, prefer a reverse proxy terminating HTTPS and forwarding to a loopback/internal Uvicorn service.

See references/deployment.md for Uvicorn, Docker, model caching, cloud/serverless, Kubernetes/Knative, clustering, and observability patterns.

Route Activation Rules

Routes are included based on top-level config keys. If a key is absent, the corresponding route family is absent even though txtai is installed.

Common route groups:

• embeddings: GET /search, POST /batchsearch, POST /add, GET /index, GET /upsert, POST /delete, POST /reindex, GET /count, transform/explain/object routes.
• workflow: POST /workflow with name and elements.
• agent: POST /agent with name, text, optional maxlength, and optional stream.
• llm and rag: /llm, /batchllm, /rag, /batchrag when those pipeline keys are configured.
• Pipeline keys: route families such as /summary, /label, /translate, /textract, /segment, /caption, /tabular, /rerank, and batch variants.
• openai: /v1/chat/completions, /v1/embeddings, /v1/audio/speech, /v1/audio/transcriptions, /v1/audio/translations.
• mcp: /mcp mounted by FastApiMCP when configured.

embeddings also enables similarity routes if no separate similarity key is present. cluster without embeddings still includes embeddings routes for the aggregator.

OpenAI-Compatible Use

Set openai: true to expose OpenAI-style routes. The actual backend still comes from txtai config:

• Chat model matching an agent name calls that agent.
• Chat model: embeddings searches the embeddings index and returns the best result text.
• Chat model matching a pipeline name calls that pipeline, except llm uses the default LLM pipeline path.
• Chat model matching a workflow name runs the named workflow on the first user message.
• /v1/embeddings uses the configured embeddings transformer; the model field is echoed in the response.

If an OpenAI client reports a missing model or route, check both openai: true and the backing agent, workflow, llm, rag, embeddings, or pipeline section.

MCP, Custom Endpoints, and Auth

Use mcp: true for defaults or a dict with clientargs and mcpargs. MCP exposes enabled API endpoints as tools at /mcp; it does not design tools or prompts for you.

Use environment hooks for advanced service customization:

• API_CLASS=package.module.CustomAPI uses a subclass/factory target instead of the default API class.
• DEPENDENCIES=package.module.Dependency adds FastAPI dependencies such as custom auth or middleware.
• EXTENSIONS=package.module.Extension runs extension hooks that can include custom routers.

Keep extension modules importable from the service environment and avoid referencing local checkout-only paths.

Console Caveat

The console is an index/application explorer, not a standard argparse CLI. python -m txtai.console --help treats --help as the initial index/config path and may fail trying to load it. Use the console with a saved index path or YAML config path:

python -m txtai.console path/to/index
python -m txtai.console app.yml

Inside the console, commands include .load, .config, .limit, .highlight, and .workflow; plain text runs a search query.

Validation Checklist

Before handing an API deployment back to a user, verify:

• Config parses as YAML and expected top-level route keys are present.
• API extras are installed; from txtai.api import app succeeds.
• CONFIG points to the intended config file from the service working directory.
• Public configs keep writable: false and reindex: false unless explicitly trusted.
• Token auth uses a SHA-256 digest in TOKEN and raw bearer token in client requests.
• /docs shows the expected route families; missing routes usually mean missing config keys.
• Accept: application/msgpack clients unpack MessagePack; JSON clients handle base64 for bytes/images.
• Container/cloud deployments mount index/model caches and satisfy CPU/GPU/system-library requirements.

Use references/troubleshooting.md for symptom-driven fixes covering extras, config paths, auth, OpenAI model routing, MCP dependencies, serialization, clusters, console path semantics, and cloud caveats.