REST API¶

The examples use this base URL:

export FORGE_API="https://forge.example.com/api/v1"

Availability¶

Endpoint	Response	Meaning
`GET /health`	JSON	The Forge API process is serving requests.
`GET /doctor`	JSON	Forge can reach its control-plane dependency. Returns `502` when it cannot.
`GET /instances`	JSON	Current instance inventory and daemon status.
`GET /instances/{id}`	JSON	One instance’s synthesized control state.
`GET /instances/{id}/health`	JSON	Operator health classification for one instance.

/health proves only that the API process is alive. Use /doctor for control-plane reachability and the runtime status endpoint for a strategy.

Instance inventory¶

curl -fsS "$FORGE_API/instances"

The response contains a daemon object and an instances array. Each instance includes instanceId, project identity, desired state, process state, runtime state, synthesized instanceState, endpoint availability, and the current run ID when known.

Lifecycle¶

Lifecycle actions are asynchronous control operations:

curl -fsS -X POST "$FORGE_API/instances/signal-watch--0.0.1/start"
curl -fsS -X POST "$FORGE_API/instances/signal-watch--0.0.1/stop"
curl -fsS -X POST "$FORGE_API/instances/signal-watch--0.0.1/restart"

An accepted response does not prove convergence. Poll GET /instances/{id} until the desired, process, and runtime states agree.

Runtime status and resources¶

curl -fsS \
  "$FORGE_API/runtime/status?instance=signal-watch--0.0.1"

curl -fsS \
  "$FORGE_API/runtime/resources?instance=signal-watch--0.0.1"

Runtime status separates transport information, engine state, and capability flags. A capability set to false can be the correct contract for that project; inspect capabilityErrors before treating it as a failure.

The resource response contains runtime metadata plus catalog entries. The contract on each entry defines the model, payload schema, delivery model, history model, replay policy, merge model, drop policy, and visibility.

Runtime queries¶

Use product endpoints above when one exists. The generic query gateway is for runtime read models reported by the selected instance:

curl -fsS \
  "$FORGE_API/runtime/query/accounts?instance=signal-watch--0.0.1"

Common query paths include resources, accounts, portfolios, and events. Account- and portfolio-specific routes are exposed only when the runtime advertises those capabilities. Unsupported routes return 409 or 404 rather than an empty successful payload.

History¶

History is scoped by instance and run. The current-run selection is convenient for interactive use; automation should record and send an exact run_id.

Endpoint	Data
`GET /history/instances`	Instances that have durable history.
`GET /history/instances/{id}/summary`	Run-scoped strategy and portfolio summary.
`GET /history/instances/{id}/portfolio/equity-series`	Portfolio equity time series.
`GET /history/instances/{id}/portfolio/metrics`	Portfolio performance metrics.
`GET /history/instances/{id}/factors`	Persisted factor samples.
`GET /history/instances/{id}/market/bars`	Persisted market bars.
`GET /history/instances/{id}/market/orderbook`	Persisted order-book rows.
`GET /history/instances/{id}/orders`	Order lifecycle rows.
`GET /history/instances/{id}/fills`	Execution fills.
`GET /history/instances/{id}/events`	Runtime and account events.

Raw history rows are returned as application/x-ndjson. Supported filters depend on the resource and include run_id, time bounds, limit, resource key, symbol, venue, account, and portfolio. Use the catalog contract to decide whether a live resource has a corresponding history model.

Logs and metrics¶

GET /instances/{id}/logs accepts tail for the number of recent lines and follow for streaming. GET /discovery returns Prometheus HTTP service discovery targets. Metrics endpoints return Prometheus text, not JSON.

Error envelopes¶

Control and live Forge routes serialize protobuf errors with uppercase ErrorCode enum values:

{
  "error": {
    "code": "ERROR_CODE_INSTANCE_NOT_FOUND",
    "message": "signal-watch--0.0.1 not found",
    "capability": "",
    "upstreamCode": "",
    "hint": ""
  }
}

History routes are delegated to the readmodel handler. They use lowercase snake-case codes and include an ok field instead of the extra protobuf error fields:

{
  "ok": false,
  "error": {
    "code": "history_unreachable",
    "message": "ClickHouse request failed"
  }
}

Branch on the HTTP status and error.code within the endpoint’s code vocabulary. Treat message and hint as operator-facing text. Typical statuses are 400 for invalid input, 404 for a missing route, resource, or history run, 409 for an unavailable capability or conflicting history identity, and 502 for an unreachable upstream component or failed history query.