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.

Forge is ManticScore’s agentic coding engine. You give it a natural language prompt and a GitHub repository; it plans the implementation, writes and validates code, and opens a pull request — all autonomously. You can run Forge directly via POST /forge/tasks, or trigger it from a build node via POST /build-nodes/{node_id}/implement. Once a PR is open, Forge polls for CI failures and review change requests and can auto-retry with failure context.

​
Run lifecycle

A Forge run moves through a fixed sequence of statuses: 
queued → submitted → planning → editing → validating
  → awaiting_approval*  → creating_pr → completed
* awaiting_approval only appears in autonomous mode. In create_pr mode the run goes directly from validating to creating_pr. Terminal statuses: failed, cancelled, rejected.

​
POST /forge/tasks

Submit a new coding task. Returns immediately with a task_id and run_id. Stream progress via GET /forge/runs/{run_id}/events.
Rate limit: 10 requests per minute.
curl -X POST https://api.manticscore.com/forge/tasks \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add rate limiting middleware to all /api/v1 routes using a sliding window algorithm. Limits: 100 req/min for authenticated users, 20 req/min for unauthenticated.",
    "repository_name": "acme/loyalty-app",
    "mode": "create_pr",
    "project_id": "a1b2c3d4-0000-0000-0000-000000000001"
  }'
​
prompt
string
required
Natural language description of the coding task. Maximum 5,000 characters. Be specific — include relevant constraints, existing patterns to follow, and files or modules to avoid touching.
​
repository_name
string
required
Target GitHub repository in owner/name format. You must have push access to this repository.
​
mode
string
default:"autonomous"
How Forge should complete the task:
  • "create_pr" — plan, code, validate, and open a PR automatically
  • "autonomous" — plan, code, validate, then pause at awaiting_approval for your review before creating the PR
  • "generate_patch" — produce code edits without creating a PR
  • "analyze_only" — produce a plan and analysis only, no code written
​
provider
string
default:"anthropic"
LLM provider to use for the coding agent. Either "anthropic" or "openai".
​
project_id
string | null
UUID of a ManticScore project to associate this run with. Optional — useful for grouping runs in the dashboard.
​
constraints
string[]
Additional constraints to enforce during code generation, applied on top of the prompt. For example: ["Do not modify existing tests", "All new functions must have JSDoc comments"].
201 response
{
  "task_id": "TASK_UUID",
  "run_id": "RUN_UUID",
  "status": "queued"
}
​
task_id
string
required
UUID of the underlying task. A task is the stable record — a run is one execution attempt. Retrying creates a new run from the same task.
​
run_id
string
required
UUID of this execution run. Use this to stream events and manage approval.
StatusCause
403Your account has no GitHub connection, or you do not have push access to the target repository

​
GET /forge/runs//events

