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 from the OpenAPI document in api-reference/openapi.json.
Base URL
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.
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
- Create a conversation with
POST /api/v1/conversations. - Track it with either
GET /api/v1/conversations/{conversation_id}polling orGET /api/v1/conversations/{conversation_id}/streamserver-sent events. - Retrieve generated files with
GET /api/v1/conversations/{conversation_id}/artifacts. - Download each artifact with
GET /api/v1/artifacts/{artifact_id}/download. - Send a follow-up with
POST /api/v1/conversationsandparentConversationId.
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 for complete Python examples.
Quickstart
Create an API key in the Mana app from Settings -> API, then store it in your shell:
export MANA_API_KEY="mana_xxx"
The examples below use Python and requests.
Health Check
Call health without auth headers:
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
exploratoryfor a research answer from the Exploratory agent. - Send
pipeline-builderto 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
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.
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:
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:
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.
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
- Open the Mana app.
- Go to Settings -> API.
- 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:
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:
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:
{
"prompt": "Compare Apple and Microsoft stock performance over the past 5 years.",
"agentType": "exploratory"
}
Useful request fields:
artifactIds: files uploaded first withPOST /api/v1/artifacts/upload, for the agent to read.responseSchema: a JSON Schema. Read the extracted result fromGET /api/v1/conversations/{conversation_id}/structured-output.modelandreasoning: the model and reasoning effort for the run.GET /api/v1/modelslists the models you can use, each with thereasoningvalues it accepts. Omitmodelto use the agent's own default. If your account is in a program with a set model, every run uses it:programModelIdnames it and it is the only model listed.titleandprojectId: the conversation's title and the project it is filed in.GET /api/v1/projectslists 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 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:
{
"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/pipelineslists the pipelines you created. Read one withGET /api/v1/pipelines/{pipeline_id}. Rename it withPATCH, and archive or restore it withPOST .../archiveandPOST .../unarchive.POST /api/v1/pipelines/{pipeline_id}/runsruns the whole pipeline once, from the entry points of its active version that have work, and returns the startedworkflowRunIds(none when its sources have no new event).POST /api/v1/pipelines/{pipeline_id}/triggers/pauseand.../triggers/resumepause and resume its automatic triggers, as Pause and Resume do in the app.GET /api/v1/pipelines/{pipeline_id}/workflowslists the workflows in the pipeline's active version.POST /api/v1/workflows/{workflow_id}/runsstarts a run; passentryPointto start from a specific trigger. Follow the run withGET /api/v1/workflow-runs/{workflow_run_id}.GET /api/v1/pipelines/{pipeline_id}/live-artifactslists the pipeline's tables. Read rows withGET /api/v1/live-artifacts/{live_artifact_id}/data(limitup to 10,000, paged withoffset).GET /api/v1/live-artifacts/{live_artifact_id}/streamsends Server-Sent Events when the table changes: eachlive_artifactevent carries the table's metadata, such asupdated_atandrow_count, not its rows, so read new rows from/datawhen it arrives.GET /api/v1/pipelines/{pipeline_id}/artifactsandGET /api/v1/pipelines/{pipeline_id}/dashboardslist 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{ "items": { "$ref": "#/components/schemas/ApiKeyDTO" }, "type": "array", "title": "Response List Api Keys" }Definitions: 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:
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):
{
"$ref": "#/components/schemas/CreateApiKeyRequest"
}
Definitions: CreateApiKeyRequest.
Responses:
-
200: Successful Response
Content type:
application/json{ "$ref": "#/components/schemas/CreateApiKeyResponse" }Definitions: CreateApiKeyResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "object", "additionalProperties": { "type": "boolean" }, "title": "Response Revoke Api Key" } -
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| 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{ "$ref": "#/components/schemas/ApiConversationListPage" }Definitions: ApiConversationListPage.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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):
{
"$ref": "#/components/schemas/ApiCreateConversationRequest"
}
Definitions: ApiCreateConversationRequest.
Responses:
-
200: Successful Response
Content type:
application/json{ "$ref": "#/components/schemas/ApiCreateConversationResponse" }Definitions: ApiCreateConversationResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiConversationListItem" }, "title": "Response List Public Pipeline Conversations" }Definitions: ApiConversationListItem.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{} -
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
Request schema (application/json):
{
"$ref": "#/components/schemas/QuestionResponseRequest"
}
Definitions: QuestionResponseRequest.
Responses:
-
200: Successful Response
Content type:
application/json{ "type": "object", "additionalProperties": true, "title": "Response Respond To Question" } -
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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):
{
"$ref": "#/components/schemas/ApiSpecReviewRequest"
}
Definitions: ApiSpecReviewRequest.
Responses:
-
200: Successful Response
Content type:
application/json{ "type": "object", "additionalProperties": true, "title": "Response Review Pipeline Spec" } -
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "object", "additionalProperties": true, "title": "Response Cancel Conversation" } -
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ApiConversationStatusResponse" }Definitions: ApiConversationStatusResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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):
{
"$ref": "#/components/schemas/ApiUpdateConversationRequest"
}
Definitions: ApiUpdateConversationRequest.
Responses:
-
200: Successful Response
Content type:
application/json{ "$ref": "#/components/schemas/ApiConversationStatusResponse" }Definitions: ApiConversationStatusResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ApiConversationStatusResponse" }Definitions: ApiConversationStatusResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ApiConversationStatusResponse" }Definitions: ApiConversationStatusResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ApiConversationWorkStopResponse" }Definitions: ApiConversationWorkStopResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ConversationStructuredOutputResponse" }Definitions: ConversationStructuredOutputResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiConversationListItem" }, "title": "Response List Sub Conversations" }Definitions: ApiConversationListItem.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiConversationHistoryItem" }, "title": "Response Get Conversation Messages" }Definitions: ApiConversationHistoryItem.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| 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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiArtifactDTO" }, "title": "Response Get Conversation Artifacts" }Definitions: ApiArtifactDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| tickerPages | object[] | Definitions: 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. |
| triggerSchedules[].triggerId | string | |
| triggerSchedules[].triggerLogicalId | string | null | |
| triggerSchedules[].webMode | string (events, feed, page) | null | Values: events, feed, page. Definitions: 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. |
| 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. |
| 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. |
| 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. |
| automaticRepairAttempts[].validationResult | string (passed, failed) | null | Values: passed, failed. Definitions: 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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiPipelineDTO" }, "title": "Response List Pipelines" }Definitions: ApiPipelineDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| tickerPages | object[] | Definitions: 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. |
| triggerSchedules[].triggerId | string | |
| triggerSchedules[].triggerLogicalId | string | null | |
| triggerSchedules[].webMode | string (events, feed, page) | null | Values: events, feed, page. Definitions: 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. |
| 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. |
| 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. |
| 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. |
| automaticRepairAttempts[].validationResult | string (passed, failed) | null | Values: passed, failed. Definitions: 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):
{
"$ref": "#/components/schemas/CreatePipelineDTO"
}
Definitions: CreatePipelineDTO.
Responses:
-
200: Successful Response
Content type:
application/json{ "$ref": "#/components/schemas/ApiPipelineDTO" }Definitions: ApiPipelineDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "items": { "$ref": "#/components/schemas/PipelineSummaryDTO" }, "type": "array", "title": "Response List Public Pipelines Summary" }Definitions: 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:
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. |
| tickerPages | object[] | Definitions: 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. |
| triggerSchedules[].triggerId | string | |
| triggerSchedules[].triggerLogicalId | string | null | |
| triggerSchedules[].webMode | string (events, feed, page) | null | Values: events, feed, page. Definitions: 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. |
| 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. |
| 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. |
| 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. |
| automaticRepairAttempts[].validationResult | string (passed, failed) | null | Values: passed, failed. Definitions: 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{ "$ref": "#/components/schemas/ApiPipelineDTO" }Definitions: ApiPipelineDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| tickerPages | object[] | Definitions: 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. |
| triggerSchedules[].triggerId | string | |
| triggerSchedules[].triggerLogicalId | string | null | |
| triggerSchedules[].webMode | string (events, feed, page) | null | Values: events, feed, page. Definitions: 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. |
| 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. |
| 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. |
| 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. |
| automaticRepairAttempts[].validationResult | string (passed, failed) | null | Values: passed, failed. Definitions: 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):
{
"$ref": "#/components/schemas/UpdatePipelineDTO"
}
Definitions: UpdatePipelineDTO.
Responses:
-
200: Successful Response
Content type:
application/json{ "$ref": "#/components/schemas/ApiPipelineDTO" }Definitions: ApiPipelineDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| tickerPages | object[] | Definitions: 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. |
| triggerSchedules[].triggerId | string | |
| triggerSchedules[].triggerLogicalId | string | null | |
| triggerSchedules[].webMode | string (events, feed, page) | null | Values: events, feed, page. Definitions: 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. |
| 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. |
| 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. |
| 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. |
| automaticRepairAttempts[].validationResult | string (passed, failed) | null | Values: passed, failed. Definitions: 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{ "$ref": "#/components/schemas/ApiPipelineDTO" }Definitions: ApiPipelineDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| tickerPages | object[] | Definitions: 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. |
| triggerSchedules[].triggerId | string | |
| triggerSchedules[].triggerLogicalId | string | null | |
| triggerSchedules[].webMode | string (events, feed, page) | null | Values: events, feed, page. Definitions: 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. |
| 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. |
| 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. |
| 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. |
| automaticRepairAttempts[].validationResult | string (passed, failed) | null | Values: passed, failed. Definitions: 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{ "$ref": "#/components/schemas/ApiPipelineDTO" }Definitions: ApiPipelineDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ApiPipelineTriggerStateResponse" }Definitions: ApiPipelineTriggerStateResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ApiPipelineTriggerStateResponse" }Definitions: ApiPipelineTriggerStateResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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):
{
"anyOf": [
{
"$ref": "#/components/schemas/ApiPipelineRunRequest"
},
{
"type": "null"
}
],
"title": "Body"
}
Definitions: ApiPipelineRunRequest.
Responses:
-
200: Successful Response
Content type:
application/json{ "$ref": "#/components/schemas/ApiPipelineRunResponse" }Definitions: ApiPipelineRunResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| 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. |
| 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. |
| 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. |
| 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{ "$ref": "#/components/schemas/ApiPipelineRunOutputDTO" }Definitions: ApiPipelineRunOutputDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| 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. |
| 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. |
| 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. |
| 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{ "$ref": "#/components/schemas/ApiPipelineRunOutputDTO" }Definitions: ApiPipelineRunOutputDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiWorkflowSummary" }, "title": "Response List Public Pipeline Workflows" }Definitions: ApiWorkflowSummary.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| modules[].id | string | |
| modules[].name | string | |
| modules[].description | string | null | |
| modules[].moduleType | string | |
| modules[].status | string | |
| edges | object[] | Definitions: 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{ "$ref": "#/components/schemas/ApiWorkflowModulesResponse" }Definitions: ApiWorkflowModulesResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ApiWorkflowDTO" }Definitions: ApiWorkflowDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| 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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiWorkflowRunSummary" }, "title": "Response List Public Workflow Runs" }Definitions: ApiWorkflowRunSummary.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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):
{
"anyOf": [
{
"$ref": "#/components/schemas/ApiWorkflowRunRequest"
},
{
"type": "null"
}
],
"title": "Request"
}
Definitions: ApiWorkflowRunRequest.
Responses:
-
200: Successful Response
Content type:
application/json{ "$ref": "#/components/schemas/ApiWorkflowRunResponse" }Definitions: ApiWorkflowRunResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| 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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiArtifactDTO" }, "title": "Response Get Public Workflow Run Artifacts" }Definitions: ApiArtifactDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiLiveArtifactDTO" }, "title": "Response Get Public Workflow Run Live Artifacts" }Definitions: ApiLiveArtifactDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| 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{ "$ref": "#/components/schemas/ApiWorkflowRunDTO" }Definitions: ApiWorkflowRunDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ApiModuleDTO" }Definitions: ApiModuleDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| 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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiPipelineArtifactSummary" }, "title": "Response List Public Pipeline Artifacts" }Definitions: ApiPipelineArtifactSummary.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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):
{
"$ref": "#/components/schemas/Body_upload_artifact"
}
Definitions: Body_upload_artifact.
Responses:
-
200: Successful Response
Content type:
application/json{ "$ref": "#/components/schemas/ApiUploadArtifactResponse" }Definitions: ApiUploadArtifactResponse.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "string", "format": "binary" } -
206: The requested single byte range, with Content-Range and Accept-Ranges headers.
Content type:
application/octet-stream{ "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{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiLiveArtifactDTO" }, "title": "Response List Public Pipeline Live Artifacts" }Definitions: ApiLiveArtifactDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiDashboardSummaryDTO" }, "title": "Response List Public Pipeline Dashboards" }Definitions: ApiDashboardSummaryDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiLiveArtifactDTO" }, "title": "Response List Public Live Artifacts" }Definitions: ApiLiveArtifactDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/ApiLiveArtifactDTO" }Definitions: ApiLiveArtifactDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "$ref": "#/components/schemas/LiveArtifactDataDTO" }Definitions: LiveArtifactDataDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{} -
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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{ "type": "array", "items": { "$ref": "#/components/schemas/ApiProjectDTO" }, "title": "Response List Public Projects" }Definitions: ApiProjectDTO.
-
422: Validation error: request parameters or body failed schema validation.
Content type:
application/json{ "$ref": "#/components/schemas/HTTPValidationError" }Definitions: 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:
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. |
| 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{ "$ref": "#/components/schemas/ApiModelsResponse" }Definitions: 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:
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{ "additionalProperties": true, "type": "object", "title": "Response Health Check" }
Example:
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
{
"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, ArtifactSourceType, ArtifactStatus, ArtifactType.
Schema ApiConversationHistoryItem
{
"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
{
"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
{
"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 ApiConversationStatusResponse
{
"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
{
"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
{
"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
{
"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
{
"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 ApiKeyDTO
{
"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
{
"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
{
"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
{
"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 ApiModuleDTO
{
"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
{
"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
{
"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, ReportPresentation.
Schema ApiPipelineDTO
{
"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, PipelineStatus, PipelineTickerPageDTO, PipelineTriggerCheckDTO, PipelineTriggerScheduleDTO, SystematicCodeRepairAttemptDTO, WorkItemStatusDTO.
Schema ApiPipelineModuleEdge
{
"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
{
"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, ApiDashboardSummaryDTO, WorkflowRunCheckSummary.
Schema ApiPipelineRunRequest
{
"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 ApiPipelineRunResponse
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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, ApiPipelineModuleEdge.
Schema ApiWorkflowRunDTO
{
"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 ApiWorkflowRunRequest
{
"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
{
"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
{
"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 ApiWorkflowSummary
{
"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
{
"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, ListingFilters, RankDefinition, SectorPhraseMatch, SecuritySelection, ShareClassHandling.
Schema ArtifactCategory
{
"type": "string",
"enum": [
"terminal",
"intermediate",
"report"
],
"title": "ArtifactCategory"
}
Schema ArtifactSourceType
{
"type": "string",
"enum": [
"user_upload",
"agent",
"module",
"system"
],
"title": "ArtifactSourceType"
}
Schema ArtifactStatus
{
"type": "string",
"enum": [
"pending",
"generated",
"validated",
"error"
],
"title": "ArtifactStatus"
}
Schema ArtifactType
{
"type": "string",
"enum": [
"structured_data",
"text",
"json",
"csv",
"report",
"chart",
"table",
"list",
"data",
"link",
"document",
"image",
"code",
"signal",
"other"
],
"title": "ArtifactType"
}
Schema AsOf
{
"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
{
"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
{
"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, AutomaticTriggerFailureCircuitState.
Schema AutomaticTriggerFailureCircuitState
{
"type": "string",
"enum": [
"armed",
"open",
"resolved"
],
"title": "AutomaticTriggerFailureCircuitState",
"description": "Lifecycle of one automatic-trigger failure fingerprint sequence."
}
Schema Body_upload_artifact
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"type": "string",
"enum": [
"active",
"archived"
],
"title": "DashboardStatus"
}
Schema ExcludedExample
{
"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
{
"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 HTTPValidationError
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
Referenced definitions: ValidationError.
Schema KeptFlagCount
{
"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 ListingFilters
{
"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 LiveArtifactDataDTO
{
"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
{
"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
{
"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
{
"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
{
"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
{
"type": "string",
"enum": [
"active",
"archived"
],
"title": "PipelineStatus"
}
Schema PipelineSummaryDTO
{
"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
{
"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
{
"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
{
"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 QuestionAnswerItem
{
"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
{
"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 RankDefinition
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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, NameCoverage.
Schema SystematicCodeRepairAttemptDTO
{
"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, SystematicCodeRepairRoute, SystematicCodeRepairState, SystematicCodeRepairValidationResult.
Schema SystematicCodeRepairRearmReason
{
"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
{
"type": "string",
"enum": [
"pipeline_builder",
"unsupported"
],
"title": "SystematicCodeRepairRoute",
"description": "Typed repair destination selected from executable ownership."
}
Schema SystematicCodeRepairState
{
"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
{
"type": "string",
"enum": [
"passed",
"failed"
],
"title": "SystematicCodeRepairValidationResult",
"description": "Bounded representative validation outcome."
}
Schema UniverseCheck
{
"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
{
"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, ExclusionCount, KeptFlagCount.
Schema UpdatePipelineDTO
{
"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
{
"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
{
"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
{
"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
{
"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, SourceCheck, UniverseCheck.