> ## Documentation Index > Fetch the complete documentation index at: https://docs.trymaitai.com/llms.txt > Use this file to discover all available pages before exploring further. # Help query > Answer a free-form question about building with Maitai in natural-language markdown. The information-only sibling of ``POST /search``: instead of a structured execution plan, returns an expert prose answer with working code examples (SDK integration, Developer API, CLI, or Portal) for agent IDEs (Cursor, Claude Code) to apply directly. Never takes action. ## OpenAPI ````yaml /openapi.yaml post /help openapi: 3.1.0 info: title: Maitai Platform API description: > The Maitai Platform API lets you programmatically manage every resource available in the Maitai Portal, applications, intents, agents, datasets, test sets, finetune runs, and more. ## Authentication All endpoints require a valid Maitai API key passed via the `X-Maitai-Api-Key` header. You can create API keys in the [Portal](https://portal.trymaitai.com) under **Settings > API Keys**. version: 1.0.0 contact: name: Maitai Support email: support@trymaitai.com url: https://trymaitai.ai servers: - url: https://api.trymaitai.ai/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Applications description: >- Manage applications and their configuration, intents, sessions, workflow runs, and models. - name: Analytics description: Read request volume and fault-rate analytics. - name: Intents description: Manage intents (application actions) nested under applications. - name: Intent Groups description: >- Cross-application intent grouping and access to related resources like sentinels, models, test sets, and datasets. - name: Agents description: >- Manage agents, actions, sub-agents, versions, releases, sessions, routing rules, and form fields. - name: Compositions description: Manage dataset compositions used for finetuning. - name: Sentinels description: >- Manage sentinels, evaluation watchers that monitor model output quality at the intent group level. - name: Monitors description: >- Manage reusable production monitors and their target attachments. Surface area summary (everything is scoped to the caller's company_id): * Core CRUD on monitors and their target attachments (intent / workflow / agent). * Lifecycle helpers (activate / pause monitor; enable / disable target). * Versioning + named releases (publish a snapshot, manage release pointers). * Activity time series + metrics rollups (charts, "is X healthy?" calls). * Run history (paginated `monitor_run` browsing + reverse lookup by source). * Live preview (run a monitor against an ad-hoc payload without persisting). * Discovery (find monitors attached to a given target). * Sample fetch (peek at the most recent production payload for a target). - name: Sessions description: >- View and manage classic (non-agent) chat sessions, timelines, and feedback. - name: Requests description: View and correct individual request/response pairs from chat completions. - name: Datasets description: Manage curated request sets used for model training (finetune datasets). - name: Evaluation Criteria description: Manage reusable evaluation criteria for test runs. - name: Unified Test Sets description: >- Unified Test Sets. Consumer-agnostic test-set family, the same set can drive MODEL, WORKFLOW, and AGENT runs. Sits alongside the legacy `test_sets.py` blueprint (mounted at `/test-sets`) for a graceful deprecation window; portal/SDK callers migrate here without breaking existing integrations. Sets are curated collections of `(canonical_input, canonical_expected_output)` pairs. Items can be hand-authored (MANUAL) or imported from a production `chat_completion_request`, `workflow_run`, or agent task; imports are idempotent at the DB level via partial unique indexes. When scoring a run, an optional per-item `expected_output` override (`test_set_item_response_sub`) shadows the item's baseline, that's how the portal supports "correct the answer, re-score" without mutating the imported ground truth. - name: Unified Test Runs description: >- Unified Test Runs. Execute a unified `test_set` against a MODEL / WORKFLOW / AGENT consumer and score the result. Sits alongside the legacy `test_runs.py` blueprint (mounted at `/test-runs`) for a graceful deprecation window; the legacy blueprint keeps serving the per-family run endpoints, portal/SDK callers migrate here. Lifecycle (state machine on `unified_test_run.status`): CREATED -> RUNNING -> COMPLETED * ``POST /`` -> CREATED (validates consumer_config, derives consumer_id, no items yet) * ``POST /{id}/prepare`` -> RUNNING (walks the set, adapts inputs, inserts per-item run rows) * ``POST /{id}/execute`` -> **non-blocking**. Schedules the conductor (in-proc asyncio task in dev, K8s Job in prod) and returns the run in RUNNING. Actual per-item work happens off-thread; callers poll ``/{id}/progress`` for completion. * ``GET /{id}/progress`` -> aggregate counts + duration percentiles. Portal polls this while a run is in flight. * ``POST /{id}/score`` -> unchanged status; populates matched / diff_result per item and returns a summary. Idempotent; safe to rerun after adding a response-sub override on an item. * ``POST /{id}/reset-failed`` -> COMPLETED -> RUNNING for reruns of just the FAILED items (S6). Skipped if the run has zero failures. * ``DELETE /{id}`` -> hard-delete run + items (S7). Plus a pure read path (``POST /preview-adapted-input``) that runs the input adapter for a single item against hypothetical run parameters, the portal wizard uses this to render "here's your adapted input" without paying for a real run. - name: Workflows description: >- Manage workflows, workflow versions/releases, artifacts, runs, and execution. - name: Finetune Runs description: Create, monitor, and cancel model finetuning jobs. - name: Evaluations description: >- Run batch evaluations against sentinels and view per-request scoring results. - name: Models description: View and manage available base and finetuned models. - name: Reports description: Read fault and fallback reports. - name: Tags description: Manage request tagging rules and tag runs. - name: Search description: Natural-language search over the Maitai API + CLI surface. - name: Help description: Natural-language implementation help for the Maitai platform. paths: /help: post: tags: - Help summary: Help query description: >- Answer a free-form question about building with Maitai in natural-language markdown. The information-only sibling of ``POST /search``: instead of a structured execution plan, returns an expert prose answer with working code examples (SDK integration, Developer API, CLI, or Portal) for agent IDEs (Cursor, Claude Code) to apply directly. Never takes action. operationId: helpQuery requestBody: required: true content: application/json: schema: type: object properties: query: type: string description: >- Free-form natural-language question (e.g. 'how do I swap my OpenAI client for the Maitai client?'). required: - query example: query: >- how do I swap out my OpenAI client for the Maitai client and use the same model? responses: '200': description: Help query. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' example: data: answer: >- Maitai's Python SDK is an OpenAI drop-in: you swap the client constructor and keep the rest of your code. **Before:** ```python from openai import OpenAI client = OpenAI(api_key="sk-...") ``` **After:** ```python import maitai client = maitai.Maitai(api_key="mt-...") ``` Your `client.chat.completions.create(model=..., messages=...)` calls work unchanged, pass the same `model` string and Maitai proxies it to the same provider while adding observability and sentinels. elapsed_seconds: 42.3 components: schemas: SuccessResponse: type: object properties: data: {} securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Maitai-Api-Key description: Your Maitai API key from the Portal. ````