Build graphs: generate, stream events, ship, and export

Build graphs are recursive, AI-generated work trees that decompose your product features into actionable build nodes. You create a graph by submitting a set of features and a product idea; ManticScore runs an LLM pipeline and emits nodes over a streaming NDJSON connection as they are created. Once a graph reaches ready status, you can expand individual nodes, update metadata, link additional research, and ship the entire tree to your preferred project management tool in a single request.

POST /build-graphs

Creates a new build graph and immediately returns a graph_id. Generation runs in the background — subscribe to the events stream to follow progress.

curl -X POST https://api.manticscore.com/build-graphs \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "idea": "A mobile app that lets indie coffee shops manage loyalty programs",
    "features": [
      {"id": "feat_1", "label": "Loyalty card stamping", "source": "research"},
      {"id": "feat_2", "label": "Customer rewards dashboard", "source": "research"}
    ],
    "project_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "auto_select": false
  }'

import httpx

response = httpx.post(
    "https://api.manticscore.com/build-graphs",
    headers={"Authorization": f"Bearer {session_token}"},
    json={
        "idea": "A mobile app that lets indie coffee shops manage loyalty programs",
        "features": [
            {"id": "feat_1", "label": "Loyalty card stamping", "source": "research"},
            {"id": "feat_2", "label": "Customer rewards dashboard", "source": "research"},
        ],
        "project_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "auto_select": False,
    },
)
graph_id = response.json()["graph_id"]

Request body

string

required

The product idea used to prime the LLM. Maximum 5,000 characters.

object[]

Features to include in the build graph. Each object must have id, label, and source string fields. Required unless auto_select is true.

Show feature object properties

string

required

Unique identifier for the feature, typically from a research or feature-research job.

string

required

Human-readable feature name displayed as the node label.

string

required

Where the feature originated. Common values: "research", "feature_research", "manual".

boolean

default:"false"

When true, ManticScore reads build_readiness from the linked research job and selects features automatically. You must provide either explicit features or set auto_select: true.

number | null

default:"null"

Set to 1 to limit auto-selected features to phase_1 items only. Ignored when auto_select is false.

string | null

UUID of the project to attach this graph to. Optional — you can link a graph to a project later via PATCH /build-graphs/{graph_id}.

string | null

UUID of a specific research job to use as context. Optional.

string | null

UUID of a feature research job whose results are injected into the LLM prompt. If omitted and a project_id is supplied, ManticScore auto-detects the latest completed feature research for that project.

Response

201 response

{
  "graph_id": "a1b2c3d4-0000-0000-0000-000000000002",
  "status": "initializing"
}

string

required

UUID of the newly created graph. Use this to subscribe to the events stream and retrieve the graph once ready.

string

required

Always "initializing" on creation. The graph transitions to generating and then ready as the background pipeline runs.

Error responses

Status	Cause
`400`	No features provided and `auto_select` is `false`
`400`	`auto_select` is `true` but the linked research has no `build_readiness` data

GET /build-graphs//events

Stream NDJSON progress events for a build graph. Supports cursor-based replay so you can reconnect without missing events.

This endpoint uses Stream auth — the same session token as other endpoints, but the server extends the TTL on connect to keep long-running streams alive.

curl -N "https://api.manticscore.com/build-graphs/GRAPH_ID/events?cursor=0" \
  -H "Authorization: Bearer <session_token>"

Query parameters

number

default:"0"

Resume from this event sequence number. Pass the last seq you received to replay only missed events after a disconnect.

Event reference Each line is a JSON object: {"v": 1, "event": "<type>", "data": {...}}.

stream_start

Emitted immediately on connect.

{"v": 1, "event": "stream_start", "data": {"request_id": "req_abc123", "job_id": "job_xyz789"}}

string

Trace ID for this connection. Include in bug reports.

string

Internal job identifier for the generation pipeline.

graph_created

Fired once the graph row is persisted in the database.

{"v": 1, "event": "graph_created", "data": {"graph_id": "...", "project_id": "...|null"}}

stage

Signals the start or completion of the LLM generation stage.

{"v": 1, "event": "stage", "data": {"name": "llm", "status": "started"}}

string

Always "llm" for build graph generation.

string

"started" or "completed".

node_created

Emitted for each node as it is written to the database during generation.

