API Reference

The FlowClaw Control API powers the Merchant Portal, Admin / Operator Portal, runtime assistant, route sessions, evidence workflows, artifacts, and audit views.

Protected routes resolve an actor context, active tenant, and role before doing work. The frontend normally sends credentials and an active tenant header.

Auth Model

The API can resolve identity from:

• Supabase bearer auth
• local cookie/session auth
• configured development identity headers in non-production environments

Product role names map to legacy code enums:

Product role	Code enum
Platform Admin	admin
Desk Operator	operator
Merchant Client	customer
Settlement Agent	verified_agent

Auth And Current User

Method	Path	Purpose	Request / response
GET	/auth/config	Return browser-safe auth configuration.	BrowserAuthConfig
POST	/auth/login	Local email/password login when local auth is enabled.	LoginRequest, AuthenticatedSession
POST	/auth/logout	Revoke session and clear cookie.	204
GET	/auth/session	Return current authenticated session.	AuthenticatedSession
POST	/auth/active-tenant	Switch active Operator Company workspace.	AuthenticatedSession
GET	/me/profile	Return current user profile.	CurrentUserProfile
GET	/me/memberships	Return current user's tenant memberships.	List[MembershipSummary]

Payment Requests And Sessions

Method	Path	Purpose	Request / response
POST	/payment-request	Create a route session, generate routes, evaluate policy, and return session audit.	PaymentRequest, SessionAudit
GET	/sessions	List sessions visible to the actor.	List[SessionAudit]
GET	/sessions/{session_id}	Get one visible session.	SessionAudit
POST	/sessions/{session_id}/approve	Approve or accept a route, depending on actor and surface.	SessionAudit
POST	/sessions/{session_id}/resume	Resume paused, failed, or degraded execution after review.	SessionAudit
POST	/sessions/{session_id}/steps/{step_id}/complete	Alias for manual step completion.	SessionAudit
POST	/sessions/{session_id}/steps/{step_id}/confirm	Confirm a manual step with proof.	ManualStepCompletionRequest, SessionAudit
POST	/sessions/{session_id}/assignments	Claim or assign session work.	SessionAssignmentRequest, SessionAudit
GET	/operator/queue	List queue items for operator/admin console.	List[QueueItem]
GET	/me/pending-actions	List pending actions for current actor.	List[QueueItem]

Runtime Assistant

Method	Path	Purpose	Request / response
POST	/runtime/requests	Send a workspace or session-scoped runtime request.	RuntimeUserRequest, RuntimeUserResponse
GET	/runtime/artifacts	List runtime artifacts.	List[RuntimeArtifact]
GET	/runtime/artifacts/{artifact_id}	Fetch one runtime artifact.	RuntimeArtifact

Provider Accounts

Method	Path	Purpose	Request / response
POST	/provider-accounts/connect	Prepare or record provider account connection.	ProviderAccount
GET	/provider-accounts	List provider accounts visible to actor.	List[ProviderAccount]
POST	/provider-accounts/{provider_account_id}/revalidate	Revalidate a provider account.	ProviderAccount

Artifacts

Method	Path	Purpose	Request / response
GET	/sessions/{session_id}/artifacts	List session artifacts.	List[SessionArtifact]
GET	/artifacts/{artifact_id}/download	Download artifact through backend-mediated access.	Endpoint
POST	/sessions/{session_id}/steps/{step_id}/artifacts	Attach artifact metadata/reference.	SessionArtifact
POST	/sessions/{session_id}/steps/{step_id}/artifacts/upload	Upload proof artifact file.	SessionArtifact

Route Cases

Method	Path	Purpose	Request / response
POST	/pilot-cases	Create a route case.	PilotCaseCreateRequest, PilotCaseResponse
GET	/pilot-cases	List visible route cases.	List[PilotCaseSummaryResponse]
GET	/pilot-cases/{pilot_case_id}	Get one route case.	PilotCaseResponse
POST	/pilot-cases/{pilot_case_id}/manual-route	Record manual route evidence.	PilotManualRouteRequest
GET	/pilot-cases/{pilot_case_id}/manual-route	Get manual route evidence.	PilotManualRouteResponse
POST	/pilot-cases/{pilot_case_id}/flowclaw-recommendation	Create/store FlowClaw recommendation evidence.	PilotFlowClawRecommendationRequest
GET	/pilot-cases/{pilot_case_id}/flowclaw-recommendation	Get FlowClaw recommendation evidence.	PilotFlowClawRecommendationResponse
POST	/pilot-cases/{pilot_case_id}/route-quotes	Record quote evidence.	PilotRouteQuoteRequest
PATCH	/pilot-cases/{pilot_case_id}/route-quotes/{quote_id}/evidence-source-type	Update quote evidence source type.	Endpoint
GET	/pilot-cases/{pilot_case_id}/route-quotes	List route quote evidence.	List[PilotRouteQuoteResponse]
GET	/pilot-cases/{pilot_case_id}/quote-comparison	Compare FlowClaw route against quotes.	PilotQuoteComparisonResponse
POST	/pilot-cases/{pilot_case_id}/proof-evidence	Attach proof evidence.	PilotProofEvidenceRequest
GET	/pilot-cases/{pilot_case_id}/proof-evidence	List proof evidence.	List[PilotProofEvidenceResponse]
GET	/pilot-cases/{pilot_case_id}/proof-evidence/{pilot_proof_evidence_id}/download	Download proof evidence artifact.	Endpoint
PUT	/pilot-cases/{pilot_case_id}/outcome	Record outcome.	PilotOutcomeRequest
PUT	/pilot-cases/{pilot_case_id}/outcome-scores	Record confidence and clarity scores.	Endpoint
PUT	/pilot-cases/{pilot_case_id}/quality-flags	Record missing obvious route or hallucination flags.	Endpoint
GET	/pilot-cases/{pilot_case_id}/outcome	Get outcome.	PilotOutcomeResponse

