Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.manticscore.com/llms.txt

Use this file to discover all available pages before exploring further.

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
  }'
Request body
​
idea
string
required
The product idea used to prime the LLM. Maximum 5,000 characters.
​
features
object[]
Features to include in the build graph. Each object must have id, label, and source string fields. Required unless auto_select is true.
​
auto_select
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.
​
phase
number | null
default:"null"
Set to 1 to limit auto-selected features to phase_1 items only. Ignored when auto_select is false.
​
project_id
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}.
​
research_id
string | null
UUID of a specific research job to use as context. Optional.
​
feature_research_id
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"
}
​
graph_id
string
required
UUID of the newly created graph. Use this to subscribe to the events stream and retrieve the graph once ready.
​
status
string
required
Always "initializing" on creation. The graph transitions to generating and then ready as the background pipeline runs.
Error responses
StatusCause
400No features provided and auto_select is false
400auto_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
​
cursor
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": {...}}.
Emitted immediately on connect.
{"v": 1, "event": "stream_start", "data": {"request_id": "req_abc123", "job_id": "job_xyz789"}}
​
request_id
string
Trace ID for this connection. Include in bug reports.
​
job_id
string
Internal job identifier for the generation pipeline.
Fired once the graph row is persisted in the database.
{"v": 1, "event": "graph_created", "data": {"graph_id": "...", "project_id": "...|null"}}
Signals the start or completion of the LLM generation stage.
{"v": 1, "event": "stage", "data": {"name": "llm", "status": "started"}}
​
name
string
Always "llm" for build graph generation.
​
status
string
"started" or "completed".
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"
  }
}
​
risk
string
"green", "yellow", or "red" — AI-assessed implementation risk.
​
node_status
string
"collapsed" for expandable nodes, "leaf" for terminal nodes.
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}}
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}}
Signals a pipeline failure.
{"v": 1, "event": "error", "data": {"code": "LLM_TIMEOUT", "message": "Generation timed out", "retryable": true}}
​
retryable
boolean
When true, you can safely retry the originating request.
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
​
project_id
string
Filter results to graphs attached to this project UUID.
​
limit
number
default:"50"
Maximum number of graphs to return. Maximum value: 100.
​
offset
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"
  }
]
​
status
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.
​
id
string
required
UUID of the graph.
​
title
string
required
Auto-generated graph title derived from the product idea.
​
status
string
required
Current graph status.
​
source
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.
​
selected_features
object[]
The features used to generate this graph.
​
nodes
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"}'
​
title
string | null
New title for the graph. Pass null to leave unchanged.
​
project_id
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"}'
​
research_id
string
required
UUID of the research job to link.
​
link_type
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"
}
StatusCause
409This 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}'
​
target
string
required
Export destination. One of "linear", "jira", "slack", "notion", or "github".
​
top_level_only
boolean
default:"false"
When true, only root-level nodes are exported. When false, all nodes in the tree are included.
​
team_id
string | null
Linear team ID. Falls back to your saved Linear default when omitted.
​
project_key
string | null
Jira project key. Falls back to your saved Jira default when omitted.
​
channel
string | null
Slack channel ID or name. Falls back to your saved Slack default when omitted.
​
repo
string | null
GitHub repository in owner/name format. Required for the "github" target.
Response by target 
{
  "total": 12,
  "created": 12,
  "issues": [
    {"id": "LIN-123", "title": "OAuth integration", "url": "https://linear.app/..."}
  ]
}
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.
​
format
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.
StatusMeaning
200PDF (or text/plain fallback) returned.
404Build graph not found or owned by another user.
422Unsupported format value.