---

name: backend-api description: "Operate TaskingAI backend REST/OpenAI-compatible APIs, object lifecycle, assistant generation, retrieval objects, auth, files, and backend service troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

backend-api

Use this sub-skill when the task is to work with TaskingAI's backend API/web service semantics: REST objects, lifecycle order, assistant/chat/message generation, retrieval collections/records/chunks, models, actions, bundle instances as backend tool references, OpenAI-compatible endpoints, authentication, file/image uploads, backend dependencies, or backend-native test prerequisites.

Load this first

1. For route prefixes, auth mode, object lifecycle, request shapes, generation order, retrieval order, and OpenAI-compatible mappings, read API and object model.
2. Before proposing or interpreting backend tests, read native testing for Python-version constraints, DB/Redis/service prerequisites, and safe skip criteria.
3. When a backend service, import, generation, retrieval, auth, file, or storage symptom appears, use troubleshooting.

Source-backed facts to preserve

• Backend package version evidence is v0.3.0.
• The backend builds a FastAPI app with an APIRouter; API mode uses /v1, while web-console mode uses /api/v1.
• Verified backend imports require Python 3.10. Python 3.11 backend import fails because aioredis==2.0.1 defines a duplicate TimeoutError base class under Python 3.11.
• Verified model type values are chat_completion, text_embedding, rerank, and wildcard.
• Verified retrieval splitting includes TextSplitter with token and separator modes.

Quick routing

• Starting containers, selecting Docker/Compose topology, setting environment variables, ports, storage mode, and service URL wiring belong to ../deployment-configuration/.
• Provider-specific model schema catalogs, credentials, inference-provider behavior, and provider execution failures belong to ../inference-providers/.
• Plugin bundle catalog internals, plugin schemas, and plugin-service execution internals belong to ../plugin-bundles/.
• Backend-created action objects, bundle instances as backend tool references, assistant tool wiring, and tool execution from an assistant generation flow stay here; return to plugin/provider sub-skills only for the provider or bundle-specific payload details.

Operating workflow

1. Identify service purpose and auth. API mode expects API-key bearer auth and /v1 routes. Web mode expects admin bearer auth and /api/v1 routes. Do not mix route prefixes with the wrong auth mode.
2. Plan object order before calling generation. For assistant + retrieval + tools, create or select required models first, then retrieval collections/records/chunks, actions or bundle instances, assistant, chat, user message, and finally generation. The exact order and constraints are in API and object model.
3. Validate IDs and model capabilities. Backend route validation uses path IDs, object parents, model types, and model properties. Chat models must be chat_completion; retrieval collection models must be text_embedding; rerank is optional for query reranking; function-call tools require a chat model that supports function calling.
4. Treat generation as orchestration. Stateful generation loads chat memory, retrievals, tools, and model settings, then may run retrieval/tool function-call rounds before creating the assistant message.
5. Check backend dependencies early. DB/Redis/object storage/inference/plugin service availability affects imports, app startup, object writes, retrieval embedding, file/image uploads, and generation. Use native testing and troubleshooting to decide whether a failure is an app bug, missing service, wrong Python, or unavailable external dependency.

Hard cases this sub-skill covers

• Mapping a request like "assistant with RAG over one document and a tool call" into the required model → collection → record/chunk → action/bundle-instance → assistant → chat → user message → generation sequence, with the validation points that can fail at each step.
• Explaining why backend import or inspection under Python 3.11 fails and choosing Python 3.10 for backend inspection/development instead of debugging unrelated FastAPI or Pydantic code.