POST /api/runs/:runId/approve

Summary

Approves a run that is awaiting human review, transitioning it to processing status and optionally publishing it.

Intent

Provides a human-in-the-loop (HITL) approval gate so that a reviewer can explicitly approve a run before it proceeds to publishing. This endpoint exists to support workflows where automated runs pause for human sign-off before their output is made live.

Parameters

Name	Type	Required	Description
runId	string	Yes	The unique identifier of the run to approve. Provided as a URL path segment.
customerId	string	No	Optional customer identifier. If provided, the run must belong to this customer or a 403 Forbidden error is returned.

Request example

curl -X POST https://maps.google.com//api/runs/run_abc123/approve \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customerId": "cust_456"}'

Response example

{
  "ok": true
}

Error cases

• 404 — No run exists with the given runId
• 403 — A customerId was provided in the request body but it does not match the customerId associated with the run
• 409 — The run exists but its current status is not ‘awaiting_review’ (e.g. it is already ‘processing’, ‘completed’, or ‘failed’)

Gotchas

• The run must be in exactly the ‘awaiting_review’ status before this endpoint can be called. Calling it on a run in any other status (including ‘processing’ or ‘completed’) will return a 409 Conflict.
• The customerId field in the request body is optional, but if supplied it must exactly match the customerId stored on the run. A mismatch returns 403 even if the token is otherwise valid.
• A successful approval immediately transitions the run status to ‘processing’ and emits a HITL_APPROVED event before any publish logic runs. There is no way to undo an approval via this API.
• If the server has a publishRun function configured, it will be invoked automatically after approval. The response returns { ok: true } regardless of whether publishing was triggered, so callers cannot distinguish between the two cases from the response alone.
• Auth is not enforced at the middleware level for this endpoint (auth required: false), but the optional customerId body parameter acts as a secondary ownership check.