Skip to content
SupaCloud Docs
Select themeSelect language

GET /api/operator/v1/routing — the routing decision-log BOARD (explainability), on the #358 `{items,total,facets}` contract. Returns a server-paginated, filtered + sorted page of `backlog_routing_decisions` (each enriched with the chosen profile name, candidate count, item state + a reason summary) plus the pager total and optional facet chips. `?workspace_id=` filters to one workspace; absent reads cross-tenant. `q`/`sort`/`dir`/`limit`/`offset`/`include_facets`/`since`/`until` drive the board.

GET
/api/operator/v1/routing
curl --request GET \
  --url https://example.com/api/operator/v1/routing

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
workspace_id
string format: uuid
q
string

Free-text search over the owning item’s title.

routing_source
string

routing_source filter (classify|escalate|fallback|manual).

item_state
string

backlog_items.state filter (the routing outcome).

sort
string

Whitelisted sort key: created_at|item_title|routing_source|outcome.

dir
string

Sort direction: asc | desc (default desc).

limit
integer format: int64
offset
integer format: int64
include_facets
boolean

Include the facet chips (by_source/by_state + total) in the response.

since
string format: date-time

Range start (inclusive) on the decision’s created_at.

until
string format: date-time

Range end (inclusive) on the decision’s created_at.

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

One page of the routing board: the filtered + paged rows, the pager total, and (optionally) the facet chips — the #358 {items, total, facets} envelope.

object
facets
One of:
null
items
required
Array<object>

One routing decision-log entry (reader of backlog_routing_decisions, mig 212). decision_factors is the verbatim JSON the classifier / escalation wrote — the operator-facing explainability of WHY the item dispatched / which model was chosen / why it was paused. routing_source is the path that produced it (classify|escalate|fallback|manual).

object
candidate_count

#626 Operations — the number of candidate profiles the router chose among (the multi-agent work-lane size), or None when no explicit candidate set was recorded (single-agent path). Honest-NULL — never a fabricated 1.

integer | null format: int64
chosen_profile_name

#626 Operations — the name of the profile the router bound to the item (agent_profiles.name), or None for a single-agent fallback / un-routed item.

string | null
created_at
required
string format: date-time
decision_factors
required
object
key
additional properties
id
required
string format: uuid
item_id
required
string format: uuid
item_state

#626 Operations — the owning item’s CURRENT lifecycle state (the routing “outcome” the operator console renders), or None if unreadable.

string | null
item_title
string | null
project_id
required
string format: uuid
reason_summary

#626 Operations — a short human-readable summary of WHY the item routed as it did, derived from decision_factors (the escalation reason, or a classify-path summary of severity + routed effort). None when nothing summarizable was recorded.

string | null
routing_source
required
string
total
required
integer format: int64
Examplegenerated
{
  "facets": {
    "by_source": [
      {
        "count": 1,
        "value": "example"
      }
    ],
    "by_state": [
      {
        "count": 1,
        "value": "example"
      }
    ],
    "total": 1
  },
  "items": [
    {
      "candidate_count": 1,
      "chosen_profile_name": "example",
      "created_at": "2026-04-15T12:00:00Z",
      "decision_factors": {
        "additionalProperty": "example"
      },
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "item_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "item_state": "example",
      "item_title": "example",
      "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "reason_summary": "example",
      "routing_source": "example"
    }
  ],
  "total": 1
}