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 automation. You describe what you want built in plain language, point it at a GitHub repository, and Forge handles the rest: it reads the codebase, plans the changes, writes the code, validates its own work, and opens a pull request. You control how much autonomy it has — from analysis-only to fully automatic PR creation — and you can monitor every step in real time through the event stream.
Forge requires a connected GitHub account. Start the OAuth flow at POST /auth/github/start before submitting tasks.

​
Run modes

Choose the mode that matches how much automation you want:
ModeWhat Forge does
analyze_onlyReads the codebase and produces a plan. No code is written.
generate_patchWrites code edits but does not open a pull request.
autonomousWrites code and pauses for your approval before creating the PR.
create_prWrites code and creates the pull request automatically, without confirmation.

​
Run lifecycle

A Forge run moves through these statuses in order: 
queued → submitted → planning → editing → validating → [awaiting_approval] → creating_pr → completed
The awaiting_approval step only appears in autonomous mode. In create_pr mode the run goes directly from validating to creating_pr.

​
Submitting a task

1

Connect GitHub

If you haven’t already, start the GitHub OAuth flow:
curl
curl --request POST \
  --url https://api.manticscore.com/auth/github/start \
  --header 'Authorization: Bearer <token>'
Open the returned auth_url in a browser to complete authorization.
2

Submit the Forge task

Describe the coding task in plain language and specify the target repository.
​
prompt
string
required
Natural language description of the coding task. Up to 5,000 characters.
​
repository_name
string
required
The GitHub repository to work in, in owner/name format.
​
mode
string
default:"autonomous"
Run mode: analyze_only, generate_patch, autonomous, or create_pr.
​
project_id
string
UUID of an existing ManticScore project. Pass null to leave unattached.
​
constraints
array
Optional list of constraints the AI should follow, e.g. ["Do not modify existing tests", "Use the existing logger utility"].
curl --request POST \
  --url https://api.manticscore.com/forge/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "Add a PDF export endpoint to the invoices API. The endpoint should accept an invoice ID, generate a PDF using the existing template engine, and return it as a file download.",
    "repository_name": "your-org/your-repo",
    "mode": "autonomous",
    "project_id": null,
    "constraints": [
      "Use the existing PDFRenderer class in src/utils/pdf.ts",
      "Do not modify existing invoice tests"
    ]
  }'
Response 201:
{
  "task_id": "d4e5f6a7-...",
  "run_id": "e5f6a7b8-...",
  "status": "queued"
}
3

Stream run progress

Connect to the run’s event stream to watch Forge plan and write code in real time.
curl
curl --request GET \
  --url 'https://api.manticscore.com/forge/runs/e5f6a7b8-.../events?cursor=0' \
  --header 'Authorization: Bearer <token>'

​
Streaming run events

The stream follows the NDJSON v1 protocol.
EventDescription
stream_startStream confirmed open
planForge’s analysis plan for the task
diffCode changes produced during the editing phase
status_changeRun moved to a new status (e.g. planning → editing)
tool_call_failedA specific tool call failed; includes the tool name and error message
errorNon-retryable run failure
doneStream closed
When a tool call fails, Forge emits a tool_call_failed event with the specific tool name and error before surfacing a generic failure. This makes it easier to diagnose integration issues.

​
Approving or rejecting a run (autonomous mode)

When a run in autonomous mode reaches awaiting_approval, you review the plan and diff before the PR is created. Approve — create the PR:
curl
curl --request POST \
  --url https://api.manticscore.com/forge/runs/e5f6a7b8-.../approve \
  --header 'Authorization: Bearer <token>'
Reject — discard the run:
curl
curl --request POST \
  --url https://api.manticscore.com/forge/runs/e5f6a7b8-.../reject \
  --header 'Authorization: Bearer <token>'
Cancel — stop an in-progress run:
curl
curl --request POST \
  --url https://api.manticscore.com/forge/runs/e5f6a7b8-.../cancel \
  --header 'Authorization: Bearer <token>'
Retry — start a new run from the same task (after failure, rejection, or cancellation):
curl
curl --request POST \
  --url https://api.manticscore.com/forge/runs/e5f6a7b8-.../retry \
  --header 'Authorization: Bearer <token>'

​
Fetching run details and PR info

​
List all runs

curl
curl --request GET \
  --url https://api.manticscore.com/forge/runs \
  --header 'Authorization: Bearer <token>'

​
Get a specific run

curl
curl --request GET \
  --url https://api.manticscore.com/forge/runs/e5f6a7b8-... \
  --header 'Authorization: Bearer <token>'
Returns the full run object with a steps array and an optional pull_request object once the PR has been created.

​
Get pull request details

curl
curl --request GET \
  --url https://api.manticscore.com/forge/pulls/e5f6a7b8-... \
  --header 'Authorization: Bearer <token>'

{
  "id": "uuid",
  "run_id": "uuid",
  "repository_name": "your-org/your-repo",
  "pr_number": 42,
  "pr_url": "https://github.com/your-org/your-repo/pull/42"
}

​
Using Forge from a build node

If you have a Build Graph, you can kick off a Forge run directly from any node. ManticScore uses the node’s generated spec as the coding prompt:
curl
curl --request POST \
  --url https://api.manticscore.com/build-nodes/node_uuid_here/implement \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "repo": "your-org/your-repo",
    "mode": "create_pr",
    "notes": "Make sure to add rate limiting on the new endpoint"
  }'
When you provide notes, ManticScore refines the node’s spec with your direction before passing it to Forge.

​
Limits and credits

Value
Rate limit10 requests / minute (task submission)
Retry rate limit5 requests / minute
Credit cost2 credits per run
Forge requires push access to the target repository. If your GitHub account does not have push access, the task submission returns a 403 error.