# Mana API Documentation Do deep research or build programmatic workflows with Mana's API. The exploratory agent lets you create agent conversations, stream live events, answer follow-up questions, and retrieve generated artifacts from your own systems. The pipeline-builder agent lets you build data pipelines, store persistent artifacts/tables, and create dashboards. The API reference is rendered at [`/docs/api`](/docs/api) from the OpenAPI document in `api-reference/openapi.json`. ## Base URL ```text https://backend-alpha.mana.ai ``` ## Authentication Use an API key from **Settings -> API** in the Mana app. Send it on authenticated public API requests with the `X-API-Key` header, or as `Authorization: Bearer mana_xxx`. ```http X-API-Key: mana_xxx ``` API keys inherit the user and organization permissions of the account that created them. Keep keys secret, rotate them after suspected exposure, and revoke unused keys from the Mana app. `GET /api/v1/health` is unauthenticated and should be called without auth headers. ## Common Workflow 1. Create a conversation with `POST /api/v1/conversations`. 2. Track it with either `GET /api/v1/conversations/{conversation_id}` polling or `GET /api/v1/conversations/{conversation_id}/stream` server-sent events. 3. Retrieve generated files with `GET /api/v1/conversations/{conversation_id}/artifacts`. 4. Download each artifact with `GET /api/v1/artifacts/{artifact_id}/download`. 5. Send a follow-up with `POST /api/v1/conversations` and `parentConversationId`. URLs that the API returns for API calls, such as `streamUrl` and `downloadUrl`, point at the API base URL. URLs such as `conversationUrl` and `pipelineUrl` open the Mana app. ## Limits Creating conversations and pipelines, and running whole pipelines, share a limit of 60 requests per minute per user. Above the limit, the API returns `429`. See the [Quickstart](/docs/quickstart) for complete Python examples. ## Quickstart Create an API key in the Mana app from **Settings -> API**, then store it in your shell: ```bash export MANA_API_KEY="mana_xxx" ``` The examples below use Python and `requests`. ## Health Check Call health without auth headers: ```python import requests BASE_URL = "https://backend-alpha.mana.ai" response = requests.get(f"{BASE_URL}/api/v1/health", timeout=30) response.raise_for_status() print(response.json()) ``` ## Choose an Agent `POST /api/v1/conversations` takes an optional `agentType`: - Leave it out, or send `jethro`, to let Mana route the request as the Mana app does. Mana answers it directly or hands it to a specialist agent, such as Pipeline Builder when you ask for a Pipeline. The specialist runs in a conversation of its own. - Send `exploratory` for a research answer from the Exploratory agent. - Send `pipeline-builder` to build or change a Pipeline with Pipeline Builder directly. Jethro picks the agent and model for each turn. If you send `model`, `reasoning` or `responseSchema` without naming `exploratory` or `pipeline-builder`, the request fails with 422. The examples below name `exploratory`. ## Poll Status and Download Artifacts ```python import os import time from pathlib import Path import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ.get("MANA_API_KEY", "mana_xxx") HEADERS = {"X-API-Key": API_KEY} # 1) Launch an exploratory agent run. create_response = requests.post( f"{BASE_URL}/api/v1/conversations", headers=HEADERS, json={ "prompt": "what is the stock price of tsla", "agentType": "exploratory", }, timeout=30, ) create_response.raise_for_status() conversation_id = create_response.json()["conversationId"] print("conversation:", conversation_id) # 2) Poll status until terminal. Polling reports a stopped run as "canceled". terminal_statuses = {"completed", "failed", "canceled"} while True: status_response = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}", headers=HEADERS, timeout=30, ) status_response.raise_for_status() status = status_response.json()["status"] print("status:", status) if status in terminal_statuses: break time.sleep(2) if status != "completed": raise RuntimeError(f"conversation ended with status={status}") # 3) Fetch artifact metadata. artifacts_response = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}/artifacts", headers=HEADERS, timeout=30, ) artifacts_response.raise_for_status() artifacts = artifacts_response.json() # 4) Download every artifact. output_dir = Path("downloads") output_dir.mkdir(exist_ok=True) for artifact in artifacts: artifact_id = artifact["id"] download_response = requests.get( f"{BASE_URL}/api/v1/artifacts/{artifact_id}/download", headers=HEADERS, allow_redirects=True, timeout=120, ) download_response.raise_for_status() filename = artifact.get("filePath") or f"{artifact_id}.bin" target_path = output_dir / filename.split("/")[-1] target_path.write_bytes(download_response.content) print("downloaded:", target_path) ``` Artifact downloads return `200` with the original file bytes, the stored content type, and an attachment filename. A single `Range: bytes=0-3` request returns `206` with `Content-Range` and those four bytes. Unsatisfiable ranges return `416`; multi-range requests return the full file with `200`. ## Stream Events with SSE Use the stream endpoint when you want live conversation updates instead of polling. ```python import json import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ.get("MANA_API_KEY", "mana_xxx") HEADERS = { "X-API-Key": API_KEY, "Accept": "text/event-stream", } # 1) Start run. create_response = requests.post( f"{BASE_URL}/api/v1/conversations", headers={"X-API-Key": API_KEY}, json={ "prompt": "what is the stock price of tsla", "agentType": "exploratory", }, timeout=30, ) create_response.raise_for_status() conversation_id = create_response.json()["conversationId"] # 2) Stream events with SSE. with requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}/stream", headers=HEADERS, stream=True, timeout=600, ) as response: response.raise_for_status() event_name = None live = False terminal_statuses = {"completed", "failed", "cancelled"} for line in response.iter_lines(decode_unicode=True): if not line: event_name = None continue if line.startswith("event: "): event_name = line[len("event: ") :] continue if line.startswith("data: "): payload = json.loads(line[len("data: ") :]) print(event_name, payload) if event_name == "stream_phase" and payload.get("phase") == "live": live = True elif ( live and event_name == "conversation_status" and payload.get("status") in terminal_statuses ): # A late copy of an earlier turn's status can arrive after # stream_phase, so confirm with the status endpoint first. current = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}", headers={"X-API-Key": API_KEY}, timeout=30, ).json()["status"] if current in {"completed", "failed", "canceled"}: break ``` The stream sends a `connection` event, replays the conversation's history, sends `stream_phase` with `phase: "live"`, and then sends live events. Each event name is a message type, such as `thinking`, `step`, `report`, `artifact_generated` or `conversation_status`. Stream payloads use snake_case keys, and the stream spells a stopped run `cancelled`. Replayed history can hold terminal statuses of earlier turns, and a late copy of one can arrive after `stream_phase`. Treat a terminal `conversation_status` as a signal to check `GET /api/v1/conversations/{conversation_id}`, as the loop above does, rather than as the end by itself. If the turn ended before you connected, its terminal status is in the replay and the stream closes on its own after a few idle seconds; the status endpoint then gives the result. ## Read the Answer The final answer is a `report` message. Read it from the conversation's messages: ```python messages = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}/messages", headers=HEADERS, timeout=30, ).json() reports = [m["content"] for m in messages if m["messageType"] == "report"] print(reports[-1]) ``` To get structured data instead of prose, pass a JSON Schema as `responseSchema` when you create an `exploratory` conversation, then read `GET /api/v1/conversations/{conversation_id}/structured-output`. A follow-up in a Pipeline Builder conversation cannot use `responseSchema`: those conversations run durably, and durable runs do not support it. ## Answer a Question Exploratory and Pipeline Builder runs started through the API do not stop to ask questions: they make reasonable assumptions and continue. Only Plan Mode runs ask, and the public API cannot start Plan Mode yet. When a run does wait for an answer, the status response has a `pendingQuestion` with a `form_id` and a list of `questions`; each has `question` text and optional `options`. Answer with `POST /api/v1/conversations/{conversation_id}/respond`: ```python status_payload = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}", headers=HEADERS, timeout=30, ).json() pending = status_payload["pendingQuestion"] answer_response = requests.post( f"{BASE_URL}/api/v1/conversations/{conversation_id}/respond", headers=HEADERS, json={ "formId": pending["form_id"], "answers": [ {"questionIndex": 0, "selectedOptions": ["Yes"]}, {"questionIndex": 1, "textAnswer": "Use the last 5 years."}, ], }, timeout=30, ) answer_response.raise_for_status() ``` ## Send a Follow-Up To add a message to an existing conversation, pass `parentConversationId`. The API returns the same `conversationId`, and the agent keeps the earlier context. Leave out `agentType` to keep the conversation's current agent. ```python follow_up_response = requests.post( f"{BASE_URL}/api/v1/conversations", headers=HEADERS, json={ "prompt": "summarize the result in one sentence", "parentConversationId": conversation_id, }, timeout=30, ) follow_up_response.raise_for_status() assert follow_up_response.json()["conversationId"] == conversation_id ``` A conversation runs one turn at a time. A follow-up sent while a turn is still running returns `409`; wait for a terminal status, or stop the turn with `POST /api/v1/conversations/{conversation_id}/cancel`. Right after a follow-up, the status reads `pending` until the new turn starts. ## Limits `POST /api/v1/conversations`, `POST /api/v1/pipelines` and `POST /api/v1/pipelines/{pipeline_id}/runs` share a limit of 60 requests per minute per user. Above it they return `429`. ## Authentication Guide Mana public API requests authenticate with API keys created in the Mana web app. ## API Key Authentication Use API keys for normal public API calls, such as creating conversations, polling status, streaming events, and downloading artifacts. ### Create a Key 1. Open the Mana app. 2. Go to **Settings -> API**. 3. Create a key and store the raw value securely. Mana only shows the raw key once. ### Send the Key Include the key in the `X-API-Key` header. The examples below read it from the `MANA_API_KEY` environment variable: ```bash curl https://backend-alpha.mana.ai/api/v1/conversations \ -H "X-API-Key: $MANA_API_KEY" ``` If your client can only send an `Authorization` header, send the key as a bearer token instead. Mana treats a bearer token that starts with `mana_` as an API key: ```bash curl https://backend-alpha.mana.ai/api/v1/conversations \ -H "Authorization: Bearer $MANA_API_KEY" ``` A missing, revoked or expired key returns `401`. ### Permissions API keys are tied to the user and organization that created them. Requests made with a key can only access data and workflows available to that account context. ## API Key Management Create, list, and revoke API keys from **Settings -> API** in the Mana web app. API keys cannot be used to manage API keys: the `/api/v1/api-keys` endpoints accept only a signed-in web session and return `403` for an API key, so a leaked key cannot create or revoke other keys. ## Unauthenticated Endpoints `GET /api/v1/health` is unauthenticated and should be called without `Authorization` or `X-API-Key` headers. ## Rotation Revoke stale or exposed keys from **Settings -> API**, then create a replacement key for your integration. ## Exploratory Guide Exploratory is Mana's research agent for ad-hoc questions and analyses. ## What You Can Do - Ask financial research questions in plain English - Pull data from SEC filings, prices, news, earnings transcripts, company metadata, and the web - Get charts, tables, and reports as downloadable artifacts - Run multi-step research that the agent plans and tracks itself - Upload documents and ask questions against them - Ask follow-ups in the same conversation ## Start a Conversation Open the Mana app and use the chat input on the home page, or go directly to `/chat/new`. Type your question and send it. Follow-ups continue in the same thread, so the agent can use the context from earlier messages. ## Use via the API Create a conversation with `POST /api/v1/conversations` and set `agentType` to `exploratory`: ```json { "prompt": "Compare Apple and Microsoft stock performance over the past 5 years.", "agentType": "exploratory" } ``` Useful request fields: - `artifactIds`: files uploaded first with `POST /api/v1/artifacts/upload`, for the agent to read. - `responseSchema`: a JSON Schema. Read the extracted result from `GET /api/v1/conversations/{conversation_id}/structured-output`. - `model` and `reasoning`: the model and reasoning effort for the run. `GET /api/v1/models` lists the models you can use, each with the `reasoning` values it accepts. Omit `model` to use the agent's own default. If your account is in a program with a set model, every run uses it: `programModelId` names it and it is the only model listed. - `title` and `projectId`: the conversation's title and the project it is filed in. `GET /api/v1/projects` lists your projects. - `parentConversationId`: send a follow-up in an existing conversation. List your conversations with `GET /api/v1/conversations`. It filters by the `status`, `pipeline_id` and `since` query parameters, and pages with `limit` and `cursor` (pass the returned `nextCursor`). Stop a running turn with `POST /api/v1/conversations/{conversation_id}/cancel`. That stops only the conversation's own turn; `POST /api/v1/conversations/{conversation_id}/stop-work` also stops the agents it delegated to. Rename a conversation with `PATCH /api/v1/conversations/{conversation_id}` and a `title`. `POST .../archive` hides it from your conversation list and stops what it still has running; `POST .../unarchive` restores it. Archive and stop-work answer `409` while a turn you just sent is still starting; once its status is `running`, they stop it. See the [Quickstart](/docs/quickstart) for full examples covering polling, streaming, questions, and follow-ups. ## Example Questions - "Compare Apple and Microsoft stock performance over the past 5 years." - "Find recent 8-K filings mentioning 'restructuring' from large-cap companies." - "Summarize the latest earnings call for NVDA and pull out the forward-looking guidance." ## Artifacts Charts, tables, and files generated during a run are saved as artifacts. You can view artifacts inline or download them. Via the API, list them with `GET /api/v1/conversations/{conversation_id}/artifacts` and download each with `GET /api/v1/artifacts/{artifact_id}/download`. ## When to Use Exploratory vs. a Pipeline Exploratory is best for one-off questions and research threads. If you want the same analysis to run on a schedule or react to new data, build a Pipeline. ## Pipelines Guide Pipelines are recurring workflows that run automatically. Each pipeline pairs a trigger, which decides what makes it run, with a workflow, which defines what runs. ## What Pipelines Offer ### Orchestrate data tables Combine data from sources like SEC filings, news, prices, and company metadata. Filter, join, and add LLM-generated classification columns, then output rows into persistent tables called LiveArtifacts that accumulate over time. ### Build live dashboards Visualize a pipeline's accumulated output as charts/tables on a dashboard so trends are visible at a glance. ### Monitor websites Describe in plain English what to watch, such as FDA press releases or a competitor's pricing page, and have a workflow run when new matching content appears. ## Triggers - **Data** - fires when new rows match your filters in a source table - **Time** - runs on a schedule, such as every weekday at 9am - **Web** - fires when monitored sites publish new matching content - **Manual** - only runs when you start it ## Example Pipelines - "Daily 9am summary of overnight earnings reports for my watchlist" (Time trigger) - "Score every new 8-K filing from S&P 500 companies for materiality" (Data trigger -> LiveArtifact -> dashboard) - "Notify me when the FDA announces a new drug approval" (Web trigger) ## Use via the API Pipelines are created and edited through the Pipeline Builder agent. Create a conversation with `POST /api/v1/conversations` and set `agentType` to `pipeline-builder`: ```json { "prompt": "Build a pipeline that runs every weekday at 9am and summarizes overnight earnings reports for AAPL, MSFT, and NVDA.", "agentType": "pipeline-builder" } ``` To modify an existing pipeline, including its dashboards, workflows, or LiveArtifacts, start a new `pipeline-builder` conversation with `pipelineId` set to that pipeline and describe the change you want. The agent has the tools to edit the pipeline's components in place. You can also read and run pipelines directly: - `GET /api/v1/pipelines` lists the pipelines you created. Read one with `GET /api/v1/pipelines/{pipeline_id}`. Rename it with `PATCH`, and archive or restore it with `POST .../archive` and `POST .../unarchive`. - `POST /api/v1/pipelines/{pipeline_id}/runs` runs the whole pipeline once, from the entry points of its active version that have work, and returns the started `workflowRunIds` (none when its sources have no new event). `POST /api/v1/pipelines/{pipeline_id}/triggers/pause` and `.../triggers/resume` pause and resume its automatic triggers, as Pause and Resume do in the app. - `GET /api/v1/pipelines/{pipeline_id}/workflows` lists the workflows in the pipeline's active version. `POST /api/v1/workflows/{workflow_id}/runs` starts a run; pass `entryPoint` to start from a specific trigger. Follow the run with `GET /api/v1/workflow-runs/{workflow_run_id}`. - `GET /api/v1/pipelines/{pipeline_id}/live-artifacts` lists the pipeline's tables. Read rows with `GET /api/v1/live-artifacts/{live_artifact_id}/data` (`limit` up to 10,000, paged with `offset`). `GET /api/v1/live-artifacts/{live_artifact_id}/stream` sends Server-Sent Events when the table changes: each `live_artifact` event carries the table's metadata, such as `updated_at` and `row_count`, not its rows, so read new rows from `/data` when it arrives. - `GET /api/v1/pipelines/{pipeline_id}/artifacts` and `GET /api/v1/pipelines/{pipeline_id}/dashboards` list its reports, files, and dashboards. --- ## Endpoints ### List API Keys `GET /api/v1/api-keys` List all API keys from the Mana web app context (metadata only). This endpoint is intended for the web app's API key settings UI; API key authentication is rejected with 403. **Authentication:** Mana web app session token, used only by the API-key management endpoints. Other endpoints also accept an API key as `Authorization: Bearer mana_...`. **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | keyPrefix | string | | | scopes | string[] | | | isActive | boolean | | | lastUsedAt | string (ISO 8601 datetime) \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | expiresAt | string (ISO 8601 datetime) \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "items": { "$ref": "#/components/schemas/ApiKeyDTO" }, "type": "array", "title": "Response List Api Keys" } ``` Definitions: [ApiKeyDTO](#schema-apikeydto). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" JWT_TOKEN = os.environ["MANA_SESSION_TOKEN"] HEADERS = {"Authorization": f"Bearer {JWT_TOKEN}"} response = requests.get( f"{BASE_URL}/api/v1/api-keys", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Create API Key `POST /api/v1/api-keys` Create a new API key from the Mana web app context. Returns the raw key exactly once. The caller must store it securely — it cannot be retrieved again (only the hash is persisted). This endpoint is intended for the web app's API key settings UI; API key authentication is rejected with 403. **Authentication:** Mana web app session token, used only by the API-key management endpoints. Other endpoints also accept an API key as `Authorization: Bearer mana_...`. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | body | name | string | Yes | Human-readable label for this key (e.g. 'Clay Integration') | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | key | string | The raw API key — store it securely, it cannot be retrieved again | | keyPrefix | string | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | expiresAt | string (ISO 8601 datetime) \| null | | **Request schema (application/json):** ```json { "$ref": "#/components/schemas/CreateApiKeyRequest" } ``` Definitions: [CreateApiKeyRequest](#schema-createapikeyrequest). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/CreateApiKeyResponse" } ``` Definitions: [CreateApiKeyResponse](#schema-createapikeyresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" JWT_TOKEN = os.environ["MANA_SESSION_TOKEN"] HEADERS = {"Authorization": f"Bearer {JWT_TOKEN}"} response = requests.post( f"{BASE_URL}/api/v1/api-keys", headers=HEADERS, json={ "name": 'My API Key', }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Revoke API Key `DELETE /api/v1/api-keys/{key_id}` Revoke an API key from the Mana web app context (soft-delete). Verifies ownership. This endpoint is intended for the web app's API key settings UI; API key authentication is rejected with 403. **Authentication:** Mana web app session token, used only by the API-key management endpoints. Other endpoints also accept an API key as `Authorization: Bearer mana_...`. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | key_id | string | Yes | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "object", "additionalProperties": { "type": "boolean" }, "title": "Response Revoke Api Key" } ``` - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" JWT_TOKEN = os.environ["MANA_SESSION_TOKEN"] HEADERS = {"Authorization": f"Bearer {JWT_TOKEN}"} # Set these environment variables to IDs returned by the corresponding create/list endpoints. key_id = os.environ["MANA_KEY_ID"] response = requests.delete( f"{BASE_URL}/api/v1/api-keys/{key_id}", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Conversations `GET /api/v1/conversations` List conversations for the authenticated user. Supports filtering by status and pagination via a cursor-backed offset. Results are ordered by most recently updated first. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | query | status | string \| null | No | Filter by status: pending, running, completed, canceled | | query | pipeline_id | string \| null | No | Filter by pipeline ID | | query | since | string (ISO 8601 datetime) \| null | No | Only include conversations updated at or after this time | | query | limit | integer | No | Max results to return Default: `50`. minimum: `1`. maximum: `100`. | | query | cursor | string \| null | No | Pagination cursor returned by the previous page | **Response fields:** | Name | Type | Description | | --- | --- | --- | | items | object[] | Definitions: [ApiConversationListItem](#schema-apiconversationlistitem). | | items[].id | string | | | items[].title | string \| null | | | items[].status | string \| null | | | items[].projectId | string \| null | | | items[].createdAt | string (ISO 8601 datetime) \| null | | | items[].updatedAt | string (ISO 8601 datetime) \| null | | | items[].pipelineId | string \| null | | | items[].parentConversationId | string \| null | | | items[].conversationUrl | string \| null | | | items[].pipelineUrl | string \| null | | | nextCursor | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiConversationListPage" } ``` Definitions: [ApiConversationListPage](#schema-apiconversationlistpage). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} response = requests.get( f"{BASE_URL}/api/v1/conversations", headers=HEADERS, params={ "limit": 50, }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Create Conversation `POST /api/v1/conversations` Create and launch a new conversation, or send a follow-up to an existing one. Returns immediately with the conversation ID and status `pending`. Track progress with the stream or the status endpoint. Pass `parentConversationId` to add a turn to an existing conversation. Requests count against a limit of 60 per minute per user; above it the endpoint answers 429. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | body | prompt | string | Yes | The user's prompt to start the conversation | | body | agentType | string \| null | No | Agent type for the run. Public JSON request bodies use the camelCase alias `agentType`. Supported public values are `jethro` (the default), `exploratory` and `pipeline-builder`. Jethro answers or hands the work to a specialist, such as Pipeline Builder for a Pipeline, as the Mana app does; it takes no `model`, `reasoning` or `responseSchema`. A deployment that does not run Jethro uses `exploratory` as the default and refuses `jethro` with 422. A follow-up that omits it keeps the conversation's agent. | | body | title | string \| null | No | Optional conversation title | | body | artifactIds | string[] | No | Optional artifact IDs to attach | | body | responseSchema | object \| null | No | Optional JSON Schema used to extract structured output from the final report. Exploratory only: a new conversation must name `agentType` `exploratory`, because the default, Jethro, refuses it with 422. A follow-up that sends it runs as Exploratory. | | body | parentConversationId | string \| null | No | ID of an existing conversation to continue. Public JSON request bodies use the camelCase alias `parentConversationId`; follow-up requests append to and return the same conversation. | | body | pipelineId | string \| null | No | Optional pipeline ID to scope the conversation to | | body | projectId | string \| null | No | Optional project ID to scope the conversation to | | body | model | string \| null | No | Optional model to use for the conversation | | body | reasoning | string (`none`, `low`, `medium`, `high`, `xhigh`, `max`) \| null | No | Optional reasoning effort level Values: `none`, `low`, `medium`, `high`, `xhigh`, `max`. | **Response fields:** | Name | Type | Description | | --- | --- | --- | | conversationId | string | | | status | string | Always `pending`: the run has been accepted, not started Default: `pending`. | | pipelineId | string \| null | | | projectId | string \| null | | | conversationUrl | string \| null | | | pipelineUrl | string \| null | | | streamUrl | string \| null | | **Request schema (application/json):** ```json { "$ref": "#/components/schemas/ApiCreateConversationRequest" } ``` Definitions: [ApiCreateConversationRequest](#schema-apicreateconversationrequest). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiCreateConversationResponse" } ``` Definitions: [ApiCreateConversationResponse](#schema-apicreateconversationresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **409**: Conflict: a follow-up was sent while the conversation's turn is still running. - **429**: Rate limit exceeded: retry after reducing request frequency. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} response = requests.post( f"{BASE_URL}/api/v1/conversations", headers=HEADERS, json={ "prompt": 'what is the stock price of tsla', "agentType": 'jethro', }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Public Pipeline Conversations `GET /api/v1/pipelines/{pipeline_id}/conversations` List top-level conversations in a pipeline. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | title | string \| null | | | status | string \| null | | | projectId | string \| null | | | createdAt | string (ISO 8601 datetime) \| null | | | updatedAt | string (ISO 8601 datetime) \| null | | | pipelineId | string \| null | | | parentConversationId | string \| null | | | conversationUrl | string \| null | | | pipelineUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiConversationListItem" }, "title": "Response List Public Pipeline Conversations" } ``` Definitions: [ApiConversationListItem](#schema-apiconversationlistitem). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.get( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/conversations", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Stream Conversation `GET /api/v1/conversations/{conversation_id}/stream` Stream a conversation's messages as Server-Sent Events (`text/event-stream`). The stream sends a `connection` event, then replays the conversation's history, then sends `stream_phase` with `phase: "live"` and continues with live messages. Each event name is the message type (`thinking`, `step`, `report`, `artifact_generated`, `conversation_status`, ...). Replayed history can include terminal `conversation_status` events (`completed`, `failed`, `cancelled`) of earlier turns, and a late copy of one can follow `stream_phase`, so confirm a terminal status with the status endpoint before treating the turn as finished. Event payloads use snake_case keys. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json {} ``` - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}/stream", headers={**HEADERS, "Accept": "text/event-stream"}, stream=True, timeout=600, ) response.raise_for_status() for line in response.iter_lines(decode_unicode=True): print(line) ``` --- ### Respond To Question `POST /api/v1/conversations/{conversation_id}/respond` Answer a question, save it to history, and resume a suspended run. Late answers recover the original form from history, as on WebSocket. Pipeline-spec decisions use the spec-review route. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | | body | formId | string | Yes | The `formId` value from the question event | | body | answers | object[] | Yes | Answers to each question Definitions: [QuestionAnswerItem](#schema-questionansweritem). | **Request schema (application/json):** ```json { "$ref": "#/components/schemas/QuestionResponseRequest" } ``` Definitions: [QuestionResponseRequest](#schema-questionresponserequest). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "object", "additionalProperties": true, "title": "Response Respond To Question" } ``` - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.post( f"{BASE_URL}/api/v1/conversations/{conversation_id}/respond", headers=HEADERS, json={ "formId": 'formId', "answers": [{'questionIndex': 0, 'selectedOptions': ['selectedOption-value']}], }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Review Pipeline Spec `POST /api/v1/conversations/{conversation_id}/spec-review` Approve or comment on a presented spec through the admin-gated review service. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | | body | formId | string | Yes | minLength: `1`. maxLength: `200`. | | body | decision | string (`accept`, `feedback`) | Yes | Values: `accept`, `feedback`. | | body | feedback | string \| null | No | | **Request schema (application/json):** ```json { "$ref": "#/components/schemas/ApiSpecReviewRequest" } ``` Definitions: [ApiSpecReviewRequest](#schema-apispecreviewrequest). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "object", "additionalProperties": true, "title": "Response Review Pipeline Spec" } ``` - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.post( f"{BASE_URL}/api/v1/conversations/{conversation_id}/spec-review", headers=HEADERS, json={ "formId": 'formId', "decision": 'accept', }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Cancel Conversation `POST /api/v1/conversations/{conversation_id}/cancel` Cancel a running conversation. Uses the same cancellation service as the WebSocket handler so Temporal, local, Modal, and owned Pipeline-build work share one terminal boundary. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "object", "additionalProperties": true, "title": "Response Cancel Conversation" } ``` - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. - **409**: Conflict: the requested action conflicts with current resource state. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.post( f"{BASE_URL}/api/v1/conversations/{conversation_id}/cancel", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Conversation Status `GET /api/v1/conversations/{conversation_id}` Get current conversation status and metadata. For polling clients that can't use SSE. Also includes any pending question the agent is waiting on. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | conversationId | string | | | status | string | | | title | string \| null | | | pendingQuestion | object \| null | | | createdAt | string (ISO 8601 datetime) \| null | | | updatedAt | string (ISO 8601 datetime) \| null | | | pipelineId | string \| null | | | parentConversationId | string \| null | | | conversationUrl | string \| null | | | pipelineUrl | string \| null | | | streamUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiConversationStatusResponse" } ``` Definitions: [ApiConversationStatusResponse](#schema-apiconversationstatusresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Rename Conversation `PATCH /api/v1/conversations/{conversation_id}` Rename one of your conversations. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | | body | title | string | Yes | The conversation's new title minLength: `1`. maxLength: `500`. | **Response fields:** | Name | Type | Description | | --- | --- | --- | | conversationId | string | | | status | string | | | title | string \| null | | | pendingQuestion | object \| null | | | createdAt | string (ISO 8601 datetime) \| null | | | updatedAt | string (ISO 8601 datetime) \| null | | | pipelineId | string \| null | | | parentConversationId | string \| null | | | conversationUrl | string \| null | | | pipelineUrl | string \| null | | | streamUrl | string \| null | | **Request schema (application/json):** ```json { "$ref": "#/components/schemas/ApiUpdateConversationRequest" } ``` Definitions: [ApiUpdateConversationRequest](#schema-apiupdateconversationrequest). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiConversationStatusResponse" } ``` Definitions: [ApiConversationStatusResponse](#schema-apiconversationstatusresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.patch( f"{BASE_URL}/api/v1/conversations/{conversation_id}", headers=HEADERS, json={ "title": 'Quarterly research', }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Archive Conversation `POST /api/v1/conversations/{conversation_id}/archive` Archive one of your conversations, reversibly. Archiving stops what the conversation still has running, as in the app: its own turn, the agents it delegated to and the triggers of the Pipelines it owns. Chief of Staff threads cannot be archived (409). **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | conversationId | string | | | status | string | | | title | string \| null | | | pendingQuestion | object \| null | | | createdAt | string (ISO 8601 datetime) \| null | | | updatedAt | string (ISO 8601 datetime) \| null | | | pipelineId | string \| null | | | parentConversationId | string \| null | | | conversationUrl | string \| null | | | pipelineUrl | string \| null | | | streamUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiConversationStatusResponse" } ``` Definitions: [ApiConversationStatusResponse](#schema-apiconversationstatusresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. - **409**: Conflict: the requested action conflicts with current resource state. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.post( f"{BASE_URL}/api/v1/conversations/{conversation_id}/archive", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Unarchive Conversation `POST /api/v1/conversations/{conversation_id}/unarchive` Restore one of your archived conversations, as in the app. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | conversationId | string | | | status | string | | | title | string \| null | | | pendingQuestion | object \| null | | | createdAt | string (ISO 8601 datetime) \| null | | | updatedAt | string (ISO 8601 datetime) \| null | | | pipelineId | string \| null | | | parentConversationId | string \| null | | | conversationUrl | string \| null | | | pipelineUrl | string \| null | | | streamUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiConversationStatusResponse" } ``` Definitions: [ApiConversationStatusResponse](#schema-apiconversationstatusresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. - **409**: Conflict: the requested action conflicts with current resource state. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.post( f"{BASE_URL}/api/v1/conversations/{conversation_id}/unarchive", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Stop Conversation Work `POST /api/v1/conversations/{conversation_id}/stop-work` Stop everything one of your conversations still has running, including the agents it delegated to. `POST /conversations/{conversation_id}/cancel` stops only the conversation's own turn; delegated agents are separate conversations and keep running. This stops them too. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | stoppedConversationIds | string[] | The conversation and every agent it delegated to that was still running | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiConversationWorkStopResponse" } ``` Definitions: [ApiConversationWorkStopResponse](#schema-apiconversationworkstopresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. - **409**: Conflict: the requested action conflicts with current resource state. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.post( f"{BASE_URL}/api/v1/conversations/{conversation_id}/stop-work", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Conversation Structured Output `GET /api/v1/conversations/{conversation_id}/structured-output` Get structured output extracted from the run's final report. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | structuredOutput | any | | | structuredOutputError | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ConversationStructuredOutputResponse" } ``` Definitions: [ConversationStructuredOutputResponse](#schema-conversationstructuredoutputresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}/structured-output", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Sub Conversations `GET /api/v1/conversations/{conversation_id}/sub-conversations` List child conversations launched from a parent conversation. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | title | string \| null | | | status | string \| null | | | projectId | string \| null | | | createdAt | string (ISO 8601 datetime) \| null | | | updatedAt | string (ISO 8601 datetime) \| null | | | pipelineId | string \| null | | | parentConversationId | string \| null | | | conversationUrl | string \| null | | | pipelineUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiConversationListItem" }, "title": "Response List Sub Conversations" } ``` Definitions: [ApiConversationListItem](#schema-apiconversationlistitem). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}/sub-conversations", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Conversation Messages `GET /api/v1/conversations/{conversation_id}/messages` Fetch conversation history (protocol messages) for a conversation. Returns all protocol message types in sequence order, with an extracted top-level content summary for UI display. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | sequence | integer | | | messageType | string | | | content | string \| null | | | messageData | object | | | createdAt | string (ISO 8601 datetime) \| null | | | conversationUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiConversationHistoryItem" }, "title": "Response Get Conversation Messages" } ``` Definitions: [ApiConversationHistoryItem](#schema-apiconversationhistoryitem). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}/messages", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Conversation Artifacts `GET /api/v1/conversations/{conversation_id}/artifacts` Fetch all artifacts produced during a conversation. Returns artifact metadata (tables, charts, reports, etc.) generated by the agent. Internal storage details are omitted. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | conversation_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | title | string | | | description | string \| null | | | type | string (`structured_data`, `text`, `json`, `csv`, `report`, `chart`, `table`, `list`, `data`, `link`, `document`, `image`, `code`, `signal`, `other`) | Values: `structured_data`, `text`, `json`, `csv`, `report`, `chart`, `table`, `list`, `data`, `link`, `document`, `image`, `code`, `signal`, `other`. | | category | string (`terminal`, `intermediate`, `report`) | Values: `terminal`, `intermediate`, `report`. | | status | string (`pending`, `generated`, `validated`, `error`) | Values: `pending`, `generated`, `validated`, `error`. | | mimeType | string \| null | | | filePath | string \| null | | | sizeBytes | integer \| null | | | sourceType | string (`user_upload`, `agent`, `module`, `system`) \| null | Values: `user_upload`, `agent`, `module`, `system`. Definitions: [ArtifactSourceType](#schema-artifactsourcetype). | | pipelineId | string \| null | | | conversationId | string \| null | | | pipelineUrl | string \| null | | | conversationUrl | string \| null | | | downloadUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiArtifactDTO" }, "title": "Response Get Conversation Artifacts" } ``` Definitions: [ApiArtifactDTO](#schema-apiartifactdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. conversation_id = os.environ["MANA_CONVERSATION_ID"] response = requests.get( f"{BASE_URL}/api/v1/conversations/{conversation_id}/artifacts", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Pipelines `GET /api/v1/pipelines` List the Pipelines the authenticated user may run, most recently updated first. These are the Pipelines the user created and the Pipelines in Projects the user owns, leaving out sub-Pipelines, which run as part of their parent: the same list Mana's MCP `list_pipelines` tool gives. Read a sub-Pipeline with `GET /pipelines/{pipeline_id}`. Returns a flat array. `cursor` is the integer offset of the first item; pass the previous `cursor` plus `limit` for the next page. The response does not include a pagination wrapper or nextCursor field. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | query | archived | boolean | No | Include archived pipelines instead of active ones Default: `False`. | | query | limit | integer | No | Maximum number of array items to return Default: `50`. minimum: `1`. maximum: `100`. | | query | cursor | string \| null | No | Integer offset used as the starting slice position | **Response fields:** | Name | Type | Description | | --- | --- | --- | | itemStatus | object | One item's current state and the time of its latest usable result. | | ownerItemStatus | object | One item's current state and the time of its latest usable result. | | latestTriggerCheck | object \| null | Definitions: [PipelineTriggerCheckDTO](#schema-pipelinetriggercheckdto). | | tickerPages | object[] | Definitions: [PipelineTickerPageDTO](#schema-pipelinetickerpagedto). | | tickerPages[].pageId | string | | | tickerPages[].symbol | string | | | hasOpenBuild | boolean | True when the Pipeline has a nonterminal Builder build. Default: `False`. | | id | string | | | orgId | string | | | createdByUserId | string | | | name | string | | | description | string \| null | | | tags | string[] | Arbitrary string tags for categorization | | status | string (`active`, `archived`) | Values: `active`, `archived`. | | ownerConversationId | string \| null | | | triggerSchedules | object[] | Active-revision and paused trigger schedules. Next occurrences are calendar opportunities, not execution guarantees; conditional triggers check their condition at that time. Definitions: [PipelineTriggerScheduleDTO](#schema-pipelinetriggerscheduledto). | | triggerSchedules[].triggerId | string | | | triggerSchedules[].triggerLogicalId | string \| null | | | triggerSchedules[].webMode | string (`events`, `feed`, `page`) \| null | Values: `events`, `feed`, `page`. Definitions: [WebTriggerMode](#schema-webtriggermode). | | triggerSchedules[].sourceUrl | string \| null | | | triggerSchedules[].triggerKind | string (`time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`) | Values: `time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`. | | triggerSchedules[].summary | string | | | triggerSchedules[].state | string (`scheduled`, `conditional`, `event`, `paused`, `invalid`) | Values: `scheduled`, `conditional`, `event`, `paused`, `invalid`. | | triggerSchedules[].timezone | string \| null | | | triggerSchedules[].hasCondition | boolean | Default: `False`. | | triggerSchedules[].scheduleType | string (`cron`, `times`, `invalid`) \| null | Values: `cron`, `times`, `invalid`. | | triggerSchedules[].cronExpression | string \| null | | | triggerSchedules[].times | string[] | | | triggerSchedules[].issue | string \| null | | | triggerSchedules[].checkIntervalSeconds | integer \| null | | | triggerSchedules[].lastCheckedAt | string (ISO 8601 datetime) \| null | | | triggerSchedules[].lastCheckOutcome | string (`no_change`, `matched`, `failed`, `unknown`) \| null | Values: `no_change`, `matched`, `failed`, `unknown`. | | triggerSchedules[].nextOccurrenceAt | string (ISO 8601 datetime) \| null | Compute at serialization time so cached configurations do not freeze time. Cached DTOs reconstruct this property from the non-executable schedule fields. A condition check is an opportunity, never a promised execution. readOnly: `true`. | | componentPipelineIds | string[] | Component pipeline IDs recorded in pipeline metadata | | sourcePipelineId | string \| null | | | parentPipelineId | string \| null | | | isSubscribed | boolean | Default: `False`. | | lastPushedRevisionId | string \| null | | | lastPushedSourceRevisionId | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | workflowCount | integer | Number of workflows in the pipeline (org-scoped). Default: `0`. | | artifactCount | integer | Artifacts with this pipeline_id (org-scoped). Default: `0`. | | runCount | integer | Workflow runs under workflows in this pipeline (org-scoped). Default: `0`. | | lastRanAt | string (ISO 8601 datetime) \| null | Most recent workflow-run start time across this pipeline's workflows. | | lastRunId | string \| null | ID of the pipeline's most recent workflow run, or None if it never ran. | | lastRunStatus | string \| null | Status of the pipeline's most recent workflow run, or None if it never ran. | | isLive | boolean | True when the pipeline has any automatic trigger. Default: `False`. | | triggerKinds | string[] | Distinct non-manual trigger kinds driving this pipeline (e.g. ['time', 'data']). | | triggerSummary | string \| null | Short human-readable cadence label for the pipeline's automatic triggers (e.g. 'Scheduled at 09:30', 'Every 30 min, and Web monitor (hourly)'). None when not live. | | triggersPaused | boolean | True when the pipeline has automatic triggers that are configured but paused (their workflow is paused, or the trigger itself is paused, so they don't fire). Mutually exclusive with is_live; lets the UI show a distinct 'Paused' state instead of the pipeline silently dropping out of 'Live'. Default: `False`. | | pausedBy | string (`user`, `staff`, `agent`, `system`, `unknown`) \| null | Recorded pause actor kind while triggers_paused; unknown for legacy or mixed actors. Values: `user`, `staff`, `agent`, `system`, `unknown`. | | pausedAt | string (ISO 8601 datetime) \| null | When this pipeline pause was recorded, while triggers_paused. None for a pause with no user record (repair, first build, failure circuit). | | automaticFailureCircuits | object[] | Unresolved automatic-trigger systematic failure circuits for this pipeline. Definitions: [AutomaticTriggerFailureCircuitDTO](#schema-automatictriggerfailurecircuitdto). | | automaticFailureCircuits[].id | string | | | automaticFailureCircuits[].pipelineId | string | | | automaticFailureCircuits[].pipelineRevisionId | string | | | automaticFailureCircuits[].moduleId | string \| null | | | automaticFailureCircuits[].fingerprint | string | | | automaticFailureCircuits[].failureClass | string | | | automaticFailureCircuits[].consecutiveCount | integer | | | automaticFailureCircuits[].firstSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].lastSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].trippedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolvedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolutionReason | string (`connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`) \| null | Values: `connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`. Definitions: [AutomaticTriggerCircuitResolutionReason](#schema-automatictriggercircuitresolutionreason). | | automaticFailureCircuits[].representativeWorkflowRunId | string \| null | | | automaticFailureCircuits[].representativeModuleRunId | string \| null | | | automaticFailureCircuits[].state | string (`armed`, `open`, `resolved`) | Lifecycle of one automatic-trigger failure fingerprint sequence. Values: `armed`, `open`, `resolved`. | | automaticRepairAttempts | object[] | Typed automatic-repair lifecycle records for this Pipeline's contained failures. Definitions: [SystematicCodeRepairAttemptDTO](#schema-systematiccoderepairattemptdto). | | automaticRepairAttempts[].id | string | | | automaticRepairAttempts[].incidentId | string | | | automaticRepairAttempts[].generation | integer | | | automaticRepairAttempts[].route | string (`pipeline_builder`, `unsupported`) | Typed repair destination selected from executable ownership. Values: `pipeline_builder`, `unsupported`. | | automaticRepairAttempts[].state | string (`observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`) | Durable automatic-repair lifecycle. Values: `observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`. | | automaticRepairAttempts[].invocationHostPipelineId | string \| null | | | automaticRepairAttempts[].invocationHostWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceModuleRunId | string \| null | | | automaticRepairAttempts[].repairConversationId | string \| null | | | automaticRepairAttempts[].repairModuleRunId | string \| null | | | automaticRepairAttempts[].replacementParameterizedWorkflowId | string \| null | | | automaticRepairAttempts[].capabilityVersion | string \| null | | | automaticRepairAttempts[].terminalReasonCode | string \| null | | | automaticRepairAttempts[].ownerOverrideRequestedAt | string (ISO 8601 datetime) \| null | | | automaticRepairAttempts[].rearmReason | string (`new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`) \| null | Values: `new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`. Definitions: [SystematicCodeRepairRearmReason](#schema-systematiccoderepairrearmreason). | | automaticRepairAttempts[].validationResult | string (`passed`, `failed`) \| null | Values: `passed`, `failed`. Definitions: [SystematicCodeRepairValidationResult](#schema-systematiccoderepairvalidationresult). | | automaticRepairAttempts[].validationWorkflowRunIds | string[] | | | automaticRepairAttempts[].activatedOwnerVersionId | string \| null | | | hasAgent | boolean | True when the pipeline has at least one active/paused analyst (agent) module. Only populated by the list endpoint; defaults to False on single-pipeline fetches. Default: `False`. | | projectIds | string[] | Project memberships (many-to-many) for list surfaces. | | pipelineUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiPipelineDTO" }, "title": "Response List Pipelines" } ``` Definitions: [ApiPipelineDTO](#schema-apipipelinedto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} response = requests.get( f"{BASE_URL}/api/v1/pipelines", headers=HEADERS, params={ "limit": 50, }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Create Public Pipeline `POST /api/v1/pipelines` Create an empty pipeline. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | body | name | string | Yes | Pipeline name minLength: `1`. maxLength: `255`. | | body | description | string \| null | No | Optional pipeline description | | body | tags | string[] | No | Arbitrary string tags for categorization | | body | id | string \| null | No | Optional client-generated pipeline ID (must be a valid lowercase UUID v4) | **Response fields:** | Name | Type | Description | | --- | --- | --- | | itemStatus | object | One item's current state and the time of its latest usable result. | | ownerItemStatus | object | One item's current state and the time of its latest usable result. | | latestTriggerCheck | object \| null | Definitions: [PipelineTriggerCheckDTO](#schema-pipelinetriggercheckdto). | | tickerPages | object[] | Definitions: [PipelineTickerPageDTO](#schema-pipelinetickerpagedto). | | tickerPages[].pageId | string | | | tickerPages[].symbol | string | | | hasOpenBuild | boolean | True when the Pipeline has a nonterminal Builder build. Default: `False`. | | id | string | | | orgId | string | | | createdByUserId | string | | | name | string | | | description | string \| null | | | tags | string[] | Arbitrary string tags for categorization | | status | string (`active`, `archived`) | Values: `active`, `archived`. | | ownerConversationId | string \| null | | | triggerSchedules | object[] | Active-revision and paused trigger schedules. Next occurrences are calendar opportunities, not execution guarantees; conditional triggers check their condition at that time. Definitions: [PipelineTriggerScheduleDTO](#schema-pipelinetriggerscheduledto). | | triggerSchedules[].triggerId | string | | | triggerSchedules[].triggerLogicalId | string \| null | | | triggerSchedules[].webMode | string (`events`, `feed`, `page`) \| null | Values: `events`, `feed`, `page`. Definitions: [WebTriggerMode](#schema-webtriggermode). | | triggerSchedules[].sourceUrl | string \| null | | | triggerSchedules[].triggerKind | string (`time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`) | Values: `time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`. | | triggerSchedules[].summary | string | | | triggerSchedules[].state | string (`scheduled`, `conditional`, `event`, `paused`, `invalid`) | Values: `scheduled`, `conditional`, `event`, `paused`, `invalid`. | | triggerSchedules[].timezone | string \| null | | | triggerSchedules[].hasCondition | boolean | Default: `False`. | | triggerSchedules[].scheduleType | string (`cron`, `times`, `invalid`) \| null | Values: `cron`, `times`, `invalid`. | | triggerSchedules[].cronExpression | string \| null | | | triggerSchedules[].times | string[] | | | triggerSchedules[].issue | string \| null | | | triggerSchedules[].checkIntervalSeconds | integer \| null | | | triggerSchedules[].lastCheckedAt | string (ISO 8601 datetime) \| null | | | triggerSchedules[].lastCheckOutcome | string (`no_change`, `matched`, `failed`, `unknown`) \| null | Values: `no_change`, `matched`, `failed`, `unknown`. | | triggerSchedules[].nextOccurrenceAt | string (ISO 8601 datetime) \| null | Compute at serialization time so cached configurations do not freeze time. Cached DTOs reconstruct this property from the non-executable schedule fields. A condition check is an opportunity, never a promised execution. readOnly: `true`. | | componentPipelineIds | string[] | Component pipeline IDs recorded in pipeline metadata | | sourcePipelineId | string \| null | | | parentPipelineId | string \| null | | | isSubscribed | boolean | Default: `False`. | | lastPushedRevisionId | string \| null | | | lastPushedSourceRevisionId | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | workflowCount | integer | Number of workflows in the pipeline (org-scoped). Default: `0`. | | artifactCount | integer | Artifacts with this pipeline_id (org-scoped). Default: `0`. | | runCount | integer | Workflow runs under workflows in this pipeline (org-scoped). Default: `0`. | | lastRanAt | string (ISO 8601 datetime) \| null | Most recent workflow-run start time across this pipeline's workflows. | | lastRunId | string \| null | ID of the pipeline's most recent workflow run, or None if it never ran. | | lastRunStatus | string \| null | Status of the pipeline's most recent workflow run, or None if it never ran. | | isLive | boolean | True when the pipeline has any automatic trigger. Default: `False`. | | triggerKinds | string[] | Distinct non-manual trigger kinds driving this pipeline (e.g. ['time', 'data']). | | triggerSummary | string \| null | Short human-readable cadence label for the pipeline's automatic triggers (e.g. 'Scheduled at 09:30', 'Every 30 min, and Web monitor (hourly)'). None when not live. | | triggersPaused | boolean | True when the pipeline has automatic triggers that are configured but paused (their workflow is paused, or the trigger itself is paused, so they don't fire). Mutually exclusive with is_live; lets the UI show a distinct 'Paused' state instead of the pipeline silently dropping out of 'Live'. Default: `False`. | | pausedBy | string (`user`, `staff`, `agent`, `system`, `unknown`) \| null | Recorded pause actor kind while triggers_paused; unknown for legacy or mixed actors. Values: `user`, `staff`, `agent`, `system`, `unknown`. | | pausedAt | string (ISO 8601 datetime) \| null | When this pipeline pause was recorded, while triggers_paused. None for a pause with no user record (repair, first build, failure circuit). | | automaticFailureCircuits | object[] | Unresolved automatic-trigger systematic failure circuits for this pipeline. Definitions: [AutomaticTriggerFailureCircuitDTO](#schema-automatictriggerfailurecircuitdto). | | automaticFailureCircuits[].id | string | | | automaticFailureCircuits[].pipelineId | string | | | automaticFailureCircuits[].pipelineRevisionId | string | | | automaticFailureCircuits[].moduleId | string \| null | | | automaticFailureCircuits[].fingerprint | string | | | automaticFailureCircuits[].failureClass | string | | | automaticFailureCircuits[].consecutiveCount | integer | | | automaticFailureCircuits[].firstSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].lastSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].trippedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolvedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolutionReason | string (`connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`) \| null | Values: `connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`. Definitions: [AutomaticTriggerCircuitResolutionReason](#schema-automatictriggercircuitresolutionreason). | | automaticFailureCircuits[].representativeWorkflowRunId | string \| null | | | automaticFailureCircuits[].representativeModuleRunId | string \| null | | | automaticFailureCircuits[].state | string (`armed`, `open`, `resolved`) | Lifecycle of one automatic-trigger failure fingerprint sequence. Values: `armed`, `open`, `resolved`. | | automaticRepairAttempts | object[] | Typed automatic-repair lifecycle records for this Pipeline's contained failures. Definitions: [SystematicCodeRepairAttemptDTO](#schema-systematiccoderepairattemptdto). | | automaticRepairAttempts[].id | string | | | automaticRepairAttempts[].incidentId | string | | | automaticRepairAttempts[].generation | integer | | | automaticRepairAttempts[].route | string (`pipeline_builder`, `unsupported`) | Typed repair destination selected from executable ownership. Values: `pipeline_builder`, `unsupported`. | | automaticRepairAttempts[].state | string (`observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`) | Durable automatic-repair lifecycle. Values: `observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`. | | automaticRepairAttempts[].invocationHostPipelineId | string \| null | | | automaticRepairAttempts[].invocationHostWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceModuleRunId | string \| null | | | automaticRepairAttempts[].repairConversationId | string \| null | | | automaticRepairAttempts[].repairModuleRunId | string \| null | | | automaticRepairAttempts[].replacementParameterizedWorkflowId | string \| null | | | automaticRepairAttempts[].capabilityVersion | string \| null | | | automaticRepairAttempts[].terminalReasonCode | string \| null | | | automaticRepairAttempts[].ownerOverrideRequestedAt | string (ISO 8601 datetime) \| null | | | automaticRepairAttempts[].rearmReason | string (`new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`) \| null | Values: `new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`. Definitions: [SystematicCodeRepairRearmReason](#schema-systematiccoderepairrearmreason). | | automaticRepairAttempts[].validationResult | string (`passed`, `failed`) \| null | Values: `passed`, `failed`. Definitions: [SystematicCodeRepairValidationResult](#schema-systematiccoderepairvalidationresult). | | automaticRepairAttempts[].validationWorkflowRunIds | string[] | | | automaticRepairAttempts[].activatedOwnerVersionId | string \| null | | | hasAgent | boolean | True when the pipeline has at least one active/paused analyst (agent) module. Only populated by the list endpoint; defaults to False on single-pipeline fetches. Default: `False`. | | projectIds | string[] | Project memberships (many-to-many) for list surfaces. | | pipelineUrl | string \| null | | **Request schema (application/json):** ```json { "$ref": "#/components/schemas/CreatePipelineDTO" } ``` Definitions: [CreatePipelineDTO](#schema-createpipelinedto). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineDTO" } ``` Definitions: [ApiPipelineDTO](#schema-apipipelinedto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **429**: Rate limit exceeded: retry after reducing request frequency. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} response = requests.post( f"{BASE_URL}/api/v1/pipelines", headers=HEADERS, json={ "name": 'My API Key', "description": 'description-value', }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Public Pipelines Summary `GET /api/v1/pipelines/summary` Return lightweight summaries of the active Pipelines the authenticated user may run. These are the same Pipelines as `GET /pipelines`: the Pipelines the user created and the Pipelines in Projects the user owns, leaving out sub-Pipelines. The list is not paginated and is ordered by last activity (the Pipeline, its conversations or its runs), most recent first. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | ownerConversationId | string \| null | Owning Builder conversation for the selected oldest unarchived Pipeline; null for other rows. | | description | string \| null | | | updatedAt | string (ISO 8601 datetime) \| null | | | parentPipelineId | string \| null | | | projectIds | string[] | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "items": { "$ref": "#/components/schemas/PipelineSummaryDTO" }, "type": "array", "title": "Response List Public Pipelines Summary" } ``` Definitions: [PipelineSummaryDTO](#schema-pipelinesummarydto). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} response = requests.get( f"{BASE_URL}/api/v1/pipelines/summary", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Pipeline `GET /api/v1/pipelines/{pipeline_id}` Fetch a pipeline by ID. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | itemStatus | object | One item's current state and the time of its latest usable result. | | ownerItemStatus | object | One item's current state and the time of its latest usable result. | | latestTriggerCheck | object \| null | Definitions: [PipelineTriggerCheckDTO](#schema-pipelinetriggercheckdto). | | tickerPages | object[] | Definitions: [PipelineTickerPageDTO](#schema-pipelinetickerpagedto). | | tickerPages[].pageId | string | | | tickerPages[].symbol | string | | | hasOpenBuild | boolean | True when the Pipeline has a nonterminal Builder build. Default: `False`. | | id | string | | | orgId | string | | | createdByUserId | string | | | name | string | | | description | string \| null | | | tags | string[] | Arbitrary string tags for categorization | | status | string (`active`, `archived`) | Values: `active`, `archived`. | | ownerConversationId | string \| null | | | triggerSchedules | object[] | Active-revision and paused trigger schedules. Next occurrences are calendar opportunities, not execution guarantees; conditional triggers check their condition at that time. Definitions: [PipelineTriggerScheduleDTO](#schema-pipelinetriggerscheduledto). | | triggerSchedules[].triggerId | string | | | triggerSchedules[].triggerLogicalId | string \| null | | | triggerSchedules[].webMode | string (`events`, `feed`, `page`) \| null | Values: `events`, `feed`, `page`. Definitions: [WebTriggerMode](#schema-webtriggermode). | | triggerSchedules[].sourceUrl | string \| null | | | triggerSchedules[].triggerKind | string (`time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`) | Values: `time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`. | | triggerSchedules[].summary | string | | | triggerSchedules[].state | string (`scheduled`, `conditional`, `event`, `paused`, `invalid`) | Values: `scheduled`, `conditional`, `event`, `paused`, `invalid`. | | triggerSchedules[].timezone | string \| null | | | triggerSchedules[].hasCondition | boolean | Default: `False`. | | triggerSchedules[].scheduleType | string (`cron`, `times`, `invalid`) \| null | Values: `cron`, `times`, `invalid`. | | triggerSchedules[].cronExpression | string \| null | | | triggerSchedules[].times | string[] | | | triggerSchedules[].issue | string \| null | | | triggerSchedules[].checkIntervalSeconds | integer \| null | | | triggerSchedules[].lastCheckedAt | string (ISO 8601 datetime) \| null | | | triggerSchedules[].lastCheckOutcome | string (`no_change`, `matched`, `failed`, `unknown`) \| null | Values: `no_change`, `matched`, `failed`, `unknown`. | | triggerSchedules[].nextOccurrenceAt | string (ISO 8601 datetime) \| null | Compute at serialization time so cached configurations do not freeze time. Cached DTOs reconstruct this property from the non-executable schedule fields. A condition check is an opportunity, never a promised execution. readOnly: `true`. | | componentPipelineIds | string[] | Component pipeline IDs recorded in pipeline metadata | | sourcePipelineId | string \| null | | | parentPipelineId | string \| null | | | isSubscribed | boolean | Default: `False`. | | lastPushedRevisionId | string \| null | | | lastPushedSourceRevisionId | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | workflowCount | integer | Number of workflows in the pipeline (org-scoped). Default: `0`. | | artifactCount | integer | Artifacts with this pipeline_id (org-scoped). Default: `0`. | | runCount | integer | Workflow runs under workflows in this pipeline (org-scoped). Default: `0`. | | lastRanAt | string (ISO 8601 datetime) \| null | Most recent workflow-run start time across this pipeline's workflows. | | lastRunId | string \| null | ID of the pipeline's most recent workflow run, or None if it never ran. | | lastRunStatus | string \| null | Status of the pipeline's most recent workflow run, or None if it never ran. | | isLive | boolean | True when the pipeline has any automatic trigger. Default: `False`. | | triggerKinds | string[] | Distinct non-manual trigger kinds driving this pipeline (e.g. ['time', 'data']). | | triggerSummary | string \| null | Short human-readable cadence label for the pipeline's automatic triggers (e.g. 'Scheduled at 09:30', 'Every 30 min, and Web monitor (hourly)'). None when not live. | | triggersPaused | boolean | True when the pipeline has automatic triggers that are configured but paused (their workflow is paused, or the trigger itself is paused, so they don't fire). Mutually exclusive with is_live; lets the UI show a distinct 'Paused' state instead of the pipeline silently dropping out of 'Live'. Default: `False`. | | pausedBy | string (`user`, `staff`, `agent`, `system`, `unknown`) \| null | Recorded pause actor kind while triggers_paused; unknown for legacy or mixed actors. Values: `user`, `staff`, `agent`, `system`, `unknown`. | | pausedAt | string (ISO 8601 datetime) \| null | When this pipeline pause was recorded, while triggers_paused. None for a pause with no user record (repair, first build, failure circuit). | | automaticFailureCircuits | object[] | Unresolved automatic-trigger systematic failure circuits for this pipeline. Definitions: [AutomaticTriggerFailureCircuitDTO](#schema-automatictriggerfailurecircuitdto). | | automaticFailureCircuits[].id | string | | | automaticFailureCircuits[].pipelineId | string | | | automaticFailureCircuits[].pipelineRevisionId | string | | | automaticFailureCircuits[].moduleId | string \| null | | | automaticFailureCircuits[].fingerprint | string | | | automaticFailureCircuits[].failureClass | string | | | automaticFailureCircuits[].consecutiveCount | integer | | | automaticFailureCircuits[].firstSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].lastSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].trippedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolvedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolutionReason | string (`connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`) \| null | Values: `connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`. Definitions: [AutomaticTriggerCircuitResolutionReason](#schema-automatictriggercircuitresolutionreason). | | automaticFailureCircuits[].representativeWorkflowRunId | string \| null | | | automaticFailureCircuits[].representativeModuleRunId | string \| null | | | automaticFailureCircuits[].state | string (`armed`, `open`, `resolved`) | Lifecycle of one automatic-trigger failure fingerprint sequence. Values: `armed`, `open`, `resolved`. | | automaticRepairAttempts | object[] | Typed automatic-repair lifecycle records for this Pipeline's contained failures. Definitions: [SystematicCodeRepairAttemptDTO](#schema-systematiccoderepairattemptdto). | | automaticRepairAttempts[].id | string | | | automaticRepairAttempts[].incidentId | string | | | automaticRepairAttempts[].generation | integer | | | automaticRepairAttempts[].route | string (`pipeline_builder`, `unsupported`) | Typed repair destination selected from executable ownership. Values: `pipeline_builder`, `unsupported`. | | automaticRepairAttempts[].state | string (`observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`) | Durable automatic-repair lifecycle. Values: `observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`. | | automaticRepairAttempts[].invocationHostPipelineId | string \| null | | | automaticRepairAttempts[].invocationHostWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceModuleRunId | string \| null | | | automaticRepairAttempts[].repairConversationId | string \| null | | | automaticRepairAttempts[].repairModuleRunId | string \| null | | | automaticRepairAttempts[].replacementParameterizedWorkflowId | string \| null | | | automaticRepairAttempts[].capabilityVersion | string \| null | | | automaticRepairAttempts[].terminalReasonCode | string \| null | | | automaticRepairAttempts[].ownerOverrideRequestedAt | string (ISO 8601 datetime) \| null | | | automaticRepairAttempts[].rearmReason | string (`new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`) \| null | Values: `new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`. Definitions: [SystematicCodeRepairRearmReason](#schema-systematiccoderepairrearmreason). | | automaticRepairAttempts[].validationResult | string (`passed`, `failed`) \| null | Values: `passed`, `failed`. Definitions: [SystematicCodeRepairValidationResult](#schema-systematiccoderepairvalidationresult). | | automaticRepairAttempts[].validationWorkflowRunIds | string[] | | | automaticRepairAttempts[].activatedOwnerVersionId | string \| null | | | hasAgent | boolean | True when the pipeline has at least one active/paused analyst (agent) module. Only populated by the list endpoint; defaults to False on single-pipeline fetches. Default: `False`. | | projectIds | string[] | Project memberships (many-to-many) for list surfaces. | | pipelineUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineDTO" } ``` Definitions: [ApiPipelineDTO](#schema-apipipelinedto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.get( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Update Public Pipeline `PATCH /api/v1/pipelines/{pipeline_id}` Rename or re-describe a pipeline. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | | body | name | string \| null | No | New pipeline name | | body | description | string \| null | No | New pipeline description | | body | tags | string[] \| null | No | Replace tags list | **Response fields:** | Name | Type | Description | | --- | --- | --- | | itemStatus | object | One item's current state and the time of its latest usable result. | | ownerItemStatus | object | One item's current state and the time of its latest usable result. | | latestTriggerCheck | object \| null | Definitions: [PipelineTriggerCheckDTO](#schema-pipelinetriggercheckdto). | | tickerPages | object[] | Definitions: [PipelineTickerPageDTO](#schema-pipelinetickerpagedto). | | tickerPages[].pageId | string | | | tickerPages[].symbol | string | | | hasOpenBuild | boolean | True when the Pipeline has a nonterminal Builder build. Default: `False`. | | id | string | | | orgId | string | | | createdByUserId | string | | | name | string | | | description | string \| null | | | tags | string[] | Arbitrary string tags for categorization | | status | string (`active`, `archived`) | Values: `active`, `archived`. | | ownerConversationId | string \| null | | | triggerSchedules | object[] | Active-revision and paused trigger schedules. Next occurrences are calendar opportunities, not execution guarantees; conditional triggers check their condition at that time. Definitions: [PipelineTriggerScheduleDTO](#schema-pipelinetriggerscheduledto). | | triggerSchedules[].triggerId | string | | | triggerSchedules[].triggerLogicalId | string \| null | | | triggerSchedules[].webMode | string (`events`, `feed`, `page`) \| null | Values: `events`, `feed`, `page`. Definitions: [WebTriggerMode](#schema-webtriggermode). | | triggerSchedules[].sourceUrl | string \| null | | | triggerSchedules[].triggerKind | string (`time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`) | Values: `time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`. | | triggerSchedules[].summary | string | | | triggerSchedules[].state | string (`scheduled`, `conditional`, `event`, `paused`, `invalid`) | Values: `scheduled`, `conditional`, `event`, `paused`, `invalid`. | | triggerSchedules[].timezone | string \| null | | | triggerSchedules[].hasCondition | boolean | Default: `False`. | | triggerSchedules[].scheduleType | string (`cron`, `times`, `invalid`) \| null | Values: `cron`, `times`, `invalid`. | | triggerSchedules[].cronExpression | string \| null | | | triggerSchedules[].times | string[] | | | triggerSchedules[].issue | string \| null | | | triggerSchedules[].checkIntervalSeconds | integer \| null | | | triggerSchedules[].lastCheckedAt | string (ISO 8601 datetime) \| null | | | triggerSchedules[].lastCheckOutcome | string (`no_change`, `matched`, `failed`, `unknown`) \| null | Values: `no_change`, `matched`, `failed`, `unknown`. | | triggerSchedules[].nextOccurrenceAt | string (ISO 8601 datetime) \| null | Compute at serialization time so cached configurations do not freeze time. Cached DTOs reconstruct this property from the non-executable schedule fields. A condition check is an opportunity, never a promised execution. readOnly: `true`. | | componentPipelineIds | string[] | Component pipeline IDs recorded in pipeline metadata | | sourcePipelineId | string \| null | | | parentPipelineId | string \| null | | | isSubscribed | boolean | Default: `False`. | | lastPushedRevisionId | string \| null | | | lastPushedSourceRevisionId | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | workflowCount | integer | Number of workflows in the pipeline (org-scoped). Default: `0`. | | artifactCount | integer | Artifacts with this pipeline_id (org-scoped). Default: `0`. | | runCount | integer | Workflow runs under workflows in this pipeline (org-scoped). Default: `0`. | | lastRanAt | string (ISO 8601 datetime) \| null | Most recent workflow-run start time across this pipeline's workflows. | | lastRunId | string \| null | ID of the pipeline's most recent workflow run, or None if it never ran. | | lastRunStatus | string \| null | Status of the pipeline's most recent workflow run, or None if it never ran. | | isLive | boolean | True when the pipeline has any automatic trigger. Default: `False`. | | triggerKinds | string[] | Distinct non-manual trigger kinds driving this pipeline (e.g. ['time', 'data']). | | triggerSummary | string \| null | Short human-readable cadence label for the pipeline's automatic triggers (e.g. 'Scheduled at 09:30', 'Every 30 min, and Web monitor (hourly)'). None when not live. | | triggersPaused | boolean | True when the pipeline has automatic triggers that are configured but paused (their workflow is paused, or the trigger itself is paused, so they don't fire). Mutually exclusive with is_live; lets the UI show a distinct 'Paused' state instead of the pipeline silently dropping out of 'Live'. Default: `False`. | | pausedBy | string (`user`, `staff`, `agent`, `system`, `unknown`) \| null | Recorded pause actor kind while triggers_paused; unknown for legacy or mixed actors. Values: `user`, `staff`, `agent`, `system`, `unknown`. | | pausedAt | string (ISO 8601 datetime) \| null | When this pipeline pause was recorded, while triggers_paused. None for a pause with no user record (repair, first build, failure circuit). | | automaticFailureCircuits | object[] | Unresolved automatic-trigger systematic failure circuits for this pipeline. Definitions: [AutomaticTriggerFailureCircuitDTO](#schema-automatictriggerfailurecircuitdto). | | automaticFailureCircuits[].id | string | | | automaticFailureCircuits[].pipelineId | string | | | automaticFailureCircuits[].pipelineRevisionId | string | | | automaticFailureCircuits[].moduleId | string \| null | | | automaticFailureCircuits[].fingerprint | string | | | automaticFailureCircuits[].failureClass | string | | | automaticFailureCircuits[].consecutiveCount | integer | | | automaticFailureCircuits[].firstSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].lastSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].trippedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolvedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolutionReason | string (`connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`) \| null | Values: `connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`. Definitions: [AutomaticTriggerCircuitResolutionReason](#schema-automatictriggercircuitresolutionreason). | | automaticFailureCircuits[].representativeWorkflowRunId | string \| null | | | automaticFailureCircuits[].representativeModuleRunId | string \| null | | | automaticFailureCircuits[].state | string (`armed`, `open`, `resolved`) | Lifecycle of one automatic-trigger failure fingerprint sequence. Values: `armed`, `open`, `resolved`. | | automaticRepairAttempts | object[] | Typed automatic-repair lifecycle records for this Pipeline's contained failures. Definitions: [SystematicCodeRepairAttemptDTO](#schema-systematiccoderepairattemptdto). | | automaticRepairAttempts[].id | string | | | automaticRepairAttempts[].incidentId | string | | | automaticRepairAttempts[].generation | integer | | | automaticRepairAttempts[].route | string (`pipeline_builder`, `unsupported`) | Typed repair destination selected from executable ownership. Values: `pipeline_builder`, `unsupported`. | | automaticRepairAttempts[].state | string (`observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`) | Durable automatic-repair lifecycle. Values: `observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`. | | automaticRepairAttempts[].invocationHostPipelineId | string \| null | | | automaticRepairAttempts[].invocationHostWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceModuleRunId | string \| null | | | automaticRepairAttempts[].repairConversationId | string \| null | | | automaticRepairAttempts[].repairModuleRunId | string \| null | | | automaticRepairAttempts[].replacementParameterizedWorkflowId | string \| null | | | automaticRepairAttempts[].capabilityVersion | string \| null | | | automaticRepairAttempts[].terminalReasonCode | string \| null | | | automaticRepairAttempts[].ownerOverrideRequestedAt | string (ISO 8601 datetime) \| null | | | automaticRepairAttempts[].rearmReason | string (`new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`) \| null | Values: `new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`. Definitions: [SystematicCodeRepairRearmReason](#schema-systematiccoderepairrearmreason). | | automaticRepairAttempts[].validationResult | string (`passed`, `failed`) \| null | Values: `passed`, `failed`. Definitions: [SystematicCodeRepairValidationResult](#schema-systematiccoderepairvalidationresult). | | automaticRepairAttempts[].validationWorkflowRunIds | string[] | | | automaticRepairAttempts[].activatedOwnerVersionId | string \| null | | | hasAgent | boolean | True when the pipeline has at least one active/paused analyst (agent) module. Only populated by the list endpoint; defaults to False on single-pipeline fetches. Default: `False`. | | projectIds | string[] | Project memberships (many-to-many) for list surfaces. | | pipelineUrl | string \| null | | **Request schema (application/json):** ```json { "$ref": "#/components/schemas/UpdatePipelineDTO" } ``` Definitions: [UpdatePipelineDTO](#schema-updatepipelinedto). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineDTO" } ``` Definitions: [ApiPipelineDTO](#schema-apipipelinedto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.patch( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}", headers=HEADERS, json={ "name": 'My API Key', "description": 'description-value', }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Archive Public Pipeline `POST /api/v1/pipelines/{pipeline_id}/archive` Soft-delete a pipeline. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | itemStatus | object | One item's current state and the time of its latest usable result. | | ownerItemStatus | object | One item's current state and the time of its latest usable result. | | latestTriggerCheck | object \| null | Definitions: [PipelineTriggerCheckDTO](#schema-pipelinetriggercheckdto). | | tickerPages | object[] | Definitions: [PipelineTickerPageDTO](#schema-pipelinetickerpagedto). | | tickerPages[].pageId | string | | | tickerPages[].symbol | string | | | hasOpenBuild | boolean | True when the Pipeline has a nonterminal Builder build. Default: `False`. | | id | string | | | orgId | string | | | createdByUserId | string | | | name | string | | | description | string \| null | | | tags | string[] | Arbitrary string tags for categorization | | status | string (`active`, `archived`) | Values: `active`, `archived`. | | ownerConversationId | string \| null | | | triggerSchedules | object[] | Active-revision and paused trigger schedules. Next occurrences are calendar opportunities, not execution guarantees; conditional triggers check their condition at that time. Definitions: [PipelineTriggerScheduleDTO](#schema-pipelinetriggerscheduledto). | | triggerSchedules[].triggerId | string | | | triggerSchedules[].triggerLogicalId | string \| null | | | triggerSchedules[].webMode | string (`events`, `feed`, `page`) \| null | Values: `events`, `feed`, `page`. Definitions: [WebTriggerMode](#schema-webtriggermode). | | triggerSchedules[].sourceUrl | string \| null | | | triggerSchedules[].triggerKind | string (`time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`) | Values: `time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`. | | triggerSchedules[].summary | string | | | triggerSchedules[].state | string (`scheduled`, `conditional`, `event`, `paused`, `invalid`) | Values: `scheduled`, `conditional`, `event`, `paused`, `invalid`. | | triggerSchedules[].timezone | string \| null | | | triggerSchedules[].hasCondition | boolean | Default: `False`. | | triggerSchedules[].scheduleType | string (`cron`, `times`, `invalid`) \| null | Values: `cron`, `times`, `invalid`. | | triggerSchedules[].cronExpression | string \| null | | | triggerSchedules[].times | string[] | | | triggerSchedules[].issue | string \| null | | | triggerSchedules[].checkIntervalSeconds | integer \| null | | | triggerSchedules[].lastCheckedAt | string (ISO 8601 datetime) \| null | | | triggerSchedules[].lastCheckOutcome | string (`no_change`, `matched`, `failed`, `unknown`) \| null | Values: `no_change`, `matched`, `failed`, `unknown`. | | triggerSchedules[].nextOccurrenceAt | string (ISO 8601 datetime) \| null | Compute at serialization time so cached configurations do not freeze time. Cached DTOs reconstruct this property from the non-executable schedule fields. A condition check is an opportunity, never a promised execution. readOnly: `true`. | | componentPipelineIds | string[] | Component pipeline IDs recorded in pipeline metadata | | sourcePipelineId | string \| null | | | parentPipelineId | string \| null | | | isSubscribed | boolean | Default: `False`. | | lastPushedRevisionId | string \| null | | | lastPushedSourceRevisionId | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | workflowCount | integer | Number of workflows in the pipeline (org-scoped). Default: `0`. | | artifactCount | integer | Artifacts with this pipeline_id (org-scoped). Default: `0`. | | runCount | integer | Workflow runs under workflows in this pipeline (org-scoped). Default: `0`. | | lastRanAt | string (ISO 8601 datetime) \| null | Most recent workflow-run start time across this pipeline's workflows. | | lastRunId | string \| null | ID of the pipeline's most recent workflow run, or None if it never ran. | | lastRunStatus | string \| null | Status of the pipeline's most recent workflow run, or None if it never ran. | | isLive | boolean | True when the pipeline has any automatic trigger. Default: `False`. | | triggerKinds | string[] | Distinct non-manual trigger kinds driving this pipeline (e.g. ['time', 'data']). | | triggerSummary | string \| null | Short human-readable cadence label for the pipeline's automatic triggers (e.g. 'Scheduled at 09:30', 'Every 30 min, and Web monitor (hourly)'). None when not live. | | triggersPaused | boolean | True when the pipeline has automatic triggers that are configured but paused (their workflow is paused, or the trigger itself is paused, so they don't fire). Mutually exclusive with is_live; lets the UI show a distinct 'Paused' state instead of the pipeline silently dropping out of 'Live'. Default: `False`. | | pausedBy | string (`user`, `staff`, `agent`, `system`, `unknown`) \| null | Recorded pause actor kind while triggers_paused; unknown for legacy or mixed actors. Values: `user`, `staff`, `agent`, `system`, `unknown`. | | pausedAt | string (ISO 8601 datetime) \| null | When this pipeline pause was recorded, while triggers_paused. None for a pause with no user record (repair, first build, failure circuit). | | automaticFailureCircuits | object[] | Unresolved automatic-trigger systematic failure circuits for this pipeline. Definitions: [AutomaticTriggerFailureCircuitDTO](#schema-automatictriggerfailurecircuitdto). | | automaticFailureCircuits[].id | string | | | automaticFailureCircuits[].pipelineId | string | | | automaticFailureCircuits[].pipelineRevisionId | string | | | automaticFailureCircuits[].moduleId | string \| null | | | automaticFailureCircuits[].fingerprint | string | | | automaticFailureCircuits[].failureClass | string | | | automaticFailureCircuits[].consecutiveCount | integer | | | automaticFailureCircuits[].firstSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].lastSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].trippedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolvedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolutionReason | string (`connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`) \| null | Values: `connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`. Definitions: [AutomaticTriggerCircuitResolutionReason](#schema-automatictriggercircuitresolutionreason). | | automaticFailureCircuits[].representativeWorkflowRunId | string \| null | | | automaticFailureCircuits[].representativeModuleRunId | string \| null | | | automaticFailureCircuits[].state | string (`armed`, `open`, `resolved`) | Lifecycle of one automatic-trigger failure fingerprint sequence. Values: `armed`, `open`, `resolved`. | | automaticRepairAttempts | object[] | Typed automatic-repair lifecycle records for this Pipeline's contained failures. Definitions: [SystematicCodeRepairAttemptDTO](#schema-systematiccoderepairattemptdto). | | automaticRepairAttempts[].id | string | | | automaticRepairAttempts[].incidentId | string | | | automaticRepairAttempts[].generation | integer | | | automaticRepairAttempts[].route | string (`pipeline_builder`, `unsupported`) | Typed repair destination selected from executable ownership. Values: `pipeline_builder`, `unsupported`. | | automaticRepairAttempts[].state | string (`observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`) | Durable automatic-repair lifecycle. Values: `observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`. | | automaticRepairAttempts[].invocationHostPipelineId | string \| null | | | automaticRepairAttempts[].invocationHostWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceModuleRunId | string \| null | | | automaticRepairAttempts[].repairConversationId | string \| null | | | automaticRepairAttempts[].repairModuleRunId | string \| null | | | automaticRepairAttempts[].replacementParameterizedWorkflowId | string \| null | | | automaticRepairAttempts[].capabilityVersion | string \| null | | | automaticRepairAttempts[].terminalReasonCode | string \| null | | | automaticRepairAttempts[].ownerOverrideRequestedAt | string (ISO 8601 datetime) \| null | | | automaticRepairAttempts[].rearmReason | string (`new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`) \| null | Values: `new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`. Definitions: [SystematicCodeRepairRearmReason](#schema-systematiccoderepairrearmreason). | | automaticRepairAttempts[].validationResult | string (`passed`, `failed`) \| null | Values: `passed`, `failed`. Definitions: [SystematicCodeRepairValidationResult](#schema-systematiccoderepairvalidationresult). | | automaticRepairAttempts[].validationWorkflowRunIds | string[] | | | automaticRepairAttempts[].activatedOwnerVersionId | string \| null | | | hasAgent | boolean | True when the pipeline has at least one active/paused analyst (agent) module. Only populated by the list endpoint; defaults to False on single-pipeline fetches. Default: `False`. | | projectIds | string[] | Project memberships (many-to-many) for list surfaces. | | pipelineUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineDTO" } ``` Definitions: [ApiPipelineDTO](#schema-apipipelinedto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. - **409**: Conflict: the requested action conflicts with current resource state. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.post( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/archive", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Unarchive Public Pipeline `POST /api/v1/pipelines/{pipeline_id}/unarchive` Restore an archived pipeline. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | itemStatus | object | One item's current state and the time of its latest usable result. | | ownerItemStatus | object | One item's current state and the time of its latest usable result. | | latestTriggerCheck | object \| null | Definitions: [PipelineTriggerCheckDTO](#schema-pipelinetriggercheckdto). | | tickerPages | object[] | Definitions: [PipelineTickerPageDTO](#schema-pipelinetickerpagedto). | | tickerPages[].pageId | string | | | tickerPages[].symbol | string | | | hasOpenBuild | boolean | True when the Pipeline has a nonterminal Builder build. Default: `False`. | | id | string | | | orgId | string | | | createdByUserId | string | | | name | string | | | description | string \| null | | | tags | string[] | Arbitrary string tags for categorization | | status | string (`active`, `archived`) | Values: `active`, `archived`. | | ownerConversationId | string \| null | | | triggerSchedules | object[] | Active-revision and paused trigger schedules. Next occurrences are calendar opportunities, not execution guarantees; conditional triggers check their condition at that time. Definitions: [PipelineTriggerScheduleDTO](#schema-pipelinetriggerscheduledto). | | triggerSchedules[].triggerId | string | | | triggerSchedules[].triggerLogicalId | string \| null | | | triggerSchedules[].webMode | string (`events`, `feed`, `page`) \| null | Values: `events`, `feed`, `page`. Definitions: [WebTriggerMode](#schema-webtriggermode). | | triggerSchedules[].sourceUrl | string \| null | | | triggerSchedules[].triggerKind | string (`time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`) | Values: `time`, `code`, `web`, `file`, `live_artifact`, `knowledge_base`, `dataset`, `result`. | | triggerSchedules[].summary | string | | | triggerSchedules[].state | string (`scheduled`, `conditional`, `event`, `paused`, `invalid`) | Values: `scheduled`, `conditional`, `event`, `paused`, `invalid`. | | triggerSchedules[].timezone | string \| null | | | triggerSchedules[].hasCondition | boolean | Default: `False`. | | triggerSchedules[].scheduleType | string (`cron`, `times`, `invalid`) \| null | Values: `cron`, `times`, `invalid`. | | triggerSchedules[].cronExpression | string \| null | | | triggerSchedules[].times | string[] | | | triggerSchedules[].issue | string \| null | | | triggerSchedules[].checkIntervalSeconds | integer \| null | | | triggerSchedules[].lastCheckedAt | string (ISO 8601 datetime) \| null | | | triggerSchedules[].lastCheckOutcome | string (`no_change`, `matched`, `failed`, `unknown`) \| null | Values: `no_change`, `matched`, `failed`, `unknown`. | | triggerSchedules[].nextOccurrenceAt | string (ISO 8601 datetime) \| null | Compute at serialization time so cached configurations do not freeze time. Cached DTOs reconstruct this property from the non-executable schedule fields. A condition check is an opportunity, never a promised execution. readOnly: `true`. | | componentPipelineIds | string[] | Component pipeline IDs recorded in pipeline metadata | | sourcePipelineId | string \| null | | | parentPipelineId | string \| null | | | isSubscribed | boolean | Default: `False`. | | lastPushedRevisionId | string \| null | | | lastPushedSourceRevisionId | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | workflowCount | integer | Number of workflows in the pipeline (org-scoped). Default: `0`. | | artifactCount | integer | Artifacts with this pipeline_id (org-scoped). Default: `0`. | | runCount | integer | Workflow runs under workflows in this pipeline (org-scoped). Default: `0`. | | lastRanAt | string (ISO 8601 datetime) \| null | Most recent workflow-run start time across this pipeline's workflows. | | lastRunId | string \| null | ID of the pipeline's most recent workflow run, or None if it never ran. | | lastRunStatus | string \| null | Status of the pipeline's most recent workflow run, or None if it never ran. | | isLive | boolean | True when the pipeline has any automatic trigger. Default: `False`. | | triggerKinds | string[] | Distinct non-manual trigger kinds driving this pipeline (e.g. ['time', 'data']). | | triggerSummary | string \| null | Short human-readable cadence label for the pipeline's automatic triggers (e.g. 'Scheduled at 09:30', 'Every 30 min, and Web monitor (hourly)'). None when not live. | | triggersPaused | boolean | True when the pipeline has automatic triggers that are configured but paused (their workflow is paused, or the trigger itself is paused, so they don't fire). Mutually exclusive with is_live; lets the UI show a distinct 'Paused' state instead of the pipeline silently dropping out of 'Live'. Default: `False`. | | pausedBy | string (`user`, `staff`, `agent`, `system`, `unknown`) \| null | Recorded pause actor kind while triggers_paused; unknown for legacy or mixed actors. Values: `user`, `staff`, `agent`, `system`, `unknown`. | | pausedAt | string (ISO 8601 datetime) \| null | When this pipeline pause was recorded, while triggers_paused. None for a pause with no user record (repair, first build, failure circuit). | | automaticFailureCircuits | object[] | Unresolved automatic-trigger systematic failure circuits for this pipeline. Definitions: [AutomaticTriggerFailureCircuitDTO](#schema-automatictriggerfailurecircuitdto). | | automaticFailureCircuits[].id | string | | | automaticFailureCircuits[].pipelineId | string | | | automaticFailureCircuits[].pipelineRevisionId | string | | | automaticFailureCircuits[].moduleId | string \| null | | | automaticFailureCircuits[].fingerprint | string | | | automaticFailureCircuits[].failureClass | string | | | automaticFailureCircuits[].consecutiveCount | integer | | | automaticFailureCircuits[].firstSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].lastSeenAt | string (ISO 8601 datetime) | format: `"date-time"`. | | automaticFailureCircuits[].trippedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolvedAt | string (ISO 8601 datetime) \| null | | | automaticFailureCircuits[].resolutionReason | string (`connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`) \| null | Values: `connection_reconnected`, `fingerprint_changed`, `successful_module_run`, `owner_resumed`, `canary_succeeded`. Definitions: [AutomaticTriggerCircuitResolutionReason](#schema-automatictriggercircuitresolutionreason). | | automaticFailureCircuits[].representativeWorkflowRunId | string \| null | | | automaticFailureCircuits[].representativeModuleRunId | string \| null | | | automaticFailureCircuits[].state | string (`armed`, `open`, `resolved`) | Lifecycle of one automatic-trigger failure fingerprint sequence. Values: `armed`, `open`, `resolved`. | | automaticRepairAttempts | object[] | Typed automatic-repair lifecycle records for this Pipeline's contained failures. Definitions: [SystematicCodeRepairAttemptDTO](#schema-systematiccoderepairattemptdto). | | automaticRepairAttempts[].id | string | | | automaticRepairAttempts[].incidentId | string | | | automaticRepairAttempts[].generation | integer | | | automaticRepairAttempts[].route | string (`pipeline_builder`, `unsupported`) | Typed repair destination selected from executable ownership. Values: `pipeline_builder`, `unsupported`. | | automaticRepairAttempts[].state | string (`observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`) | Durable automatic-repair lifecycle. Values: `observed`, `circuit_open`, `repair_claimed`, `repair_launched`, `diagnosed_no_change`, `patch_applied`, `validation_passed`, `activated`, `failed`. | | automaticRepairAttempts[].invocationHostPipelineId | string \| null | | | automaticRepairAttempts[].invocationHostWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceWorkflowRunId | string \| null | | | automaticRepairAttempts[].sourceModuleRunId | string \| null | | | automaticRepairAttempts[].repairConversationId | string \| null | | | automaticRepairAttempts[].repairModuleRunId | string \| null | | | automaticRepairAttempts[].replacementParameterizedWorkflowId | string \| null | | | automaticRepairAttempts[].capabilityVersion | string \| null | | | automaticRepairAttempts[].terminalReasonCode | string \| null | | | automaticRepairAttempts[].ownerOverrideRequestedAt | string (ISO 8601 datetime) \| null | | | automaticRepairAttempts[].rearmReason | string (`new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`) \| null | Values: `new_active_revision`, `fingerprint_changed`, `owner_override`, `capability_upgrade`. Definitions: [SystematicCodeRepairRearmReason](#schema-systematiccoderepairrearmreason). | | automaticRepairAttempts[].validationResult | string (`passed`, `failed`) \| null | Values: `passed`, `failed`. Definitions: [SystematicCodeRepairValidationResult](#schema-systematiccoderepairvalidationresult). | | automaticRepairAttempts[].validationWorkflowRunIds | string[] | | | automaticRepairAttempts[].activatedOwnerVersionId | string \| null | | | hasAgent | boolean | True when the pipeline has at least one active/paused analyst (agent) module. Only populated by the list endpoint; defaults to False on single-pipeline fetches. Default: `False`. | | projectIds | string[] | Project memberships (many-to-many) for list surfaces. | | pipelineUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineDTO" } ``` Definitions: [ApiPipelineDTO](#schema-apipipelinedto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. - **409**: Conflict: the requested action conflicts with current resource state. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.post( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/unarchive", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Pause Public Pipeline Triggers `POST /api/v1/pipelines/{pipeline_id}/triggers/pause` Pause the Pipeline's automatic triggers, as Pause does in the app. Pauses every live Workflow of the active revision and its sub-Pipelines' triggers, without archiving the Pipeline. Repeating it changes nothing. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | triggersPaused | boolean | Whether the Pipeline's automatic triggers are now paused | | updatedWorkflowIds | string[] | Workflows whose triggers this request changed | | message | string | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineTriggerStateResponse" } ``` Definitions: [ApiPipelineTriggerStateResponse](#schema-apipipelinetriggerstateresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.post( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/triggers/pause", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Resume Public Pipeline Triggers `POST /api/v1/pipelines/{pipeline_id}/triggers/resume` Resume the Pipeline's paused automatic triggers, as Resume does in the app. A sub-Pipeline paused on its own stays paused. Repeating it changes nothing. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | triggersPaused | boolean | Whether the Pipeline's automatic triggers are now paused | | updatedWorkflowIds | string[] | Workflows whose triggers this request changed | | message | string | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineTriggerStateResponse" } ``` Definitions: [ApiPipelineTriggerStateResponse](#schema-apipipelinetriggerstateresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.post( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/triggers/resume", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Run Public Pipeline `POST /api/v1/pipelines/{pipeline_id}/runs` Run the whole Pipeline once, as Run does in the app. Starts the active revision's entry points that have work; a source with no new event starts nothing, and the response lists no runs. Follow each run with `GET /workflow-runs/{workflow_run_id}`. Answers 404 for a missing Pipeline or one without an active revision, and 409 when the active revision has no Workflows. To run one Workflow, use `POST /workflows/{workflow_id}/runs`. A Pipeline that starts from a file needs `file`: a Knowledge Base document id (an uploaded document that is ready), or the id of a file its file trigger delivered. Only the file trigger runs, on that document. Answers 404 for a Knowledge Base document that is not yours, and 409 for a document that is not ready or cannot be a file input, or a Pipeline with no file trigger. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | workflowRunIds | string[] | Started Workflow runs; follow each with GET /workflow-runs/{id} | | startedWorkflowIds | string[] | | | runUrls | string[] | The API URL of each started run, in workflowRunIds order | | message | string | | **Request schema (application/json):** ```json { "anyOf": [ { "$ref": "#/components/schemas/ApiPipelineRunRequest" }, { "type": "null" } ], "title": "Body" } ``` Definitions: [ApiPipelineRunRequest](#schema-apipipelinerunrequest). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineRunResponse" } ``` Definitions: [ApiPipelineRunResponse](#schema-apipipelinerunresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. - **409**: Conflict: the requested action conflicts with current resource state. - **429**: Rate limit exceeded: retry after reducing request frequency. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.post( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/runs", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Pipeline Latest Run `GET /api/v1/pipelines/{pipeline_id}/runs/latest` Read the Pipeline's latest completed run with its outputs, as Mana's MCP `get_pipeline_run` does. The latest run is the newest completed top-level run that is not a validation run. Answers 404 for a Pipeline the user may not run (one they did not create and that is in no Project they own) and for a Pipeline with no completed run yet. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | workflowId | string | | | pipelineId | string | | | status | string (`pending`, `running`, `completed`, `failed`, `cancelled`) | Values: `pending`, `running`, `completed`, `failed`, `cancelled`. | | summary | string \| null | | | checkSummary | object \| null | Definitions: [WorkflowRunCheckSummary](#schema-workflowrunchecksummary). | | runUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | summaryStatus | string (`ready`, `pending`, `unavailable`) | `ready`: the summary is final. `pending`: read again later for the summary, even when the status is final. `unavailable`: this run has no summary; use its artifacts. Values: `ready`, `pending`, `unavailable`. | | pipelineUrl | string \| null | Link to the Pipeline in the Mana app. | | runPageUrl | string \| null | Link to this run in the Mana app. | | artifacts | object[] | At most 20 of the run's artifacts. List all of them with `GET /workflow-runs/{id}/artifacts`. Definitions: [ApiArtifactDTO](#schema-apiartifactdto). | | artifacts[].id | string | | | artifacts[].title | string | | | artifacts[].description | string \| null | | | artifacts[].type | string (`structured_data`, `text`, `json`, `csv`, `report`, `chart`, `table`, `list`, `data`, `link`, `document`, `image`, `code`, `signal`, `other`) | Values: `structured_data`, `text`, `json`, `csv`, `report`, `chart`, `table`, `list`, `data`, `link`, `document`, `image`, `code`, `signal`, `other`. | | artifacts[].category | string (`terminal`, `intermediate`, `report`) | Values: `terminal`, `intermediate`, `report`. | | artifacts[].status | string (`pending`, `generated`, `validated`, `error`) | Values: `pending`, `generated`, `validated`, `error`. | | artifacts[].mimeType | string \| null | | | artifacts[].filePath | string \| null | | | artifacts[].sizeBytes | integer \| null | | | artifacts[].sourceType | string (`user_upload`, `agent`, `module`, `system`) \| null | Values: `user_upload`, `agent`, `module`, `system`. Definitions: [ArtifactSourceType](#schema-artifactsourcetype). | | artifacts[].pipelineId | string \| null | | | artifacts[].conversationId | string \| null | | | artifacts[].pipelineUrl | string \| null | | | artifacts[].conversationUrl | string \| null | | | artifacts[].downloadUrl | string \| null | | | artifacts[].createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | artifacts[].updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | dashboards | object[] | The Pipeline's dashboards, each at its latest version. Definitions: [ApiDashboardSummaryDTO](#schema-apidashboardsummarydto). | | dashboards[].id | string | | | dashboards[].pipelineId | string | | | dashboards[].lineageId | string | | | dashboards[].version | integer | | | dashboards[].name | string | | | dashboards[].description | string \| null | | | dashboards[].status | string (`active`, `archived`) | Values: `active`, `archived`. | | dashboards[].createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | dashboards[].updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | dashboards[].previewCellId | string \| null | | | dashboards[].previewVersion | string \| null | | | dashboards[].pipelineUrl | string \| null | | | dashboards[].dashboardUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineRunOutputDTO" } ``` Definitions: [ApiPipelineRunOutputDTO](#schema-apipipelinerunoutputdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.get( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/runs/latest", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Pipeline Run `GET /api/v1/pipelines/{pipeline_id}/runs/{workflow_run_id}` Read one run of the Pipeline with its outputs, as Mana's MCP `get_pipeline_run` does. Read again while `status` is `pending` or `running`, or while `summaryStatus` is `pending`. Answers 404 for a Pipeline the user may not run and for a run that does not belong to the Pipeline. A later stage's run id from `POST /pipelines/{pipeline_id}/runs` answers 404 until its stage starts. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | | path | workflow_run_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | workflowId | string | | | pipelineId | string | | | status | string (`pending`, `running`, `completed`, `failed`, `cancelled`) | Values: `pending`, `running`, `completed`, `failed`, `cancelled`. | | summary | string \| null | | | checkSummary | object \| null | Definitions: [WorkflowRunCheckSummary](#schema-workflowrunchecksummary). | | runUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | summaryStatus | string (`ready`, `pending`, `unavailable`) | `ready`: the summary is final. `pending`: read again later for the summary, even when the status is final. `unavailable`: this run has no summary; use its artifacts. Values: `ready`, `pending`, `unavailable`. | | pipelineUrl | string \| null | Link to the Pipeline in the Mana app. | | runPageUrl | string \| null | Link to this run in the Mana app. | | artifacts | object[] | At most 20 of the run's artifacts. List all of them with `GET /workflow-runs/{id}/artifacts`. Definitions: [ApiArtifactDTO](#schema-apiartifactdto). | | artifacts[].id | string | | | artifacts[].title | string | | | artifacts[].description | string \| null | | | artifacts[].type | string (`structured_data`, `text`, `json`, `csv`, `report`, `chart`, `table`, `list`, `data`, `link`, `document`, `image`, `code`, `signal`, `other`) | Values: `structured_data`, `text`, `json`, `csv`, `report`, `chart`, `table`, `list`, `data`, `link`, `document`, `image`, `code`, `signal`, `other`. | | artifacts[].category | string (`terminal`, `intermediate`, `report`) | Values: `terminal`, `intermediate`, `report`. | | artifacts[].status | string (`pending`, `generated`, `validated`, `error`) | Values: `pending`, `generated`, `validated`, `error`. | | artifacts[].mimeType | string \| null | | | artifacts[].filePath | string \| null | | | artifacts[].sizeBytes | integer \| null | | | artifacts[].sourceType | string (`user_upload`, `agent`, `module`, `system`) \| null | Values: `user_upload`, `agent`, `module`, `system`. Definitions: [ArtifactSourceType](#schema-artifactsourcetype). | | artifacts[].pipelineId | string \| null | | | artifacts[].conversationId | string \| null | | | artifacts[].pipelineUrl | string \| null | | | artifacts[].conversationUrl | string \| null | | | artifacts[].downloadUrl | string \| null | | | artifacts[].createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | artifacts[].updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | dashboards | object[] | The Pipeline's dashboards, each at its latest version. Definitions: [ApiDashboardSummaryDTO](#schema-apidashboardsummarydto). | | dashboards[].id | string | | | dashboards[].pipelineId | string | | | dashboards[].lineageId | string | | | dashboards[].version | integer | | | dashboards[].name | string | | | dashboards[].description | string \| null | | | dashboards[].status | string (`active`, `archived`) | Values: `active`, `archived`. | | dashboards[].createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | dashboards[].updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | dashboards[].previewCellId | string \| null | | | dashboards[].previewVersion | string \| null | | | dashboards[].pipelineUrl | string \| null | | | dashboards[].dashboardUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiPipelineRunOutputDTO" } ``` Definitions: [ApiPipelineRunOutputDTO](#schema-apipipelinerunoutputdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] workflow_run_id = os.environ["MANA_WORKFLOW_RUN_ID"] response = requests.get( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/runs/{workflow_run_id}", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Public Pipeline Workflows `GET /api/v1/pipelines/{pipeline_id}/workflows` List workflows selected by the pipeline's active revision. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | description | string \| null | | | status | string | | | pipelineId | string | | | pipelineUrl | string \| null | | | workflowUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiWorkflowSummary" }, "title": "Response List Public Pipeline Workflows" } ``` Definitions: [ApiWorkflowSummary](#schema-apiworkflowsummary). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.get( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/workflows", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Workflow Modules `GET /api/v1/workflows/{workflow_id}/modules` Return one workflow's module DAG without module source code. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | workflow_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | workflowId | string | | | modules | object[] | Definitions: [ApiModuleNode](#schema-apimodulenode). | | modules[].id | string | | | modules[].name | string | | | modules[].description | string \| null | | | modules[].moduleType | string | | | modules[].status | string | | | edges | object[] | Definitions: [ApiPipelineModuleEdge](#schema-apipipelinemoduleedge). | | edges[].sourceModuleId | string | | | edges[].targetModuleId | string | | | edges[].kind | string | Default: `dependency`. | | edges[].passResults | boolean | Default: `True`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiWorkflowModulesResponse" } ``` Definitions: [ApiWorkflowModulesResponse](#schema-apiworkflowmodulesresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. workflow_id = os.environ["MANA_WORKFLOW_ID"] response = requests.get( f"{BASE_URL}/api/v1/workflows/{workflow_id}/modules", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Workflow `GET /api/v1/workflows/{workflow_id}` Fetch workflow metadata and entry point module IDs. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | workflow_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | description | string \| null | | | status | string | | | pipelineId | string | | | pipelineUrl | string \| null | | | workflowUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | entryPointModuleIds | string[] | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiWorkflowDTO" } ``` Definitions: [ApiWorkflowDTO](#schema-apiworkflowdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. workflow_id = os.environ["MANA_WORKFLOW_ID"] response = requests.get( f"{BASE_URL}/api/v1/workflows/{workflow_id}", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Public Workflow Runs `GET /api/v1/workflows/{workflow_id}/runs` List workflow runs newest first. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | workflow_id | string | Yes | | | query | status | string \| null | No | Filter by status: pending, running, completed, failed, cancelled | | query | limit | integer | No | Default: `50`. minimum: `1`. maximum: `100`. | | query | offset | integer | No | Default: `0`. minimum: `0`. | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | workflowId | string | | | pipelineId | string | | | status | string (`pending`, `running`, `completed`, `failed`, `cancelled`) | Values: `pending`, `running`, `completed`, `failed`, `cancelled`. | | summary | string \| null | | | checkSummary | object \| null | Definitions: [WorkflowRunCheckSummary](#schema-workflowrunchecksummary). | | runUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiWorkflowRunSummary" }, "title": "Response List Public Workflow Runs" } ``` Definitions: [ApiWorkflowRunSummary](#schema-apiworkflowrunsummary). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. workflow_id = os.environ["MANA_WORKFLOW_ID"] response = requests.get( f"{BASE_URL}/api/v1/workflows/{workflow_id}/runs", headers=HEADERS, params={ "limit": 50, "offset": 0, }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Create Public Workflow Run `POST /api/v1/workflows/{workflow_id}/runs` Start a manual workflow run and return immediately. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | workflow_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | workflowRunId | string | | | status | string (`pending`, `running`, `completed`, `failed`, `cancelled`) | Values: `pending`, `running`, `completed`, `failed`, `cancelled`. | | runUrl | string | | | streamUrl | string \| null | | **Request schema (application/json):** ```json { "anyOf": [ { "$ref": "#/components/schemas/ApiWorkflowRunRequest" }, { "type": "null" } ], "title": "Request" } ``` Definitions: [ApiWorkflowRunRequest](#schema-apiworkflowrunrequest). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiWorkflowRunResponse" } ``` Definitions: [ApiWorkflowRunResponse](#schema-apiworkflowrunresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. - **409**: Conflict: the requested action conflicts with current resource state. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. workflow_id = os.environ["MANA_WORKFLOW_ID"] response = requests.post( f"{BASE_URL}/api/v1/workflows/{workflow_id}/runs", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Workflow Run Artifacts `GET /api/v1/workflow-runs/{workflow_run_id}/artifacts` List artifacts produced during a workflow run. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | workflow_run_id | string | Yes | | | query | limit | integer | No | Default: `50`. minimum: `1`. maximum: `100`. | | query | offset | integer | No | Default: `0`. minimum: `0`. | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | title | string | | | description | string \| null | | | type | string (`structured_data`, `text`, `json`, `csv`, `report`, `chart`, `table`, `list`, `data`, `link`, `document`, `image`, `code`, `signal`, `other`) | Values: `structured_data`, `text`, `json`, `csv`, `report`, `chart`, `table`, `list`, `data`, `link`, `document`, `image`, `code`, `signal`, `other`. | | category | string (`terminal`, `intermediate`, `report`) | Values: `terminal`, `intermediate`, `report`. | | status | string (`pending`, `generated`, `validated`, `error`) | Values: `pending`, `generated`, `validated`, `error`. | | mimeType | string \| null | | | filePath | string \| null | | | sizeBytes | integer \| null | | | sourceType | string (`user_upload`, `agent`, `module`, `system`) \| null | Values: `user_upload`, `agent`, `module`, `system`. Definitions: [ArtifactSourceType](#schema-artifactsourcetype). | | pipelineId | string \| null | | | conversationId | string \| null | | | pipelineUrl | string \| null | | | conversationUrl | string \| null | | | downloadUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiArtifactDTO" }, "title": "Response Get Public Workflow Run Artifacts" } ``` Definitions: [ApiArtifactDTO](#schema-apiartifactdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. workflow_run_id = os.environ["MANA_WORKFLOW_RUN_ID"] response = requests.get( f"{BASE_URL}/api/v1/workflow-runs/{workflow_run_id}/artifacts", headers=HEADERS, params={ "limit": 50, "offset": 0, }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Workflow Run Live Artifacts `GET /api/v1/workflow-runs/{workflow_run_id}/live-artifacts` List LiveArtifacts appended to during a workflow run. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | workflow_run_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | description | string \| null | | | type | string | | | schemaDefinition | object | | | pipelineId | string \| null | | | pipelineUrl | string \| null | | | streamUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiLiveArtifactDTO" }, "title": "Response Get Public Workflow Run Live Artifacts" } ``` Definitions: [ApiLiveArtifactDTO](#schema-apiliveartifactdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. workflow_run_id = os.environ["MANA_WORKFLOW_RUN_ID"] response = requests.get( f"{BASE_URL}/api/v1/workflow-runs/{workflow_run_id}/live-artifacts", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Workflow Run `GET /api/v1/workflow-runs/{workflow_run_id}` Fetch workflow run metadata. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | workflow_run_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | workflowId | string | | | pipelineId | string | | | status | string (`pending`, `running`, `completed`, `failed`, `cancelled`) | Values: `pending`, `running`, `completed`, `failed`, `cancelled`. | | summary | string \| null | | | checkSummary | object \| null | Definitions: [WorkflowRunCheckSummary](#schema-workflowrunchecksummary). | | runUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiWorkflowRunDTO" } ``` Definitions: [ApiWorkflowRunDTO](#schema-apiworkflowrundto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. workflow_run_id = os.environ["MANA_WORKFLOW_RUN_ID"] response = requests.get( f"{BASE_URL}/api/v1/workflow-runs/{workflow_run_id}", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Module `GET /api/v1/modules/{module_id}` Fetch public module metadata without source code. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | module_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | description | string \| null | | | purpose | string \| null | | | moduleType | string | | | status | string | | | expectedOutputType | string \| null | | | parameters | object | | | defaultTriggerConfig | object | | | pipelineId | string \| null | | | workflowId | string \| null | | | pipelineUrl | string \| null | | | workflowUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiModuleDTO" } ``` Definitions: [ApiModuleDTO](#schema-apimoduledto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. module_id = os.environ["MANA_MODULE_ID"] response = requests.get( f"{BASE_URL}/api/v1/modules/{module_id}", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Public Pipeline Artifacts `GET /api/v1/pipelines/{pipeline_id}/artifacts` List artifacts in a pipeline. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | title | string | | | reportPresentation | object | Labels beside a report's delivery date, separate from its finding title. | | description | string \| null | | | type | string | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | isInbox | boolean | Default: `False`. | | inboxHeld | boolean | Default: `False`. | | isRead | boolean | Default: `False`. | | moduleRunId | string \| null | | | workflowName | string \| null | | | pipelineId | string \| null | | | pipelineName | string \| null | | | canOpenPipeline | boolean | Default: `False`. | | tickerPages | object[] | Definitions: [PipelineTickerPageDTO](#schema-pipelinetickerpagedto). | | tickerPages[].pageId | string | | | tickerPages[].symbol | string | | | reportKind | string \| null | | | sourceKind | string (`pipeline`, `task`) \| null | Values: `pipeline`, `task`. | | sourceConversationId | string \| null | | | sourceTitle | string \| null | | | mimeType | string \| null | | | fileExtension | string \| null | | | category | string \| null | | | downloadUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiPipelineArtifactSummary" }, "title": "Response List Public Pipeline Artifacts" } ``` Definitions: [ApiPipelineArtifactSummary](#schema-apipipelineartifactsummary). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.get( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/artifacts", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Upload Artifact `POST /api/v1/artifacts/upload` Upload a file as an artifact in a single multipart request. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | form | file | string | Yes | | | form | title | string \| null | No | | | form | description | string \| null | No | | | form | pipeline_id | string \| null | No | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | title | string | | | mimeType | string \| null | | | sizeBytes | integer | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | pipelineId | string \| null | | | pipelineUrl | string \| null | | | downloadUrl | string \| null | | **Request schema (multipart/form-data):** ```json { "$ref": "#/components/schemas/Body_upload_artifact" } ``` Definitions: [Body_upload_artifact](#schema-body_upload_artifact). **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiUploadArtifactResponse" } ``` Definitions: [ApiUploadArtifactResponse](#schema-apiuploadartifactresponse). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **413**: Payload too large: uploaded artifact exceeds the maximum supported size. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} with open("artifact.csv", "rb") as file: response = requests.post( f"{BASE_URL}/api/v1/artifacts/upload", headers=HEADERS, files={"file": file}, data={ "title": 'Quarterly research', }, timeout=120, ) response.raise_for_status() print(response.json()) ``` --- ### Download Artifact `GET /api/v1/artifacts/{artifact_id}/download` Authorize the reader and stream the artifact's original bytes as an attachment. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | artifact_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | response | file | format: `"binary"`. | **Responses:** - **200**: Artifact file bytes with the stored content type and an attachment filename. Content type: `application/octet-stream` ```json { "type": "string", "format": "binary" } ``` - **206**: The requested single byte range, with Content-Range and Accept-Ranges headers. Content type: `application/octet-stream` ```json { "type": "string", "format": "binary" } ``` - **416**: The byte range is unsatisfiable. Content-Range reports the full file size. - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. artifact_id = os.environ["MANA_ARTIFACT_ID"] response = requests.get( f"{BASE_URL}/api/v1/artifacts/{artifact_id}/download", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.content) ``` --- ### List Public Pipeline Live Artifacts `GET /api/v1/pipelines/{pipeline_id}/live-artifacts` List live artifacts in a pipeline. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | | query | pipeline_revision_id | string \| null | No | Optional pipeline revision scope | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | description | string \| null | | | type | string | | | schemaDefinition | object | | | pipelineId | string \| null | | | pipelineUrl | string \| null | | | streamUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiLiveArtifactDTO" }, "title": "Response List Public Pipeline Live Artifacts" } ``` Definitions: [ApiLiveArtifactDTO](#schema-apiliveartifactdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.get( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/live-artifacts", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Public Pipeline Dashboards `GET /api/v1/pipelines/{pipeline_id}/dashboards` List latest dashboards for a pipeline. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | pipeline_id | string | Yes | | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | pipelineId | string | | | lineageId | string | | | version | integer | | | name | string | | | description | string \| null | | | status | string (`active`, `archived`) | Values: `active`, `archived`. | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | | previewCellId | string \| null | | | previewVersion | string \| null | | | pipelineUrl | string \| null | | | dashboardUrl | string \| null | | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiDashboardSummaryDTO" }, "title": "Response List Public Pipeline Dashboards" } ``` Definitions: [ApiDashboardSummaryDTO](#schema-apidashboardsummarydto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. pipeline_id = os.environ["MANA_PIPELINE_ID"] response = requests.get( f"{BASE_URL}/api/v1/pipelines/{pipeline_id}/dashboards", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Public Live Artifacts `GET /api/v1/live-artifacts` List live artifacts for the authenticated user. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | query | pipeline_id | string \| null | No | Optional pipeline filter | | query | pipeline_revision_id | string \| null | No | Optional pipeline revision scope | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | description | string \| null | | | type | string | | | schemaDefinition | object | | | pipelineId | string \| null | | | pipelineUrl | string \| null | | | streamUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiLiveArtifactDTO" }, "title": "Response List Public Live Artifacts" } ``` Definitions: [ApiLiveArtifactDTO](#schema-apiliveartifactdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} response = requests.get( f"{BASE_URL}/api/v1/live-artifacts", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Live Artifact `GET /api/v1/live-artifacts/{live_artifact_id}` Fetch a live artifact by ID. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | live_artifact_id | string | Yes | | | query | pipeline_id | string \| null | No | Optional pipeline scope | | query | pipeline_revision_id | string \| null | No | Optional pipeline revision scope | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | description | string \| null | | | type | string | | | schemaDefinition | object | | | pipelineId | string \| null | | | pipelineUrl | string \| null | | | streamUrl | string \| null | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiLiveArtifactDTO" } ``` Definitions: [ApiLiveArtifactDTO](#schema-apiliveartifactdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. live_artifact_id = os.environ["MANA_LIVE_ARTIFACT_ID"] response = requests.get( f"{BASE_URL}/api/v1/live-artifacts/{live_artifact_id}", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Get Public Live Artifact Data `GET /api/v1/live-artifacts/{live_artifact_id}/data` Fetch paginated rows from a live artifact. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | live_artifact_id | string | Yes | | | query | limit | integer | No | Default: `1000`. minimum: `1`. maximum: `10000`. | | query | offset | integer | No | Default: `0`. minimum: `0`. maximum: `1000000`. | | query | pipeline_id | string \| null | No | Optional pipeline scope | | query | pipeline_revision_id | string \| null | No | Optional pipeline revision scope | **Response fields:** | Name | Type | Description | | --- | --- | --- | | liveArtifactId | string | | | columns | object[] | | | rows | object[] | | | returnedRows | integer | | | totalRows | integer | | | offset | integer | | | truncated | boolean | | | storageBytes | integer \| null | Compressed on-disk size of the authoritative backing store in bytes, when available. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/LiveArtifactDataDTO" } ``` Definitions: [LiveArtifactDataDTO](#schema-liveartifactdatadto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. live_artifact_id = os.environ["MANA_LIVE_ARTIFACT_ID"] response = requests.get( f"{BASE_URL}/api/v1/live-artifacts/{live_artifact_id}/data", headers=HEADERS, params={ "limit": 1000, "offset": 0, }, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Stream Live Artifact `GET /api/v1/live-artifacts/{live_artifact_id}/stream` Stream change notifications for a live artifact as Server-Sent Events. Each `live_artifact` event carries the table's metadata, including `updated_at` and `row_count`, not its rows; read rows from the `/data` endpoint. `heartbeat` events keep the connection open. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | path | live_artifact_id | string | Yes | | | query | pipeline_id | string \| null | No | Optional pipeline scope | | query | pipeline_revision_id | string \| null | No | Optional pipeline revision scope | **Responses:** - **200**: Successful Response Content type: `application/json` ```json {} ``` - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. - **404**: Not found: the resource does not exist or is not visible to the authenticated principal. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} # Set these environment variables to IDs returned by the corresponding create/list endpoints. live_artifact_id = os.environ["MANA_LIVE_ARTIFACT_ID"] response = requests.get( f"{BASE_URL}/api/v1/live-artifacts/{live_artifact_id}/stream", headers={**HEADERS, "Accept": "text/event-stream"}, stream=True, timeout=600, ) response.raise_for_status() for line in response.iter_lines(decode_unicode=True): print(line) ``` --- ### List Public Projects `GET /api/v1/projects` List your Projects, as the app's Projects page does. Pass a Project's `id` as `projectId` when you create a conversation to file it there. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Parameters:** | Location | Name | Type | Required | Description | | --- | --- | --- | --- | --- | | query | status | string (`active`, `archived`, `all`) | No | Which Projects to list Values: `active`, `archived`, `all`. Default: `active`. | **Response fields:** | Name | Type | Description | | --- | --- | --- | | id | string | | | name | string | | | description | string \| null | | | status | string | `active` or `archived` | | pipelineCount | integer | | | conversationCount | integer | | | createdAt | string (ISO 8601 datetime) | format: `"date-time"`. | | updatedAt | string (ISO 8601 datetime) | format: `"date-time"`. | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "type": "array", "items": { "$ref": "#/components/schemas/ApiProjectDTO" }, "title": "Response List Public Projects" } ``` Definitions: [ApiProjectDTO](#schema-apiprojectdto). - **422**: Validation error: request parameters or body failed schema validation. Content type: `application/json` ```json { "$ref": "#/components/schemas/HTTPValidationError" } ``` Definitions: [HTTPValidationError](#schema-httpvalidationerror). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} response = requests.get( f"{BASE_URL}/api/v1/projects", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### List Public Models `GET /api/v1/models` List the models you can pass as `model` when you create a conversation, as the app's model picker does. Each model lists the `reasoning` values creation accepts with it. When your account is in a program with a set model, every conversation runs on that model whatever `model` says: `programModelId` names it and it is the only model listed. Omit `model` to use the agent's own default. Answers 503 when the model catalog cannot be read. **Authentication:** API key created in the Mana web app. Use for authenticated public API calls. **Response fields:** | Name | Type | Description | | --- | --- | --- | | models | object[] | Definitions: [ApiModelDTO](#schema-apimodeldto). | | models[].id | string | The value to pass as `model` when you create a conversation | | models[].label | string | | | models[].reasoningLevels | string[] | Values the model accepts as `reasoning` | | programModelId | string \| null | When set, the caller's program runs every conversation on this model, whatever `model` says, and `models` lists only it | **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "$ref": "#/components/schemas/ApiModelsResponse" } ``` Definitions: [ApiModelsResponse](#schema-apimodelsresponse). - **400**: Bad request: invalid cursor, unsupported value, or malformed request state. - **401**: Unauthorized: missing, invalid, or expired authentication credentials. - **403**: Forbidden: credentials are valid but cannot access this resource or auth mode is not allowed. - **500**: Internal server error: an unexpected server-side failure occurred. **Example:** ```python import os import requests BASE_URL = "https://backend-alpha.mana.ai" API_KEY = os.environ["MANA_API_KEY"] HEADERS = {"X-API-Key": API_KEY} response = requests.get( f"{BASE_URL}/api/v1/models", headers=HEADERS, timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ### Health Check `GET /api/v1/health` Report that the API is up. Call it without authentication. **Authentication:** None required. **Responses:** - **200**: Successful Response Content type: `application/json` ```json { "additionalProperties": true, "type": "object", "title": "Response Health Check" } ``` **Example:** ```python import requests BASE_URL = "https://backend-alpha.mana.ai" response = requests.get( f"{BASE_URL}/api/v1/health", timeout=30, ) response.raise_for_status() print(response.json()) ``` --- ## Schema definitions ### Schema ApiArtifactDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "type": { "$ref": "#/components/schemas/ArtifactType" }, "category": { "$ref": "#/components/schemas/ArtifactCategory" }, "status": { "$ref": "#/components/schemas/ArtifactStatus" }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mimetype" }, "filePath": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filepath" }, "sizeBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sizebytes" }, "sourceType": { "anyOf": [ { "$ref": "#/components/schemas/ArtifactSourceType" }, { "type": "null" } ] }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineid" }, "conversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversationid" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" }, "conversationUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversationurl" }, "downloadUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Downloadurl" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "title", "type", "category", "status", "createdAt", "updatedAt" ], "title": "ApiArtifactDTO", "description": "Artifact metadata for public API responses." } ``` Referenced definitions: [ArtifactCategory](#schema-artifactcategory), [ArtifactSourceType](#schema-artifactsourcetype), [ArtifactStatus](#schema-artifactstatus), [ArtifactType](#schema-artifacttype). ### Schema ApiConversationHistoryItem ```json { "properties": { "sequence": { "type": "integer", "title": "Sequence" }, "messageType": { "type": "string", "title": "Messagetype" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content" }, "messageData": { "additionalProperties": true, "type": "object", "title": "Messagedata" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat" }, "conversationUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversationurl" } }, "type": "object", "required": [ "sequence", "messageType", "messageData" ], "title": "ApiConversationHistoryItem", "description": "Public protocol message summary with API URL fields." } ``` ### Schema ApiConversationListItem ```json { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Projectid" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updatedat" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineid" }, "parentConversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentconversationid" }, "conversationUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversationurl" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" } }, "type": "object", "required": [ "id" ], "title": "ApiConversationListItem", "description": "Public conversation list item with API URL fields." } ``` ### Schema ApiConversationListPage ```json { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiConversationListItem" }, "type": "array", "title": "Items" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" } }, "type": "object", "title": "ApiConversationListPage", "description": "Paginated public conversation list response." } ``` Referenced definitions: [ApiConversationListItem](#schema-apiconversationlistitem). ### Schema ApiConversationStatusResponse ```json { "properties": { "conversationId": { "type": "string", "title": "Conversationid" }, "status": { "type": "string", "title": "Status" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "pendingQuestion": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Pendingquestion" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updatedat" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineid" }, "parentConversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentconversationid" }, "conversationUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversationurl" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" }, "streamUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Streamurl" } }, "type": "object", "required": [ "conversationId", "status" ], "title": "ApiConversationStatusResponse", "description": "Public conversation status for polling clients." } ``` ### Schema ApiConversationWorkStopResponse ```json { "properties": { "stoppedConversationIds": { "items": { "type": "string" }, "type": "array", "title": "Stoppedconversationids", "description": "The conversation and every agent it delegated to that was still running" } }, "type": "object", "required": [ "stoppedConversationIds" ], "title": "ApiConversationWorkStopResponse", "description": "Conversations that a public stop-work request marked stopped, children first." } ``` ### Schema ApiCreateConversationRequest ```json { "properties": { "prompt": { "type": "string", "title": "Prompt", "description": "The user's prompt to start the conversation" }, "agentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agenttype", "description": "Agent type for the run. Public JSON request bodies use the camelCase alias `agentType`. Supported public values are `jethro` (the default), `exploratory` and `pipeline-builder`. Jethro answers or hands the work to a specialist, such as Pipeline Builder for a Pipeline, as the Mana app does; it takes no `model`, `reasoning` or `responseSchema`. A deployment that does not run Jethro uses `exploratory` as the default and refuses `jethro` with 422. A follow-up that omits it keeps the conversation's agent.", "example": "jethro" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Optional conversation title" }, "artifactIds": { "items": { "type": "string" }, "type": "array", "title": "Artifactids", "description": "Optional artifact IDs to attach" }, "responseSchema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Responseschema", "description": "Optional JSON Schema used to extract structured output from the final report. Exploratory only: a new conversation must name `agentType` `exploratory`, because the default, Jethro, refuses it with 422. A follow-up that sends it runs as Exploratory." }, "parentConversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentconversationid", "description": "ID of an existing conversation to continue. Public JSON request bodies use the camelCase alias `parentConversationId`; follow-up requests append to and return the same conversation." }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineid", "description": "Optional pipeline ID to scope the conversation to" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Projectid", "description": "Optional project ID to scope the conversation to" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "Optional model to use for the conversation" }, "reasoning": { "anyOf": [ { "type": "string", "enum": [ "none", "low", "medium", "high", "xhigh", "max" ] }, { "type": "null" } ], "title": "Reasoning", "description": "Optional reasoning effort level" } }, "type": "object", "required": [ "prompt" ], "title": "ApiCreateConversationRequest", "description": "Public request to create and launch a new conversation." } ``` ### Schema ApiCreateConversationResponse ```json { "properties": { "conversationId": { "type": "string", "title": "Conversationid" }, "status": { "type": "string", "title": "Status", "description": "Always `pending`: the run has been accepted, not started", "default": "pending" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineid" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Projectid" }, "conversationUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversationurl" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" }, "streamUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Streamurl" } }, "type": "object", "required": [ "conversationId" ], "title": "ApiCreateConversationResponse", "description": "Public response after launching a new conversation." } ``` ### Schema ApiDashboardSummaryDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "pipelineId": { "type": "string", "title": "Pipelineid" }, "lineageId": { "type": "string", "title": "Lineageid" }, "version": { "type": "integer", "title": "Version" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "status": { "$ref": "#/components/schemas/DashboardStatus" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" }, "previewCellId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previewcellid" }, "previewVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previewversion" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" }, "dashboardUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboardurl" } }, "type": "object", "required": [ "id", "pipelineId", "lineageId", "version", "name", "status", "createdAt", "updatedAt" ], "title": "ApiDashboardSummaryDTO", "description": "Public dashboard summary with UI URLs." } ``` Referenced definitions: [DashboardStatus](#schema-dashboardstatus). ### Schema ApiKeyDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "keyPrefix": { "type": "string", "title": "Keyprefix" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "isActive": { "type": "boolean", "title": "Isactive" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastusedat" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiresat" } }, "type": "object", "required": [ "id", "name", "keyPrefix", "isActive", "createdAt" ], "title": "ApiKeyDTO", "description": "API key metadata (excludes the raw key, which is never stored)." } ``` ### Schema ApiLiveArtifactDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "type": { "type": "string", "title": "Type" }, "schemaDefinition": { "additionalProperties": true, "type": "object", "title": "Schemadefinition" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineid" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" }, "streamUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Streamurl" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "name", "type", "schemaDefinition", "createdAt", "updatedAt" ], "title": "ApiLiveArtifactDTO", "description": "LiveArtifact metadata exposed through the public API." } ``` ### Schema ApiModelDTO ```json { "properties": { "id": { "type": "string", "title": "Id", "description": "The value to pass as `model` when you create a conversation" }, "label": { "type": "string", "title": "Label" }, "reasoningLevels": { "items": { "type": "string" }, "type": "array", "title": "Reasoninglevels", "description": "Values the model accepts as `reasoning`" } }, "type": "object", "required": [ "id", "label", "reasoningLevels" ], "title": "ApiModelDTO", "description": "A model a conversation may run on." } ``` ### Schema ApiModelsResponse ```json { "properties": { "models": { "items": { "$ref": "#/components/schemas/ApiModelDTO" }, "type": "array", "title": "Models" }, "programModelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Programmodelid", "description": "When set, the caller's program runs every conversation on this model, whatever `model` says, and `models` lists only it" } }, "type": "object", "required": [ "models" ], "title": "ApiModelsResponse", "description": "The models available to the caller." } ``` Referenced definitions: [ApiModelDTO](#schema-apimodeldto). ### Schema ApiModuleDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purpose" }, "moduleType": { "type": "string", "title": "Moduletype" }, "status": { "type": "string", "title": "Status" }, "expectedOutputType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expectedoutputtype" }, "parameters": { "additionalProperties": true, "type": "object", "title": "Parameters" }, "defaultTriggerConfig": { "additionalProperties": true, "type": "object", "title": "Defaulttriggerconfig" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineid" }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflowid" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" }, "workflowUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflowurl" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "name", "moduleType", "status", "createdAt", "updatedAt" ], "title": "ApiModuleDTO", "description": "Public module description without executable code or internal fields." } ``` ### Schema ApiModuleNode ```json { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "moduleType": { "type": "string", "title": "Moduletype" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "id", "name", "moduleType", "status" ], "title": "ApiModuleNode", "description": "Public module node for workflow DAG rendering." } ``` ### Schema ApiPipelineArtifactSummary ```json { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "reportPresentation": { "$ref": "#/components/schemas/ReportPresentation" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "type": { "type": "string", "title": "Type" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "isInbox": { "type": "boolean", "title": "Isinbox", "default": false }, "inboxHeld": { "type": "boolean", "title": "Inboxheld", "default": false }, "isRead": { "type": "boolean", "title": "Isread", "default": false }, "moduleRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modulerunid" }, "workflowName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflowname" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineid" }, "pipelineName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelinename" }, "canOpenPipeline": { "type": "boolean", "title": "Canopenpipeline", "default": false }, "tickerPages": { "items": { "$ref": "#/components/schemas/PipelineTickerPageDTO" }, "type": "array", "title": "Tickerpages" }, "reportKind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reportkind" }, "sourceKind": { "anyOf": [ { "type": "string", "enum": [ "pipeline", "task" ] }, { "type": "null" } ], "title": "Sourcekind" }, "sourceConversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourceconversationid" }, "sourceTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcetitle" }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mimetype" }, "fileExtension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fileextension" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "downloadUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Downloadurl" } }, "type": "object", "required": [ "id", "title", "type", "createdAt" ], "title": "ApiPipelineArtifactSummary", "description": "Public artifact summary with download URL." } ``` Referenced definitions: [PipelineTickerPageDTO](#schema-pipelinetickerpagedto), [ReportPresentation](#schema-reportpresentation). ### Schema ApiPipelineDTO ```json { "properties": { "itemStatus": { "$ref": "#/components/schemas/WorkItemStatusDTO" }, "ownerItemStatus": { "$ref": "#/components/schemas/WorkItemStatusDTO" }, "latestTriggerCheck": { "anyOf": [ { "$ref": "#/components/schemas/PipelineTriggerCheckDTO" }, { "type": "null" } ] }, "tickerPages": { "items": { "$ref": "#/components/schemas/PipelineTickerPageDTO" }, "type": "array", "title": "Tickerpages" }, "hasOpenBuild": { "type": "boolean", "title": "Hasopenbuild", "description": "True when the Pipeline has a nonterminal Builder build.", "default": false }, "id": { "type": "string", "title": "Id" }, "orgId": { "type": "string", "title": "Orgid" }, "createdByUserId": { "type": "string", "title": "Createdbyuserid" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Arbitrary string tags for categorization" }, "status": { "$ref": "#/components/schemas/PipelineStatus" }, "ownerConversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ownerconversationid" }, "triggerSchedules": { "items": { "$ref": "#/components/schemas/PipelineTriggerScheduleDTO" }, "type": "array", "title": "Triggerschedules", "description": "Active-revision and paused trigger schedules. Next occurrences are calendar opportunities, not execution guarantees; conditional triggers check their condition at that time." }, "componentPipelineIds": { "items": { "type": "string" }, "type": "array", "title": "Componentpipelineids", "description": "Component pipeline IDs recorded in pipeline metadata" }, "sourcePipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcepipelineid" }, "parentPipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentpipelineid" }, "isSubscribed": { "type": "boolean", "title": "Issubscribed", "default": false }, "lastPushedRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lastpushedrevisionid" }, "lastPushedSourceRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lastpushedsourcerevisionid" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" }, "workflowCount": { "type": "integer", "title": "Workflowcount", "description": "Number of workflows in the pipeline (org-scoped).", "default": 0 }, "artifactCount": { "type": "integer", "title": "Artifactcount", "description": "Artifacts with this pipeline_id (org-scoped).", "default": 0 }, "runCount": { "type": "integer", "title": "Runcount", "description": "Workflow runs under workflows in this pipeline (org-scoped).", "default": 0 }, "lastRanAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastranat", "description": "Most recent workflow-run start time across this pipeline's workflows." }, "lastRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lastrunid", "description": "ID of the pipeline's most recent workflow run, or None if it never ran." }, "lastRunStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lastrunstatus", "description": "Status of the pipeline's most recent workflow run, or None if it never ran." }, "isLive": { "type": "boolean", "title": "Islive", "description": "True when the pipeline has any automatic trigger.", "default": false }, "triggerKinds": { "items": { "type": "string" }, "type": "array", "title": "Triggerkinds", "description": "Distinct non-manual trigger kinds driving this pipeline (e.g. ['time', 'data'])." }, "triggerSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Triggersummary", "description": "Short human-readable cadence label for the pipeline's automatic triggers (e.g. 'Scheduled at 09:30', 'Every 30 min, and Web monitor (hourly)'). None when not live." }, "triggersPaused": { "type": "boolean", "title": "Triggerspaused", "description": "True when the pipeline has automatic triggers that are configured but paused (their workflow is paused, or the trigger itself is paused, so they don't fire). Mutually exclusive with is_live; lets the UI show a distinct 'Paused' state instead of the pipeline silently dropping out of 'Live'.", "default": false }, "pausedBy": { "anyOf": [ { "type": "string", "enum": [ "user", "staff", "agent", "system", "unknown" ] }, { "type": "null" } ], "title": "Pausedby", "description": "Recorded pause actor kind while triggers_paused; unknown for legacy or mixed actors." }, "pausedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Pausedat", "description": "When this pipeline pause was recorded, while triggers_paused. None for a pause with no user record (repair, first build, failure circuit)." }, "automaticFailureCircuits": { "items": { "$ref": "#/components/schemas/AutomaticTriggerFailureCircuitDTO" }, "type": "array", "title": "Automaticfailurecircuits", "description": "Unresolved automatic-trigger systematic failure circuits for this pipeline." }, "automaticRepairAttempts": { "items": { "$ref": "#/components/schemas/SystematicCodeRepairAttemptDTO" }, "type": "array", "title": "Automaticrepairattempts", "description": "Typed automatic-repair lifecycle records for this Pipeline's contained failures." }, "hasAgent": { "type": "boolean", "title": "Hasagent", "description": "True when the pipeline has at least one active/paused analyst (agent) module. Only populated by the list endpoint; defaults to False on single-pipeline fetches.", "default": false }, "projectIds": { "items": { "type": "string" }, "type": "array", "title": "Projectids", "description": "Project memberships (many-to-many) for list surfaces." }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" } }, "type": "object", "required": [ "id", "orgId", "createdByUserId", "name", "status", "createdAt", "updatedAt" ], "title": "ApiPipelineDTO", "description": "Public pipeline representation with UI URL." } ``` Referenced definitions: [AutomaticTriggerFailureCircuitDTO](#schema-automatictriggerfailurecircuitdto), [PipelineStatus](#schema-pipelinestatus), [PipelineTickerPageDTO](#schema-pipelinetickerpagedto), [PipelineTriggerCheckDTO](#schema-pipelinetriggercheckdto), [PipelineTriggerScheduleDTO](#schema-pipelinetriggerscheduledto), [SystematicCodeRepairAttemptDTO](#schema-systematiccoderepairattemptdto), [WorkItemStatusDTO](#schema-workitemstatusdto). ### Schema ApiPipelineModuleEdge ```json { "properties": { "sourceModuleId": { "type": "string", "title": "Sourcemoduleid" }, "targetModuleId": { "type": "string", "title": "Targetmoduleid" }, "kind": { "type": "string", "title": "Kind", "default": "dependency" }, "passResults": { "type": "boolean", "title": "Passresults", "default": true } }, "type": "object", "required": [ "sourceModuleId", "targetModuleId" ], "title": "ApiPipelineModuleEdge", "description": "Public pipeline graph edge." } ``` ### Schema ApiPipelineRunOutputDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "workflowId": { "type": "string", "title": "Workflowid" }, "pipelineId": { "type": "string", "title": "Pipelineid" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "checkSummary": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowRunCheckSummary" }, { "type": "null" } ] }, "runUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runurl" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" }, "summaryStatus": { "type": "string", "enum": [ "ready", "pending", "unavailable" ], "title": "Summarystatus", "description": "`ready`: the summary is final. `pending`: read again later for the summary, even when the status is final. `unavailable`: this run has no summary; use its artifacts." }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl", "description": "Link to the Pipeline in the Mana app." }, "runPageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runpageurl", "description": "Link to this run in the Mana app." }, "artifacts": { "items": { "$ref": "#/components/schemas/ApiArtifactDTO" }, "type": "array", "title": "Artifacts", "description": "At most 20 of the run's artifacts. List all of them with `GET /workflow-runs/{id}/artifacts`." }, "dashboards": { "items": { "$ref": "#/components/schemas/ApiDashboardSummaryDTO" }, "type": "array", "title": "Dashboards", "description": "The Pipeline's dashboards, each at its latest version." } }, "type": "object", "required": [ "id", "workflowId", "pipelineId", "status", "createdAt", "updatedAt", "summaryStatus" ], "title": "ApiPipelineRunOutputDTO", "description": "One run of a Pipeline with its outputs: the summary, the run's artifacts and the Pipeline's dashboards." } ``` Referenced definitions: [ApiArtifactDTO](#schema-apiartifactdto), [ApiDashboardSummaryDTO](#schema-apidashboardsummarydto), [WorkflowRunCheckSummary](#schema-workflowrunchecksummary). ### Schema ApiPipelineRunRequest ```json { "properties": { "file": { "anyOf": [ { "$ref": "#/components/schemas/PipelineFileInput" }, { "type": "null" } ], "description": "For a Pipeline that starts from a file: the document to run it on. Only its file trigger runs. Omit for any other Pipeline." } }, "type": "object", "title": "ApiPipelineRunRequest", "description": "Optional input for running a whole Pipeline once." } ``` Referenced definitions: [PipelineFileInput](#schema-pipelinefileinput). ### Schema ApiPipelineRunResponse ```json { "properties": { "workflowRunIds": { "items": { "type": "string" }, "type": "array", "title": "Workflowrunids", "description": "Started Workflow runs; follow each with GET /workflow-runs/{id}" }, "startedWorkflowIds": { "items": { "type": "string" }, "type": "array", "title": "Startedworkflowids" }, "runUrls": { "items": { "type": "string" }, "type": "array", "title": "Runurls", "description": "The API URL of each started run, in workflowRunIds order" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "workflowRunIds", "startedWorkflowIds", "runUrls", "message" ], "title": "ApiPipelineRunResponse", "description": "Public result of running a whole Pipeline once." } ``` ### Schema ApiPipelineTriggerStateResponse ```json { "properties": { "triggersPaused": { "type": "boolean", "title": "Triggerspaused", "description": "Whether the Pipeline's automatic triggers are now paused" }, "updatedWorkflowIds": { "items": { "type": "string" }, "type": "array", "title": "Updatedworkflowids", "description": "Workflows whose triggers this request changed" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "triggersPaused", "updatedWorkflowIds", "message" ], "title": "ApiPipelineTriggerStateResponse", "description": "Public result of pausing or resuming a Pipeline's automatic triggers." } ``` ### Schema ApiProjectDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "status": { "type": "string", "title": "Status", "description": "`active` or `archived`" }, "pipelineCount": { "type": "integer", "title": "Pipelinecount" }, "conversationCount": { "type": "integer", "title": "Conversationcount" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "name", "status", "pipelineCount", "conversationCount", "createdAt", "updatedAt" ], "title": "ApiProjectDTO", "description": "A Project of the caller's, for filing conversations with `projectId`." } ``` ### Schema ApiSpecReviewRequest ```json { "properties": { "formId": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Formid" }, "decision": { "type": "string", "enum": [ "accept", "feedback" ], "title": "Decision" }, "feedback": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Feedback" } }, "type": "object", "required": [ "formId", "decision" ], "title": "ApiSpecReviewRequest", "description": "Approve a presented Pipeline spec or request changes in words." } ``` ### Schema ApiUpdateConversationRequest ```json { "properties": { "title": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Title", "description": "The conversation's new title" } }, "type": "object", "required": [ "title" ], "title": "ApiUpdateConversationRequest", "description": "Public request to rename a conversation." } ``` ### Schema ApiUploadArtifactResponse ```json { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mimetype" }, "sizeBytes": { "type": "integer", "title": "Sizebytes" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineid" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" }, "downloadUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Downloadurl" } }, "type": "object", "required": [ "id", "title", "sizeBytes", "createdAt" ], "title": "ApiUploadArtifactResponse", "description": "Public response after uploading a file as an artifact." } ``` ### Schema ApiWorkflowDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "status": { "type": "string", "title": "Status" }, "pipelineId": { "type": "string", "title": "Pipelineid" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" }, "workflowUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflowurl" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" }, "entryPointModuleIds": { "items": { "type": "string" }, "type": "array", "title": "Entrypointmoduleids" } }, "type": "object", "required": [ "id", "name", "status", "pipelineId", "createdAt", "updatedAt" ], "title": "ApiWorkflowDTO", "description": "Public workflow detail." } ``` ### Schema ApiWorkflowModulesResponse ```json { "properties": { "workflowId": { "type": "string", "title": "Workflowid" }, "modules": { "items": { "$ref": "#/components/schemas/ApiModuleNode" }, "type": "array", "title": "Modules" }, "edges": { "items": { "$ref": "#/components/schemas/ApiPipelineModuleEdge" }, "type": "array", "title": "Edges" } }, "type": "object", "required": [ "workflowId" ], "title": "ApiWorkflowModulesResponse", "description": "Workflow modules plus graph edges." } ``` Referenced definitions: [ApiModuleNode](#schema-apimodulenode), [ApiPipelineModuleEdge](#schema-apipipelinemoduleedge). ### Schema ApiWorkflowRunDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "workflowId": { "type": "string", "title": "Workflowid" }, "pipelineId": { "type": "string", "title": "Pipelineid" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "checkSummary": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowRunCheckSummary" }, { "type": "null" } ] }, "runUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runurl" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "workflowId", "pipelineId", "status", "createdAt", "updatedAt" ], "title": "ApiWorkflowRunDTO", "description": "Public workflow run detail." } ``` Referenced definitions: [WorkflowRunCheckSummary](#schema-workflowrunchecksummary). ### Schema ApiWorkflowRunRequest ```json { "properties": { "entryPoint": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Entrypoint", "description": "Logical ID of the workflow trigger to start from. Omit to retain the default run behavior." } }, "type": "object", "title": "ApiWorkflowRunRequest", "description": "Optional selection for a manual workflow run." } ``` ### Schema ApiWorkflowRunResponse ```json { "properties": { "workflowRunId": { "type": "string", "title": "Workflowrunid" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "runUrl": { "type": "string", "title": "Runurl" }, "streamUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Streamurl" } }, "type": "object", "required": [ "workflowRunId", "status", "runUrl" ], "title": "ApiWorkflowRunResponse", "description": "Response returned after a manual workflow run is started." } ``` ### Schema ApiWorkflowRunSummary ```json { "properties": { "id": { "type": "string", "title": "Id" }, "workflowId": { "type": "string", "title": "Workflowid" }, "pipelineId": { "type": "string", "title": "Pipelineid" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "checkSummary": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowRunCheckSummary" }, { "type": "null" } ] }, "runUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runurl" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "workflowId", "pipelineId", "status", "createdAt", "updatedAt" ], "title": "ApiWorkflowRunSummary", "description": "Public workflow run summary." } ``` Referenced definitions: [WorkflowRunCheckSummary](#schema-workflowrunchecksummary). ### Schema ApiWorkflowSummary ```json { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "status": { "type": "string", "title": "Status" }, "pipelineId": { "type": "string", "title": "Pipelineid" }, "pipelineUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipelineurl" }, "workflowUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflowurl" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "name", "status", "pipelineId", "createdAt", "updatedAt" ], "title": "ApiWorkflowSummary", "description": "Public latest-version workflow summary." } ``` ### Schema AppliedDefinition ```json { "properties": { "classMatch": { "anyOf": [ { "$ref": "#/components/schemas/SectorPhraseMatch" }, { "type": "null" } ] }, "rank": { "$ref": "#/components/schemas/RankDefinition" }, "listing": { "$ref": "#/components/schemas/ListingFilters" }, "security": { "$ref": "#/components/schemas/SecuritySelection" }, "shareClass": { "$ref": "#/components/schemas/ShareClassHandling" }, "asOf": { "$ref": "#/components/schemas/AsOf" } }, "type": "object", "required": [ "classMatch", "rank", "listing", "security", "shareClass", "asOf" ], "title": "AppliedDefinition", "description": "Everything that decided membership, as the helper applied it.\n\nAttributes:\n class_match: How the sector phrase resolved; None without a phrase.\n rank: The ordering and the cut.\n listing: Venue, domicile and market-cap filters.\n security: The security types kept.\n share_class: How an issuer's lines were merged.\n as_of: The data dates. Not part of `definition_hash`." } ``` Referenced definitions: [AsOf](#schema-asof), [ListingFilters](#schema-listingfilters), [RankDefinition](#schema-rankdefinition), [SectorPhraseMatch](#schema-sectorphrasematch), [SecuritySelection](#schema-securityselection), [ShareClassHandling](#schema-shareclasshandling). ### Schema ArtifactCategory ```json { "type": "string", "enum": [ "terminal", "intermediate", "report" ], "title": "ArtifactCategory" } ``` ### Schema ArtifactSourceType ```json { "type": "string", "enum": [ "user_upload", "agent", "module", "system" ], "title": "ArtifactSourceType" } ``` ### Schema ArtifactStatus ```json { "type": "string", "enum": [ "pending", "generated", "validated", "error" ], "title": "ArtifactStatus" } ``` ### Schema ArtifactType ```json { "type": "string", "enum": [ "structured_data", "text", "json", "csv", "report", "chart", "table", "list", "data", "link", "document", "image", "code", "signal", "other" ], "title": "ArtifactType" } ``` ### Schema AsOf ```json { "properties": { "runDate": { "type": "string", "format": "date", "title": "Rundate" }, "marketCapDateFirst": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Marketcapdatefirst" }, "marketCapDateLast": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Marketcapdatelast" }, "pointInTime": { "type": "boolean", "const": false, "title": "Pointintime", "default": false } }, "type": "object", "required": [ "runDate", "marketCapDateFirst", "marketCapDateLast" ], "title": "AsOf", "description": "When the data behind the universe is from.\n\nAttributes:\n run_date: The date the query ran (UTC).\n market_cap_date_first: The oldest market-cap date among the members.\n market_cap_date_last: The newest market-cap date among the members.\n point_in_time: Always False: the query reads the latest fundamentals and FX\n with no date bound, so a backdated run still uses today's market caps." } ``` ### Schema AutomaticTriggerCircuitResolutionReason ```json { "type": "string", "enum": [ "connection_reconnected", "fingerprint_changed", "successful_module_run", "owner_resumed", "canary_succeeded" ], "title": "AutomaticTriggerCircuitResolutionReason", "description": "Typed reasons a failure sequence or open circuit stopped applying." } ``` ### Schema AutomaticTriggerFailureCircuitDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "pipelineId": { "type": "string", "title": "Pipelineid" }, "pipelineRevisionId": { "type": "string", "title": "Pipelinerevisionid" }, "moduleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Moduleid" }, "fingerprint": { "type": "string", "title": "Fingerprint" }, "failureClass": { "type": "string", "title": "Failureclass" }, "consecutiveCount": { "type": "integer", "title": "Consecutivecount" }, "firstSeenAt": { "type": "string", "format": "date-time", "title": "Firstseenat" }, "lastSeenAt": { "type": "string", "format": "date-time", "title": "Lastseenat" }, "trippedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Trippedat" }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Resolvedat" }, "resolutionReason": { "anyOf": [ { "$ref": "#/components/schemas/AutomaticTriggerCircuitResolutionReason" }, { "type": "null" } ] }, "representativeWorkflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Representativeworkflowrunid" }, "representativeModuleRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Representativemodulerunid" }, "state": { "$ref": "#/components/schemas/AutomaticTriggerFailureCircuitState" } }, "type": "object", "required": [ "id", "pipelineId", "pipelineRevisionId", "fingerprint", "failureClass", "consecutiveCount", "firstSeenAt", "lastSeenAt", "state" ], "title": "AutomaticTriggerFailureCircuitDTO", "description": "Privacy-safe circuit state exposed to an organization owner." } ``` Referenced definitions: [AutomaticTriggerCircuitResolutionReason](#schema-automatictriggercircuitresolutionreason), [AutomaticTriggerFailureCircuitState](#schema-automatictriggerfailurecircuitstate). ### Schema AutomaticTriggerFailureCircuitState ```json { "type": "string", "enum": [ "armed", "open", "resolved" ], "title": "AutomaticTriggerFailureCircuitState", "description": "Lifecycle of one automatic-trigger failure fingerprint sequence." } ``` ### Schema Body_upload_artifact ```json { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "pipeline_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pipeline Id" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_artifact" } ``` ### Schema CheckedSource ```json { "type": "string", "enum": [ "sec_filings", "news", "press_releases", "earnings_transcripts", "web_news", "documents", "edgar_filings", "edgar_filing_documents", "web_pages", "insider_trades", "institutional_holdings_13f", "podcasts", "x_posts", "warehouse", "fda", "clinical_trials", "direct_http" ], "title": "CheckedSource", "description": "A data source whose reads are recorded on a WorkflowRun.\n\nDocuments-corpus sources use the corpus's own ``source_type`` values so a\n``get_documents`` row is attributed to the feed it came from." } ``` ### Schema ConversationStructuredOutputResponse ```json { "properties": { "structuredOutput": { "title": "Structuredoutput" }, "structuredOutputError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Structuredoutputerror" } }, "type": "object", "required": [ "structuredOutput" ], "title": "ConversationStructuredOutputResponse", "description": "Structured output extracted from a conversation's final report." } ``` ### Schema CreateApiKeyRequest ```json { "properties": { "name": { "type": "string", "title": "Name", "description": "Human-readable label for this key (e.g. 'Clay Integration')" } }, "type": "object", "required": [ "name" ], "title": "CreateApiKeyRequest", "description": "Request to create a new API key." } ``` ### Schema CreateApiKeyResponse ```json { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "key": { "type": "string", "title": "Key", "description": "The raw API key — store it securely, it cannot be retrieved again" }, "keyPrefix": { "type": "string", "title": "Keyprefix" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiresat" } }, "type": "object", "required": [ "id", "name", "key", "keyPrefix", "createdAt" ], "title": "CreateApiKeyResponse", "description": "Response after creating an API key. Contains the raw key (shown only once)." } ``` ### Schema CreatePipelineDTO ```json { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Pipeline name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Optional pipeline description" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Arbitrary string tags for categorization" }, "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, { "type": "null" } ], "title": "Id", "description": "Optional client-generated pipeline ID (must be a valid lowercase UUID v4)" } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "CreatePipelineDTO", "description": "Request body for creating a new pipeline." } ``` ### Schema DashboardStatus ```json { "type": "string", "enum": [ "active", "archived" ], "title": "DashboardStatus" } ``` ### Schema ExcludedExample ```json { "properties": { "symbol": { "type": "string", "title": "Symbol" }, "name": { "type": "string", "title": "Name" }, "marketCapUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Marketcapusd" }, "detail": { "type": "string", "title": "Detail" } }, "type": "object", "required": [ "symbol", "name", "marketCapUsd", "detail" ], "title": "ExcludedExample", "description": "One issuer left out (or flagged) under a reason.\n\nAttributes:\n symbol: The line that would have represented the issuer.\n name: The listing name.\n market_cap_usd: The line's latest USD market cap, when known.\n detail: Why this line, in the reason's terms: its venue, domicile, industry,\n security-type rule, rank position, or the returned line (\"kept GOOGL\")." } ``` ### Schema ExclusionCount ```json { "properties": { "reason": { "type": "string", "enum": [ "venue", "domicile", "class_neighbour", "common_stock", "adr", "etf", "mutual_fund", "closed_end_fund", "preferred", "debt", "warrant", "unit", "right", "other", "duplicate_line", "no_rank_value", "market_cap_band", "below_rank_cutoff", "code_filter" ], "title": "Reason" }, "count": { "type": "integer", "minimum": 0.0, "title": "Count" }, "examples": { "items": { "$ref": "#/components/schemas/ExcludedExample" }, "type": "array", "maxItems": 5, "title": "Examples" }, "label": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Label" } }, "type": "object", "required": [ "reason", "count" ], "title": "ExclusionCount", "description": "How many issuers one reason excluded, with up to five examples.\n\nAttributes:\n reason: Why they were excluded.\n count: Issuers excluded for this reason alone.\n examples: The most telling issuers, in the reason's example order.\n label: The caller's description of a `code_filter`; None for helper reasons." } ``` Referenced definitions: [ExcludedExample](#schema-excludedexample). ### Schema HTTPValidationError ```json { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ``` Referenced definitions: [ValidationError](#schema-validationerror). ### Schema KeptFlagCount ```json { "properties": { "flag": { "type": "string", "enum": [ "adr", "non_us_domicile", "no_market_cap" ], "title": "Flag" }, "count": { "type": "integer", "minimum": 0.0, "title": "Count" }, "examples": { "items": { "$ref": "#/components/schemas/ExcludedExample" }, "type": "array", "maxItems": 5, "title": "Examples" } }, "type": "object", "required": [ "flag", "count" ], "title": "KeptFlagCount", "description": "How many returned members carry one flag, with up to five of the largest." } ``` Referenced definitions: [ExcludedExample](#schema-excludedexample). ### Schema ListingFilters ```json { "properties": { "activeOnly": { "type": "boolean", "title": "Activeonly" }, "venues": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Venues" }, "excludeVenues": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Excludevenues" }, "domiciles": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Domiciles" }, "venuesDefaulted": { "type": "boolean", "title": "Venuesdefaulted" }, "domicilesDefaulted": { "type": "boolean", "title": "Domicilesdefaulted" }, "marketCap": { "$ref": "#/components/schemas/MarketCapBand" } }, "type": "object", "required": [ "activeOnly", "venues", "excludeVenues", "domiciles", "venuesDefaulted", "domicilesDefaulted", "marketCap" ], "title": "ListingFilters", "description": "Where listings trade, where issuers are domiciled, and the market-cap band.\n\nAttributes:\n active_only: Only currently listed securities were considered.\n venues: Venues a listing had to trade on; None is no venue restriction.\n exclude_venues: Venues that excluded a listing; None is none.\n domiciles: Issuer country codes kept; None keeps every domicile.\n venues_defaulted: The caller did not choose venues, so the helper's legacy\n default (no venue filter) applied.\n domiciles_defaulted: The caller did not choose a domicile, so the helper's\n legacy default applied: US-domiciled for the list helper, every country\n for the top-N helper.\n market_cap: The USD market-cap band." } ``` Referenced definitions: [MarketCapBand](#schema-marketcapband). ### Schema LiveArtifactDataDTO ```json { "properties": { "liveArtifactId": { "type": "string", "title": "Liveartifactid" }, "columns": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Columns" }, "rows": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Rows" }, "returnedRows": { "type": "integer", "title": "Returnedrows" }, "totalRows": { "type": "integer", "title": "Totalrows" }, "offset": { "type": "integer", "title": "Offset" }, "truncated": { "type": "boolean", "title": "Truncated" }, "storageBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Storagebytes", "description": "Compressed on-disk size of the authoritative backing store in bytes, when available." } }, "type": "object", "required": [ "liveArtifactId", "columns", "rows", "returnedRows", "totalRows", "offset", "truncated" ], "title": "LiveArtifactDataDTO", "description": "DTO for row data downloaded from a LiveArtifact's authoritative store." } ``` ### Schema LiveArtifactWrite ```json { "properties": { "stableId": { "type": "string", "title": "Stableid" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "rowsWritten": { "type": "integer", "minimum": 0.0, "title": "Rowswritten", "default": 0 } }, "type": "object", "required": [ "stableId" ], "title": "LiveArtifactWrite", "description": "Rows one WorkflowRun wrote to one LiveArtifact." } ``` ### Schema MarketCapBand ```json { "properties": { "minUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Minusd" }, "maxUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Maxusd" }, "comparisonOperator": { "anyOf": [ { "type": "string", "enum": [ ">", ">=", "<", "<=" ] }, { "type": "null" } ], "title": "Comparisonoperator" }, "comparisonValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Comparisonvalue" } }, "type": "object", "title": "MarketCapBand", "description": "The USD market-cap band applied after the issuer dedup; all None means no band." } ``` ### Schema NameCoverage ```json { "properties": { "overflowed": { "type": "boolean", "title": "Overflowed", "default": false }, "askedCount": { "type": "integer", "title": "Askedcount", "description": "Distinct names the run's reads of this source asked for.", "readOnly": true }, "withItemsCount": { "type": "integer", "title": "Withitemscount", "description": "Asked names that returned at least one item.", "readOnly": true } }, "type": "object", "required": [ "askedCount", "withItemsCount" ], "title": "NameCoverage", "description": "Which of the names a source was asked for returned at least one item during one WorkflowRun.\n\nA name is a company (a ticker, in ``normalize_share_class_symbol`` form) or a\nkeyword (casefolded). Reads merge by name (``merge_name_coverage``), so a\nname read twice, by two calls or two nodes, counts once.\n\nThe two name lists are internal: the headline check and the report node's\nprompt read them, and the persisted record keeps them\n(``dump_check_summary``), but every other serialization, the run API DTOs\nincluded, carries only the counts. Shared pipelines' runs are visible to\nreaders other than the owner, and no reader uses the lists." } ``` ### Schema PipelineFileInput ```json { "properties": { "fileArtifactId": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Fileartifactid", "description": "A document Artifact a file trigger delivered, or the Artifact of a Knowledge Base upload." }, "knowledgeBaseDocumentId": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Knowledgebasedocumentid", "description": "A Knowledge Base document id from Knowledge Base search. Only uploaded documents qualify." }, "triggerLogicalId": { "anyOf": [ { "type": "string", "maxLength": 256, "minLength": 1 }, { "type": "null" } ], "title": "Triggerlogicalid", "description": "The file trigger that receives the document. Needed only when the Pipeline has several." } }, "additionalProperties": false, "type": "object", "title": "PipelineFileInput", "description": "The document a manual run delivers to a file-started Pipeline's file trigger.\n\nExactly one of ``file_artifact_id`` and ``knowledge_base_document_id``.\n``pipeline_file_input.resolve_file_input_payload`` turns it into the\ntrigger's row." } ``` ### Schema PipelineStatus ```json { "type": "string", "enum": [ "active", "archived" ], "title": "PipelineStatus" } ``` ### Schema PipelineSummaryDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "ownerConversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ownerconversationid", "description": "Owning Builder conversation for the selected oldest unarchived Pipeline; null for other rows." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updatedat" }, "parentPipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentpipelineid" }, "projectIds": { "items": { "type": "string" }, "type": "array", "title": "Projectids" } }, "type": "object", "required": [ "id", "name" ], "title": "PipelineSummaryDTO", "description": "Lightweight pipeline representation for quick listing (e.g. sidebar nav).\n\nNote: ``updated_at`` is a computed last-activity timestamp (GREATEST of\npipeline, conversation, and module-run timestamps) — not the raw DB column.\n\n``description`` is included so the pipeline page header (title + subtitle)\ncan paint instantly from the sidebar's localStorage-backed summary cache,\navoiding a network round-trip on navigation.\n\n``parent_pipeline_id`` is included so listing surfaces (sidebar dropdown,\nconversation grouping, etc.) can hide subpipelines, which are surfaced in\nthe context of their parent rather than as standalone top-level pipelines." } ``` ### Schema PipelineTickerPageDTO ```json { "properties": { "pageId": { "type": "string", "title": "Pageid" }, "symbol": { "type": "string", "title": "Symbol" } }, "type": "object", "required": [ "pageId", "symbol" ], "title": "PipelineTickerPageDTO", "description": "An owned, active Ticker page associated with a listed Pipeline." } ``` ### Schema PipelineTriggerCheckDTO ```json { "properties": { "triggerId": { "type": "string", "title": "Triggerid" }, "checkedAt": { "type": "string", "format": "date-time", "title": "Checkedat" }, "outcome": { "type": "string", "enum": [ "no_change", "matched", "failed", "unknown" ], "title": "Outcome" }, "failureReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failurereason" } }, "type": "object", "required": [ "triggerId", "checkedAt", "outcome" ], "title": "PipelineTriggerCheckDTO", "description": "A source check, independent of whether it started a Pipeline run." } ``` ### Schema PipelineTriggerScheduleDTO ```json { "properties": { "triggerId": { "type": "string", "title": "Triggerid" }, "triggerLogicalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Triggerlogicalid" }, "webMode": { "anyOf": [ { "$ref": "#/components/schemas/WebTriggerMode" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourceurl" }, "triggerKind": { "type": "string", "enum": [ "time", "code", "web", "file", "live_artifact", "knowledge_base", "dataset", "result" ], "title": "Triggerkind" }, "summary": { "type": "string", "title": "Summary" }, "state": { "type": "string", "enum": [ "scheduled", "conditional", "event", "paused", "invalid" ], "title": "State" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" }, "hasCondition": { "type": "boolean", "title": "Hascondition", "default": false }, "scheduleType": { "anyOf": [ { "type": "string", "enum": [ "cron", "times", "invalid" ] }, { "type": "null" } ], "title": "Scheduletype" }, "cronExpression": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cronexpression" }, "times": { "items": { "type": "string" }, "type": "array", "title": "Times" }, "issue": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Issue" }, "checkIntervalSeconds": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Checkintervalseconds" }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastcheckedat" }, "lastCheckOutcome": { "anyOf": [ { "type": "string", "enum": [ "no_change", "matched", "failed", "unknown" ] }, { "type": "null" } ], "title": "Lastcheckoutcome" }, "nextOccurrenceAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Nextoccurrenceat", "description": "Compute at serialization time so cached configurations do not freeze time.\n\nCached DTOs reconstruct this property from the non-executable schedule\nfields. A condition check is an opportunity, never a promised execution.", "readOnly": true } }, "type": "object", "required": [ "triggerId", "triggerKind", "summary", "state", "nextOccurrenceAt" ], "title": "PipelineTriggerScheduleDTO", "description": "One active-revision or paused trigger and its next calendar opportunity." } ``` Referenced definitions: [WebTriggerMode](#schema-webtriggermode). ### Schema QuestionAnswerItem ```json { "properties": { "questionIndex": { "type": "integer", "title": "Questionindex", "description": "Index of the question this answer is for (0-based)", "default": 0 }, "selectedOptions": { "items": { "type": "string" }, "type": "array", "title": "Selectedoptions" }, "textAnswer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Textanswer", "description": "Free-form text answer" } }, "type": "object", "title": "QuestionAnswerItem", "description": "A single answer to a question in an AskUserQuestion form." } ``` ### Schema QuestionResponseRequest ```json { "properties": { "formId": { "type": "string", "title": "Formid", "description": "The `formId` value from the question event" }, "answers": { "items": { "$ref": "#/components/schemas/QuestionAnswerItem" }, "type": "array", "title": "Answers", "description": "Answers to each question" } }, "type": "object", "required": [ "formId", "answers" ], "title": "QuestionResponseRequest", "description": "Request to respond to a pending agent question." } ``` Referenced definitions: [QuestionAnswerItem](#schema-questionansweritem). ### Schema RankDefinition ```json { "properties": { "metric": { "type": "string", "enum": [ "market_cap", "pe_ratio" ], "title": "Metric" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "title": "Direction" }, "n": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "N" } }, "type": "object", "required": [ "metric", "direction", "n" ], "title": "RankDefinition", "description": "The ordering a helper applied and where it cut.\n\nAttributes:\n metric: The ranking metric. The list helper orders by USD market cap.\n direction: \"desc\" keeps the largest values.\n n: The row cap; None returns every qualifying company." } ``` ### Schema ReportPresentation ```json { "properties": { "kinds": { "items": { "type": "string", "enum": [ "requested_once", "historical_example" ] }, "type": "array", "title": "Kinds" }, "source_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Source Date" } }, "additionalProperties": false, "type": "object", "title": "ReportPresentation", "description": "Labels beside a report's delivery date, separate from its finding title." } ``` ### Schema SectorPhraseMatch ```json { "properties": { "phrase": { "type": "string", "title": "Phrase" }, "method": { "type": "string", "enum": [ "fmp_sector", "model", "model_fallback", "model_empty" ], "title": "Method" }, "sectors": { "items": { "type": "string" }, "type": "array", "title": "Sectors", "default": [] }, "industries": { "items": { "type": "string" }, "type": "array", "title": "Industries", "default": [] } }, "type": "object", "required": [ "phrase", "method" ], "title": "SectorPhraseMatch", "description": "How a universe helper resolved its `sector_search_phrase` into a listing filter.\n\nAttributes:\n phrase: The phrase as the helper received it, with list phrases joined by \", \".\n method: \"fmp_sector\" when every part named an FMP sector exactly and the helper\n filters `equity_metadata.sector`; \"model\" when the industry matcher chose\n industries and the helper filters `equity_metadata.industry`;\n \"model_fallback\" when the matcher's answer is not a known industry (it\n answers with the phrase itself after an error), so the industry filter\n uses that answer; \"model_empty\" when the matcher chose no industries, so\n no sector or industry filter applies and the whole market passes.\n sectors: The FMP sectors filtered on; empty except on the sector path.\n industries: The industries the matcher answered with; empty on the sector path." } ``` ### Schema SecuritySelection ```json { "properties": { "universe": { "type": "string", "enum": [ "operating_equity", "all" ], "title": "Universe" }, "etfs": { "type": "string", "enum": [ "yes", "no", "only etfs" ], "title": "Etfs" }, "tickers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tickers" } }, "type": "object", "required": [ "universe", "etfs", "tickers" ], "title": "SecuritySelection", "description": "Which security types formed the universe.\n\nAttributes:\n universe: \"operating_equity\" (common stock and ADRs) or \"all\". Explicit tickers\n force \"all\".\n etfs: The ETF choice applied on top of `universe`.\n tickers: The exact symbols requested, when the caller named them." } ``` ### Schema ShareClassHandling ```json { "properties": { "issuerKey": { "type": "string", "enum": [ "listing_name", "symbol" ], "title": "Issuerkey" }, "tieBreak": { "items": { "type": "string" }, "type": "array", "title": "Tiebreak", "default": [ "operating_equity_type", "undotted_symbol", "known_market_cap", "dollar_volume", "market_cap", "symbol" ] } }, "type": "object", "required": [ "issuerKey" ], "title": "ShareClassHandling", "description": "The rule behind every merge of an issuer's lines.\n\nAttributes:\n issuer_key: \"listing_name\" folds the listing name's punctuation and case into\n one issuer; \"symbol\" keeps every requested ticker as its own issuer.\n tie_break: The dedup's ordering of an issuer's lines, first key first." } ``` ### Schema SourceCheck ```json { "properties": { "source": { "$ref": "#/components/schemas/CheckedSource" }, "calls": { "type": "integer", "minimum": 0.0, "title": "Calls", "default": 0 }, "failedCalls": { "type": "integer", "minimum": 0.0, "title": "Failedcalls", "default": 0 }, "items": { "type": "integer", "minimum": 0.0, "title": "Items", "default": 0 }, "newestItemAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Newestitemat" }, "newestItemPrecision": { "anyOf": [ { "type": "string", "enum": [ "date", "datetime" ] }, { "type": "null" } ], "title": "Newestitemprecision" }, "currentWindowCalls": { "type": "integer", "minimum": 0.0, "title": "Currentwindowcalls", "default": 0 }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastcheckedat" }, "stale": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Stale" }, "archiveWatermarkCalls": { "type": "integer", "minimum": 0.0, "title": "Archivewatermarkcalls", "default": 0 }, "archiveWatermarkAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Archivewatermarkat" }, "companies": { "anyOf": [ { "$ref": "#/components/schemas/NameCoverage" }, { "type": "null" } ] }, "keywords": { "anyOf": [ { "$ref": "#/components/schemas/NameCoverage" }, { "type": "null" } ] }, "unnamedItemCalls": { "type": "integer", "minimum": 0.0, "title": "Unnameditemcalls", "default": 0 } }, "type": "object", "required": [ "source" ], "title": "SourceCheck", "description": "Aggregated reads of one source during one WorkflowRun." } ``` Referenced definitions: [CheckedSource](#schema-checkedsource), [NameCoverage](#schema-namecoverage). ### Schema SystematicCodeRepairAttemptDTO ```json { "properties": { "id": { "type": "string", "title": "Id" }, "incidentId": { "type": "string", "title": "Incidentid" }, "generation": { "type": "integer", "title": "Generation" }, "route": { "$ref": "#/components/schemas/SystematicCodeRepairRoute" }, "state": { "$ref": "#/components/schemas/SystematicCodeRepairState" }, "invocationHostPipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invocationhostpipelineid" }, "invocationHostWorkflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invocationhostworkflowrunid" }, "sourceWorkflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourceworkflowrunid" }, "sourceModuleRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcemodulerunid" }, "repairConversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repairconversationid" }, "repairModuleRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repairmodulerunid" }, "replacementParameterizedWorkflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replacementparameterizedworkflowid" }, "capabilityVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Capabilityversion" }, "terminalReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Terminalreasoncode" }, "ownerOverrideRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Owneroverriderequestedat" }, "rearmReason": { "anyOf": [ { "$ref": "#/components/schemas/SystematicCodeRepairRearmReason" }, { "type": "null" } ] }, "validationResult": { "anyOf": [ { "$ref": "#/components/schemas/SystematicCodeRepairValidationResult" }, { "type": "null" } ] }, "validationWorkflowRunIds": { "items": { "type": "string" }, "type": "array", "title": "Validationworkflowrunids" }, "activatedOwnerVersionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Activatedownerversionid" } }, "type": "object", "required": [ "id", "incidentId", "generation", "route", "state" ], "title": "SystematicCodeRepairAttemptDTO", "description": "Privacy-safe automatic-repair lifecycle exposed with run and Pipeline status." } ``` Referenced definitions: [SystematicCodeRepairRearmReason](#schema-systematiccoderepairrearmreason), [SystematicCodeRepairRoute](#schema-systematiccoderepairroute), [SystematicCodeRepairState](#schema-systematiccoderepairstate), [SystematicCodeRepairValidationResult](#schema-systematiccoderepairvalidationresult). ### Schema SystematicCodeRepairRearmReason ```json { "type": "string", "enum": [ "new_active_revision", "fingerprint_changed", "owner_override", "capability_upgrade" ], "title": "SystematicCodeRepairRearmReason", "description": "Policy-approved reasons an incident may receive another repair claim." } ``` ### Schema SystematicCodeRepairRoute ```json { "type": "string", "enum": [ "pipeline_builder", "unsupported" ], "title": "SystematicCodeRepairRoute", "description": "Typed repair destination selected from executable ownership." } ``` ### Schema SystematicCodeRepairState ```json { "type": "string", "enum": [ "observed", "circuit_open", "repair_claimed", "repair_launched", "diagnosed_no_change", "patch_applied", "validation_passed", "activated", "failed" ], "title": "SystematicCodeRepairState", "description": "Durable automatic-repair lifecycle." } ``` ### Schema SystematicCodeRepairValidationResult ```json { "type": "string", "enum": [ "passed", "failed" ], "title": "SystematicCodeRepairValidationResult", "description": "Bounded representative validation outcome." } ``` ### Schema UniverseCheck ```json { "properties": { "moduleId": { "type": "string", "title": "Moduleid" }, "callIndex": { "type": "integer", "minimum": 0.0, "title": "Callindex" }, "record": { "$ref": "#/components/schemas/UniverseRecord" } }, "type": "object", "required": [ "moduleId", "callIndex", "record" ], "title": "UniverseCheck", "description": "One universe-helper call a Pipeline node made during a WorkflowRun.\n\nAttributes:\n module_id: The node (module) whose code made the call.\n call_index: The call's position among that node's recorded calls in its latest\n execution, from 0. A re-executed node replaces its earlier calls.\n record: What the call applied, returned and left out." } ``` Referenced definitions: [UniverseRecord](#schema-universerecord). ### Schema UniverseRecord ```json { "properties": { "schemaVersion": { "type": "integer", "const": 1, "title": "Schemaversion", "default": 1 }, "helper": { "type": "string", "enum": [ "get_company_list", "get_top_companies_by_metric" ], "title": "Helper" }, "definition": { "$ref": "#/components/schemas/AppliedDefinition" }, "definitionHash": { "type": "string", "title": "Definitionhash" }, "memberCount": { "type": "integer", "minimum": 0.0, "title": "Membercount" }, "requestedN": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Requestedn" }, "shortfall": { "type": "integer", "minimum": 0.0, "title": "Shortfall" }, "exclusions": { "items": { "$ref": "#/components/schemas/ExclusionCount" }, "type": "array", "title": "Exclusions" }, "keptFlags": { "items": { "$ref": "#/components/schemas/KeptFlagCount" }, "type": "array", "title": "Keptflags" }, "recordedAt": { "type": "string", "format": "date-time", "title": "Recordedat" } }, "type": "object", "required": [ "helper", "definition", "definitionHash", "memberCount", "requestedN", "shortfall", "exclusions", "keptFlags", "recordedAt" ], "title": "UniverseRecord", "description": "What one universe helper call applied, returned and left out.\n\nAttributes:\n schema_version: Bumped when the record's shape changes.\n helper: The helper that produced it.\n definition: The resolved definition.\n definition_hash: A short hash of the definition without its dates, so runs and\n builds can tell \"same definition, different data\" from \"different definition\".\n member_count: Rows returned.\n requested_n: The row cap requested; None without one.\n shortfall: How many fewer rows than `requested_n` came back.\n exclusions: Issuers left out, per reason, largest count first.\n kept_flags: Returned members carrying a flag, per flag, largest count first.\n recorded_at: When the record was built (UTC). A cache hit returns the original." } ``` Referenced definitions: [AppliedDefinition](#schema-applieddefinition), [ExclusionCount](#schema-exclusioncount), [KeptFlagCount](#schema-keptflagcount). ### Schema UpdatePipelineDTO ```json { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New pipeline name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "New pipeline description" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Replace tags list" } }, "type": "object", "title": "UpdatePipelineDTO", "description": "Request body for updating pipeline name or description." } ``` ### Schema ValidationError ```json { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } ``` ### Schema WebTriggerMode ```json { "type": "string", "enum": [ "events", "feed", "page" ], "title": "WebTriggerMode", "description": "What a web trigger watches: a Parallel event-stream query, a feed, or one page." } ``` ### Schema WorkItemStatusDTO ```json { "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "working", "needs_you", "failed", "ready" ] }, { "type": "null" } ], "title": "State" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Readyat" }, "conversationFailed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Conversationfailed" } }, "type": "object", "title": "WorkItemStatusDTO", "description": "One item's current state and the time of its latest usable result." } ``` ### Schema WorkflowRunCheckSummary ```json { "properties": { "version": { "type": "integer", "title": "Version", "default": 1 }, "sources": { "items": { "$ref": "#/components/schemas/SourceCheck" }, "type": "array", "title": "Sources" }, "universes": { "items": { "$ref": "#/components/schemas/UniverseCheck" }, "type": "array", "title": "Universes" }, "liveArtifacts": { "items": { "$ref": "#/components/schemas/LiveArtifactWrite" }, "type": "array", "title": "Liveartifacts" }, "reportsPublished": { "type": "integer", "minimum": 0.0, "title": "Reportspublished", "default": 0 }, "filesDelivered": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Filesdelivered" }, "sealedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Sealedat" }, "sealedStatus": { "anyOf": [ { "type": "string", "enum": [ "completed", "failed", "cancelled" ] }, { "type": "null" } ], "title": "Sealedstatus" } }, "type": "object", "title": "WorkflowRunCheckSummary", "description": "What a WorkflowRun read, what it produced, and whether its sources were current." } ``` Referenced definitions: [LiveArtifactWrite](#schema-liveartifactwrite), [SourceCheck](#schema-sourcecheck), [UniverseCheck](#schema-universecheck).