diff --git a/docs/administration/deploy-server.mdx b/docs/administration/deploy-server.mdx
index 4563cd460..cb40f4786 100644
--- a/docs/administration/deploy-server.mdx
+++ b/docs/administration/deploy-server.mdx
@@ -89,11 +89,11 @@ The web UI connects to the API server and provides:
 
 ## Event streaming
 
-The API streams run events via [Server-Sent Events (SSE)](/api-reference/runs#get-events). Every stage start, LLM call, tool invocation, and edge selection is emitted as a structured JSON event. Any HTTP client that supports SSE can subscribe — the web UI is just one consumer.
+The API streams run events via [Server-Sent Events (SSE)](/api-reference/runs/stream-run-events). Every stage start, LLM call, tool invocation, and edge selection is emitted as a structured JSON event. Any HTTP client that supports SSE can subscribe — the web UI is just one consumer.
 
 ## Human-in-the-loop
 
-In server mode, human-in-the-loop questions are served over HTTP instead of terminal prompts. The engine blocks the current stage until an answer is submitted, then continues execution. See the [Human-in-the-Loop API reference](/api-reference/human-in-the-loop) for the polling and answer endpoints.
+In server mode, human-in-the-loop questions are served over HTTP instead of terminal prompts. The engine blocks the current stage until an answer is submitted, then continues execution. See the [list questions](/api-reference/human-in-the-loop/list-run-questions) and [submit answer](/api-reference/human-in-the-loop/submit-run-answer) API reference pages.
 
 ## Authentication
 
diff --git a/docs/docs.json b/docs/docs.json
index 039397008..a02db282f 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -217,7 +217,7 @@
                   "GET /runs/{id}/context",
                   "GET /runs/{id}/stages",
                   "GET /runs/{id}/stages/{stageId}/turns",
-                  "GET /runs/{id}/configuration"
+                  "GET /runs/{id}/settings"
                 ]
               }
             ]
diff --git a/docs/execution/observability.mdx b/docs/execution/observability.mdx
index 761ae18d6..494e6b7be 100644
--- a/docs/execution/observability.mdx
+++ b/docs/execution/observability.mdx
@@ -163,7 +163,7 @@ FABRO_LOG=debug fabro run workflow.fabro
 
 ### API: Server-Sent Events
 
-When running workflows through the API server, subscribe to a live event stream via the [run events endpoint](/api-reference/runs#get-events). Each event is a JSON-serialized `WorkflowRunEvent`. The stream stays open until the run completes.
+When running workflows through the API server, subscribe to a live event stream via the [run events endpoint](/api-reference/runs/stream-run-events). Each event is a JSON-serialized `WorkflowRunEvent`. The stream stays open until the run completes.
 
 ### Web UI
 
@@ -209,13 +209,13 @@ Each run's directory contains a standard set of files:
 
 ### Inspecting stages and turns
 
-The API provides endpoints for drilling into individual stages and the agent turns within them. See the [stages](/api-reference/run-internals#get-stages) and [turns](/api-reference/run-internals#get-stage-turns) API reference for details.
+The API provides endpoints for drilling into individual stages and the agent turns within them. See the [stages](/api-reference/run-internals/list-run-stages) and [turns](/api-reference/run-internals/list-stage-turns) API reference pages.
 
 ## Insights (SQL analytics)
 
 The Insights feature lets you run SQL queries across your run data using DuckDB. This is useful for aggregate analysis — finding slow workflows, tracking failure rates, comparing model costs, and spotting trends.
 
-Insights is managed through the [Insights API endpoints](/api-reference/insights). You can save, update, and execute queries programmatically.
+Insights is managed through the [saved queries](/api-reference/insights/list-saved-queries) and [execute query](/api-reference/insights/execute-query) API reference pages. You can save, update, and execute queries programmatically.
 
 ### Example queries
 
@@ -253,7 +253,7 @@ ORDER BY runs DESC
 
 ## Aggregate usage
 
-The API server tracks aggregate usage counters across all runs — total run count, total runtime, and per-model breakdowns of token usage and cost. See the [usage endpoint](/api-reference/run-outputs#get-usage) in the API reference. Counters reset on server restart.
+The API server tracks aggregate usage counters across all runs — total run count, total runtime, and per-model breakdowns of token usage and cost. See the [usage endpoint](/api-reference/usage/aggregate-usage) in the API reference. Counters reset on server restart.
 
 <Frame caption="The Usage tab breaks down token counts and costs by stage and by model.">
   <img src="/images/web/run-usage.png" alt="Fabro web UI run usage showing per-stage and per-model token and cost breakdown" />
diff --git a/docs/execution/retros.mdx b/docs/execution/retros.mdx
index 0ec2dd0ed..d6b5ad4f5 100644
--- a/docs/execution/retros.mdx
+++ b/docs/execution/retros.mdx
@@ -144,7 +144,7 @@ retros = true
 
 ### API
 
-Retros are also available via the REST API. See the [Retros API reference](/api-reference/retros) for endpoints to retrieve a single run's retro or list retros across all runs.
+Retros are also available via the REST API. See the [list retros](/api-reference/retros/list-retros) and [retrieve retro](/api-reference/retros/retrieve-retro) API reference pages.
 
 ## Storage
 
diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx
index 0cb644785..4454d462a 100644
--- a/docs/reference/architecture.mdx
+++ b/docs/reference/architecture.mdx
@@ -53,11 +53,11 @@ Key server config options:
 
 ### Event streaming
 
-The API streams run events via [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). Every significant action — stage starts, LLM calls, tool invocations, edge selections — is emitted as a structured JSON event. The web UI uses this endpoint for real-time run monitoring. Any HTTP client that supports SSE can subscribe. See the [run events endpoint](/api-reference/runs#get-events) in the API reference.
+The API streams run events via [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). Every significant action — stage starts, LLM calls, tool invocations, edge selections — is emitted as a structured JSON event. The web UI uses this endpoint for real-time run monitoring. Any HTTP client that supports SSE can subscribe. See the [run events endpoint](/api-reference/runs/stream-run-events) in the API reference.
 
 ### Human-in-the-loop
 
-In API mode, human-in-the-loop questions are served over HTTP instead of terminal prompts. The engine blocks the current stage until an answer is received, then continues execution. See the [Human-in-the-Loop API reference](/api-reference/human-in-the-loop) for the polling and answer submission endpoints.
+In API mode, human-in-the-loop questions are served over HTTP instead of terminal prompts. The engine blocks the current stage until an answer is received, then continues execution. See the [list questions](/api-reference/human-in-the-loop/list-run-questions) and [submit answer](/api-reference/human-in-the-loop/submit-run-answer) API reference pages.
 
 ### Authentication