POST /v1/routing/explain

The endpoint uses the same Feedback-driven and Smart Cost planners as live routing, including feature/master switches, actual history, constraints and shadow approval. It does not dispatch models, emit a request/response log, or increment rotation/usage counters. The authenticated audit event and explain rate budget still apply.

Request

Send a chat request directly as the JSON body, with ordinary HTTP headers. The endpoint does not accept a wrapper containing request, locale or headers.

curl -s https://api.floopy.ai/v1/routing/explain \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -H "floopy-routing-rule: $ROUTING_RULE_ID" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Summarise this report."}]}'

floopy-routing-rule selects an organization-scoped rule before optimization. Reserved identity/internal headers are removed from the simulated context. Unknown body fields return 400 unknown_field; invalid chat data returns 400 invalid_body.

Response

The audit is nested under audit. This illustrative untested trial keeps Feedback-driven as the governing strategy:

{
  "dry_run": true,
  "would_select": {"provider":"openai","model":"gpt-4o-mini"},
  "confidence": 0.0,
  "confidence_reason": "insufficient_samples",
  "firewall_decision": "pass",
  "audit": {
    "strategy_id": "feedback_driven",
    "reason": "would_dispatch",
    "phase": "auto",
    "exploration_draw": "explore_untested",
    "exploration": "explore_untested",
    "exploration_rate_effective": 0.2,
    "history_available": true,
    "winner_origin": "smart_cost_candidate",
    "winner": {"provider":"openai","model":"gpt-4o-mini"},
    "candidates": [
      {"provider":"openai","model":"gpt-4o-mini","score":0.61},
      {"provider":"openai","model":"gpt-4o","score":0.86}
    ],
    "filtered": []
  }
}

Field	Meaning
`would_select`	First proposed provider/model; null when blocked or unresolved.
`audit.strategy_id`	Governing policy. Joint mode is `feedback_driven`.
`audit.smart_cost`	Optional participation, baseline, chosen pair, complexity and effective reason.
`audit.exploration_draw`	Band drawn before pool availability and constraints.
`audit.exploration`	Effective selection band; can be exploit when a drawn exploration pool is empty.
`audit.history_available`	Distinguishes usable empty history from a failed query.
`audit.winner_origin`	`approved_target` or `smart_cost_candidate` for optimized routing.
`audit.candidates` / `audit.filtered`	Proposed dispatch chain and rejected candidates.
`audit.evidence.samples_in_window`	Actual winner’s sample count.
`audit.evidence.recent_regressions`	Tagged count: `{ "kind": "exact", "n": 0 }`, or `{ "kind": "at_least", "n": 10 }`.
`confidence` / `confidence_reason`	Confidence for the proposed winner; insufficient data can yield zero.
`explanation`	Localized rendered text and template ID.

In joint mode, candidate scores represent Feedback-driven quality; audit.smart_cost.model_score, when available, records cost utility separately. audit.smart_cost.savings_estimate is zero during planning/explain because token usage is unknown. Live request logs populate it after usage is known, in microdollars. Bypass does not remove quality, cost or shadow constraints.

Content-Language identifies the locale selected from Accept-Language. The firewall runs under the same plan/header gates; blocked requests return 200 with no proposed winner and a firewall filter reason.

Selection is reproducible internally with the same request seed, configuration and evidence snapshot. Each HTTP explain call gets a new request ID and current evidence, so exploratory calls can differ. Round-robin peeks without advancing its counter; concurrent live traffic can change the next turn. Provider failures, retries and stream outcomes are not simulated. Active MCP agent loops return audit.reason: "agent_loop_not_simulated" without a fabricated winner; send floopy-mcp-disabled: true to inspect the ordinary strategy chain.

Availability and limits

The endpoint requires the audit API kill switch and eligible plan/permissions. Its budget is 30 calls/minute per organization and 10 per API key; the body cap is 64 KiB. Rejected feature/permission checks return 403, the kill switch returns 404, and exceeded budgets return 429.

See routing decision flow, constraints, and confidence.