Stream run progress as NDJSON. Supports cursor-based replay for reconnection.
This endpoint uses Stream auth — the server extends your session TTL on connect.
curl -N "https://api.manticscore.com/forge/runs/RUN_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: {"v": 1, "event": "<type>", "data": {...}}.
Emitted immediately on connect.
{"v": 1, "event": "stream_start", "data": {"request_id": "req_abc123"}}
Emitted each time the run transitions to a new status.
{"v": 1, "event": "status_change", "data": {"status": "planning"}}
Use these events to track progress through the run lifecycle: queued → submitted → planning → editing → validating → awaiting_approval → creating_pr → completed.
Emitted once planning is complete. Contains the structured implementation plan Forge intends to execute.
{"v": 1, "event": "plan", "data": {"steps": [...], "files_to_edit": [...]}}
Emitted after code edits are generated. Contains the code diff for the changes Forge produced.
{"v": 1, "event": "diff", "data": {"files": [...], "summary": "3 files changed"}}
Fired when a specific external tool call inside the run fails. Surfaces which tool broke so you can diagnose integration issues rather than seeing only a generic failure.
{"v": 1, "event": "tool_call_failed", "data": {"tool": "GITHUB_CREATE_BRANCH", "error": "Repository not found or insufficient permissions"}}
​
tool
string
The Composio tool name that failed.
​
error
string
The error message from the failed tool call.
Emitted at the end of each cycle of the validator-driven repair loop. Reports how many error-level findings remained before and after the cycle so you can track repair progress.
{"v": 1, "event": "repair_cycle", "data": {"cycle": 1, "errors_before": 4, "errors_after": 1}}
​
cycle
number
The repair cycle index (1-based).
​
errors_before
number
Count of error-level findings entering this cycle.
​
errors_after
number
Count of error-level findings remaining after the cycle ran.
Emitted when a repair cycle finishes without reducing the error count — that is, the LLM rewrite produced output that did not actually fix anything (errors_after >= errors_before). Use this as a distinct signal from repair_cycle to warn users that a [DRAFT] PR likely still has the original validation failures and should be reviewed carefully rather than treated as a near-fix.
{"v": 1, "event": "repair_stalled", "data": {"cycle": 2, "errors_before": 3, "errors_after": 3, "regressed": false}}
​
cycle
number
The repair cycle index (1-based) that stalled.
​
errors_before
number
Count of error-level findings entering the stalled cycle.
​
errors_after
number
Count of error-level findings after the stalled cycle.
​
regressed
boolean
true when the cycle made things worse (errors_after > errors_before); false when it merely failed to make progress (errors_after == errors_before).
In addition to the stream event, the server fires an APNS push notification to every device registered for the user via POST /push-tokens. The push payload’s data includes {"type": "repair_stalled", "run_id": "<run_id>"} so mobile clients can deep-link straight to the run detail screen. The push is best-effort — failures never block the run or the stream.
Signals a run-level failure.
{"v": 1, "event": "error", "data": {"code": "VALIDATION_FAILED", "message": "Generated code failed linting checks"}}
Always the final event on the stream.
{"v": 1, "event": "done", "data": {}}

​
GET /forge/runs

List your Forge runs, optionally filtered by status. 
curl "https://api.manticscore.com/forge/runs?status=awaiting_approval&limit=20" \
  -H "Authorization: Bearer <session_token>"
​
status
string
Filter to runs in this status. Valid values: queued, submitted, planning, editing, validating, awaiting_approval, creating_pr, completed, failed, cancelled, rejected.
​
limit
number
default:"20"
Maximum results to return. Maximum value: 100.
​
offset
number
default:"0"
Number of results to skip for pagination.
200 response
[
  {
    "id": "RUN_UUID",
    "task_id": "TASK_UUID",
    "repository_name": "acme/loyalty-app",
    "prompt": "Add rate limiting middleware...",
    "mode": "create_pr",
    "status": "completed",
    "branch_name": "forge/rate-limiting-abc123"
  }
]

​
GET /forge/runs/

Retrieve full details for a single run, including its step history and PR information. 
curl "https://api.manticscore.com/forge/runs/RUN_ID" \
  -H "Authorization: Bearer <session_token>"
The response is the full run object with a steps array detailing each pipeline stage and, when a PR has been created, a pull_request object with PR metadata.

​
Approving, rejecting, and cancelling runs

These three endpoints apply to runs in autonomous mode.
When a run reaches awaiting_approval, call this endpoint to authorize PR creation.
curl -X POST "https://api.manticscore.com/forge/runs/RUN_ID/approve" \
  -H "Authorization: Bearer <session_token>"
200 response
{"run_id": "RUN_UUID", "status": "creating_pr"}
A 400 response means the run is not currently in awaiting_approval state.

​
POST /forge/runs//retry

Create a new run from the same underlying task. Only available for runs in failed, cancelled, or rejected status.
Rate limit: 5 requests per minute.
curl -X POST "https://api.manticscore.com/forge/runs/RUN_ID/retry" \
  -H "Authorization: Bearer <session_token>"
200 response
{
  "run_id": "NEW_RUN_UUID",
  "status": "queued"
}
Retry creates a new run from the same task. The run_id in the response is different from the one you retried. Subscribe to GET /forge/runs/{new_run_id}/events to track the new attempt.