{
  "v": 1,
  "event": "node_created",
  "data": {
    "id": "node_uuid",
    "graph_id": "graph_uuid",
    "parent_id": "parent_uuid|null",
    "node_key": "auth.oauth",
    "depth": 1,
    "sort_order": 0,
    "name": "OAuth integration",
    "description": "Implement OAuth 2.0 login flow",
    "risk": "yellow",
    "node_status": "collapsed"
  }
}

string

"green", "yellow", or "red" — AI-assessed implementation risk.

string

"collapsed" for expandable nodes, "leaf" for terminal nodes.

graph_ready

Emitted when all root nodes have been created and the graph is ready for use.

{"v": 1, "event": "graph_ready", "data": {"graph_id": "...", "root_count": 5, "duration_ms": 8423}}

expand_start / expand_done

Fired when a node expansion begins and completes during the initial generation sweep.

{"v": 1, "event": "expand_start", "data": {"node_id": "...", "depth": 1}}
{"v": 1, "event": "expand_done", "data": {"node_id": "...", "children_count": 4}}

error

Signals a pipeline failure.

{"v": 1, "event": "error", "data": {"code": "LLM_TIMEOUT", "message": "Generation timed out", "retryable": true}}

boolean

When true, you can safely retry the originating request.

done

Always the final event on the stream, whether successful or not.

{"v": 1, "event": "done", "data": {}}

Parse on the event field and ignore types you don’t recognize. The protocol is forward-compatible and new event types may be added without a version bump.

GET /build-graphs

List build graphs, optionally scoped to a project.

curl "https://api.manticscore.com/build-graphs?project_id=PROJECT_UUID&limit=20&offset=0" \
  -H "Authorization: Bearer <session_token>"

Query parameters

string

Filter results to graphs attached to this project UUID.

number

default:"50"

Maximum number of graphs to return. Maximum value: 100.

number

default:"0"

Number of graphs to skip for pagination.

200 response

[
  {
    "id": "a1b2c3d4-0000-0000-0000-000000000002",
    "title": "Loyalty App Build Graph",
    "status": "ready",
    "created_at": "2026-04-19T10:30:00Z"
  }
]

string

One of "initializing", "generating", "ready", or "failed".

GET /build-graphs/

Retrieve a specific graph with its full node tree.

curl "https://api.manticscore.com/build-graphs/GRAPH_ID" \
  -H "Authorization: Bearer <session_token>"

200 response

{
  "id": "a1b2c3d4-0000-0000-0000-000000000002",
  "title": "Loyalty App Build Graph",
  "status": "ready",
  "source": "user",
  "selected_features": [
    {"id": "feat_1", "label": "Loyalty card stamping", "source": "research"}
  ],
  "nodes": [
    {
      "id": "node_uuid",
      "name": "Authentication",
      "depth": 0,
      "node_status": "collapsed",
      "children": []
    }
  ]
}

GET /build-graphs/{graph_id} returns the node tree under the key "nodes". The shortcut endpoint GET /projects/{project_id}/build-graph returns the same tree under "roots" instead.

string

required

UUID of the graph.

string

required

Auto-generated graph title derived from the product idea.

string

required

Current graph status.

string

How the graph was created. "user" for graphs created via POST /build-graphs, "research_auto_seeded" for graphs auto-created by the server when an attached research run completed with a quality score of 70 or higher. Auto-seeded graphs are pre-populated with the top 5 features from the research and start in status: "ready"; you can expand any node immediately or treat the graph as a starting point and edit it.

object[]

The features used to generate this graph.

Show properties

string

Feature identifier.

string

Feature label.

string

Feature origin.

object[]

Root-level nodes of the build tree. Each node may contain nested children. See Build nodes for the full node shape.

PATCH /build-graphs/

Update a graph’s project association or title.

curl -X PATCH "https://api.manticscore.com/build-graphs/GRAPH_ID" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "v2 Build Plan", "project_id": "a1b2c3d4-0000-0000-0000-000000000001"}'

string | null

New title for the graph. Pass null to leave unchanged.

string | null

UUID of the project to link, or null to detach the graph from its current project.

The response is the full updated graph row.

DELETE /build-graphs/

Permanently deletes the graph and all its nodes.

curl -X DELETE "https://api.manticscore.com/build-graphs/GRAPH_ID" \
  -H "Authorization: Bearer <session_token>"