Route Readiness And Governance

Method	Path	Purpose	Request / response
GET	/pilot-cases/proof-quality	Review proof completeness and exclusions.	PilotProofQualityReviewResponse
GET	/pilot-cases/outcome-evidence	Review outcomes and quality evidence.	PilotOutcomeEvidenceReviewResponse
GET	/pilot-readiness/stage-0-evidence	Review historical route case evidence.	PilotStageEvidenceReviewResponse
GET	/pilot-readiness/stage-1-evidence	Review current quote evidence.	PilotStageEvidenceReviewResponse
GET	/pilot-readiness/stage-2-readiness	Check Stage 2 readiness status.	PilotStage2ReadinessResponse
POST	/pilot-readiness/controlled-probe-preparations	Check controlled route review preparation.	PilotControlledProbePreparationResponse
POST	/pilot-readiness/decisions	Record readiness decision.	PilotReadinessDecisionRequest
GET	/pilot-governance/pilot-cases/{pilot_case_id}/evidence	Build governance evidence bundle.	PilotGovernanceEvidenceResponse

Controlled Route Review

Method	Path	Purpose	Request / response
PUT	/pilot-cases/{pilot_case_id}/controlled-probe/rail-ownership	Record rail ownership acknowledgement.	ControlledProbeRailOwnershipResponse
POST	/controlled-probe-settlement-legs	Assign settlement leg to Settlement Agent.	ControlledProbeSettlementLegResponse
PUT	/pilot-cases/{pilot_case_id}/controlled-probe/completion	Record completion proof.	ControlledProbeCompletionResponse
PUT	/pilot-cases/{pilot_case_id}/controlled-probe/actuals	Record actual fee/timing/outcome.	ControlledProbeActualsResponse
GET	/pilot-cases/{pilot_case_id}/controlled-probe/actuals	Get controlled probe actuals.	ControlledProbeActualsResponse

Settlement Agent

Method	Path	Purpose	Request / response
GET	/settlement-agent/controlled-probe-legs	List assigned settlement legs.	List[ControlledProbeSettlementLegResponse]
GET	/settlement-agent/controlled-probe-legs/{settlement_leg_id}	Get one assigned settlement leg.	ControlledProbeSettlementLegResponse
POST	/settlement-agent/controlled-probe-legs/{settlement_leg_id}/proof	Submit proof for assigned leg.	ControlledProbeSettlementLegResponse
POST	/settlement-agent/controlled-probe-legs/{settlement_leg_id}/route-approval	Always denied. Settlement Agents cannot approve routes.	Endpoint
POST	/settlement-agent/controlled-probe-legs/{settlement_leg_id}/policy-bypass	Always denied. Settlement Agents cannot bypass policy.	Endpoint

Merchant-Safe Case Views

Method	Path	Purpose	Request / response
POST	/pilot-cases/{pilot_case_id}/merchant-visibility	Assign/publish a route case to a Merchant Client.	PilotCaseResponse
GET	/merchant/pilot-cases	List assigned merchant-visible cases.	List[MerchantPilotCaseResponse]
GET	/merchant/pilot-cases/{pilot_case_id}	Get one assigned merchant-visible case.	MerchantPilotCaseResponse

Audit And Static UI

Method	Path	Purpose	Request / response
GET	/audit/log	List tenant-scoped audit entries.	List[Dict]
GET	/index.html	Serve Platform Admin / Desk Operator console.	Endpoint
GET	/customer.html	Serve legacy Merchant Portal route.	Endpoint
GET	/merchant.html	Serve preferred Merchant Portal route.	Endpoint
GET	/	Serve root route.	Endpoint

Important Schemas

Schema	Purpose
PaymentRequest	Route request input.
SessionAudit	Session response and audit view.
ManualStepCompletionRequest	Proof-based manual step confirmation.
SessionAssignmentRequest	Session assignment/claim request.
PilotCaseCreateRequest	Route case creation.
PilotManualRouteRequest	Manual route evidence.
PilotFlowClawRecommendationRequest	Recommendation evidence.
PilotRouteQuoteRequest	Quote evidence.
PilotProofEvidenceRequest	Proof evidence.
PilotOutcomeRequest	Outcome record.
PilotReadinessDecisionRequest	Governance readiness decision.
MerchantPilotCaseResponse	Merchant-safe pilot case view.
RuntimeUserRequest	Runtime assistant input.