​
Pull requests

Auto-append to the project brief on PR creation. When a Forge run associated with a project opens a PR, the server appends a normalized progress entry to the project’s most recent brief. If the project has no brief yet, one is bootstrapped from the latest research with audience: "founder" before the entry is added.The progress entry is upserted into a progress section with shape {title, items[]} and is keyed on pr_number, so reposting the same PR is idempotent. Every successful append increments brief.revision and bumps brief.updated_at, and emits a revision_updated event on the brief channel. This step is best-effort; PR creation never fails because of it.
Validation gate and draft PR fallback. After code generation, Forge runs a deterministic validator on the proposed changes. If error-level findings are detected, the run enters a repair loop (up to two cycles) that summarizes the failures and rewrites only the failing files before re-validating. Each cycle emits a repair_cycle event with errors_before and errors_after; if a cycle finishes without reducing the error count, Forge additionally emits a repair_stalled event so clients can warn the user that the LLM did not actually fix the failures. If the run still has error-level findings after the repair budget is spent, Forge proceeds to PR creation but opens the PR as a draft with a [AgentForge][DRAFT] title prefix, so reviewers can see it needs human attention before merge. Runs that pass validation (with the repair loop or without one) open a normal, ready-for-review PR.

​
GET /forge/pulls/

Retrieve PR details for a completed run. 
curl "https://api.manticscore.com/forge/pulls/RUN_ID" \
  -H "Authorization: Bearer <session_token>"
200 response
{
  "id": "PR_UUID",
  "run_id": "RUN_UUID",
  "repository_name": "acme/loyalty-app",
  "pr_number": 42,
  "pr_url": "https://github.com/acme/loyalty-app/pull/42"
}

​
GET /forge/pulls//reactions

Retrieve the CI status, review state, and auto-retry configuration for a Forge PR. Forge polls open PRs every 5 minutes and can automatically retry runs when CI fails or a reviewer requests changes. 
curl "https://api.manticscore.com/forge/pulls/PR_ID/reactions" \
  -H "Authorization: Bearer <session_token>"
200 response
{
  "id": "PR_UUID",
  "ci_status": "failure",
  "ci_failure_log": "Error: 3 tests failed\n  FAIL src/middleware/rate-limit.test.ts",
  "review_status": null,
  "review_comments": null,
  "retry_count": 1,
  "max_retries": 2,
  "child_run_id": "CHILD_RUN_UUID",
  "reaction_config": {
    "auto_retry_ci": true,
    "auto_retry_review": false
  }
}
​
ci_status
string | null
Current CI check status from GitHub. null if CI has not yet reported.
​
ci_failure_log
string | null
Truncated CI failure log used as context for auto-retries. null when CI is passing.
​
review_status
string | null
Latest review state from GitHub. null if no review has been submitted.
​
review_comments
string | null
Review comments used as context for auto-retries. null when no blocking review exists.
​
retry_count
number
Number of auto-retry attempts made so far for this PR.
​
max_retries
number
Maximum auto-retries allowed. Configurable via PATCH /forge/pulls/{pr_id}/reactions.
​
child_run_id
string | null
UUID of the most recent auto-generated retry run, if one exists.
​
reaction_config
object
Auto-retry configuration.

​
PATCH /forge/pulls//reactions

Configure auto-retry behavior for a specific PR. 
curl -X PATCH "https://api.manticscore.com/forge/pulls/PR_ID/reactions" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"auto_retry_ci": true, "auto_retry_review": true, "max_retries": 3}'
​
auto_retry_ci
boolean | null
Enable or disable automatic retry on CI failure. Omit to leave unchanged.
​
auto_retry_review
boolean | null
Enable or disable automatic retry when a reviewer requests changes. Omit to leave unchanged.
​
max_retries
number | null
Maximum number of auto-retries to allow. Accepts 0–5. Omit to leave unchanged.
200 response
{"updated": true}
Auto-retry consumes Forge credits for each attempt. Set max_retries to a conservative value (2–3) to avoid unexpected credit usage on flaky CI.