200 response

{"success": true}

POST /build-graphs//sources

Link an additional research job to a graph as a supplementary context source.

curl -X POST "https://api.manticscore.com/build-graphs/GRAPH_ID/sources" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"research_id": "RESEARCH_UUID", "link_type": "supplement"}'

string

required

UUID of the research job to link.

string

required

Relationship between the research and this graph. One of "context", "supplement", or "external".

201 response

{
  "graph_id": "GRAPH_UUID",
  "research_id": "RESEARCH_UUID",
  "link_type": "supplement"
}

Status	Cause
`409`	This research job is already linked to this graph

POST /build-graphs//ship

Export the entire graph to an external platform in a single request. ManticScore uses your saved integration defaults — no extra configuration required after initial connection.

curl -X POST "https://api.manticscore.com/build-graphs/GRAPH_ID/ship" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"target": "linear", "top_level_only": false}'

curl -X POST "https://api.manticscore.com/build-graphs/GRAPH_ID/ship" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"target": "slack", "channel": "C012AB3CD"}'

curl -X POST "https://api.manticscore.com/build-graphs/GRAPH_ID/ship" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"target": "github", "repo": "acme/loyalty-app"}'

string

required

Export destination. One of "linear", "jira", "slack", "notion", or "github".

boolean

default:"false"

When true, only root-level nodes are exported. When false, all nodes in the tree are included.

string | null

Linear team ID. Falls back to your saved Linear default when omitted.

string | null

Jira project key. Falls back to your saved Jira default when omitted.

string | null

Slack channel ID or name. Falls back to your saved Slack default when omitted.

string | null

GitHub repository in owner/name format. Required for the "github" target.

Response by target

Linear / Jira
Slack
Notion
GitHub

{
  "total": 12,
  "created": 12,
  "issues": [
    {"id": "LIN-123", "title": "OAuth integration", "url": "https://linear.app/..."}
  ]
}

{"sent": true, "channel": "C012AB3CD"}

{"page": {"id": "notion_page_id", "url": "https://notion.so/..."}}

{"run_id": "forge_run_uuid", "status": "queued"}

GitHub export kicks off a Forge run that creates a PR from the build tree. Track progress via GET /forge/runs/{run_id}/events. See Forge for full event documentation.

A 400 response means the target integration is not connected or has no default configuration saved. Connect the integration and configure defaults at PATCH /profile/integrations/{toolkit}/defaults before calling ship.

GET /build-graphs//export

Downloads the build graph as a binary PDF file. The export flattens the recursive node tree into an indented bullet list and includes the build order rationale and overall graph status. The graph is scoped to the authenticated user. If WeasyPrint is unavailable on the server, the endpoint falls back to a plain-text export.

string

default:"pdf"

Export format. Currently only pdf is supported.

curl "https://api.manticscore.com/build-graphs/GRAPH_ID/export?format=pdf" \
  -H "Authorization: Bearer <token>" \
  --output build-plan.pdf

The response is binary content with Content-Type: application/pdf and a Content-Disposition: attachment header naming the file <idea>-build-plan.pdf. Sections rendered in order: build_order_rationale, nodes (indented hierarchy of titles + summaries), and status.

Status	Meaning
`200`	PDF (or `text/plain` fallback) returned.
`404`	Build graph not found or owned by another user.
`422`	Unsupported `format` value.

Overview

Projects & Research

Build & Forge

Intelligence & Chat

Integrations & Ship

Pipeline & Realtime

Billing & Admin

Build graphs: generate, stream events, ship, and export

POST /build-graphs

GET /build-graphs//events

GET /build-graphs

GET /build-graphs/

PATCH /build-graphs/

DELETE /build-graphs/

POST /build-graphs//sources

POST /build-graphs//ship

GET /build-graphs//export

​POST /build-graphs

​GET /build-graphs//events

​GET /build-graphs

​GET /build-graphs/

​PATCH /build-graphs/

​DELETE /build-graphs/

​POST /build-graphs//sources

​POST /build-graphs//ship

​GET /build-graphs//export

POST /build-graphs

GET /build-graphs//events

GET /build-graphs

GET /build-graphs/

PATCH /build-graphs/

DELETE /build-graphs/

POST /build-graphs//sources

POST /build-graphs//ship

GET /build-graphs//export