Signal API reference

Signal exposes tenant-scoped standing data through the Paybond Gateway. Use it to retrieve signed operator receipts, inspect score history, review portfolio rollups, and export signed tenant snapshots for partner verification and audit workflows where the tenant plan and signing configuration enable those surfaces.

This page focuses on what the API does and how to use it. The interactive reference on /docs/api/signal remains the canonical contract for request and response shapes.

What Signal is for

Signal is designed for teams that need verifiable standing rather than internal-only analytics. Common uses include:

checking the latest signed receipt for one operator
reviewing score movement and supporting metrics over time
triaging operators that need manual review
sharing a signed tenant portfolio snapshot with partners or internal reviewers
tracing a score or review decision back to the underlying Paybond provenance

Signal is private to the authenticated tenant. It is not a public reputation feed or cross-tenant leaderboard.

Authentication and tenant scope

All Signal routes are served through the Paybond Gateway and require an authenticated session with access to Signal.

Tenant scope always comes from the authenticated session.
Caller-supplied tenant identifiers are treated as hints, not as authority.
Cross-tenant access is never part of the product contract.
Most Signal routes require the private-dashboard entitlement and Signal read permissions; write-style review and release-gate routes require stronger tenant roles.

Route groups

Operator receipt

GET /reputation/{operator_did}?score_version=...

Returns the signed receipt for one operator under the current score model or a supported historical version. This is the main endpoint to use when another system needs a portable standing artifact for one operator.

Expect a signed receipt envelope with:

the scoring family and score-model version
outcome-driven metrics and reason codes
the operator score
signature material required for independent verification

404 means the operator does not yet have a receipt for the requested score model.

Portfolio views and exports

GET /signal/v1/overview

Returns the tenant's current Signal portfolio view, including rollups, current operator scores, and review-policy context that helps teams decide whether to clear, defer, or inspect an operator.

GET /signal/v1/portfolio/summary?score_version=...

Returns a compact aggregate for one score model, including operator counts, average score, and settlement volume totals.

GET /signal/v1/portfolio/signed-export?score_version=...

Returns a signed tenant portfolio snapshot that can be moved into partner review, audit, or compliance workflows. The artifact is tenant-scoped, intentionally private, and available only when Gateway has Signal artifact signing configured.

Operator history and review detail

GET /signal/v1/operators/{operator_did}/trend?score_version=...&limit=...

Returns append-only score history for one operator. Use it for trend charts, case review, and historical comparisons.

GET /signal/v1/operators/{operator_did}/explanation?score_version=...

Returns the current explanation surface for one operator, including support and confidence data and the signed score-change delta when available.

GET /signal/v1/operators/{operator_did}/review-status?score_version=...

Returns the current review posture for one operator, including review state, decision band, assurance posture, shadow-risk annotations, friction controls, recent review-related events, fraud_signals, and a compact fraud_assessment. Fraud signals are score-neutral and never rewrite the signed score.

GET /signal/v1/operators/{operator_did}/score-model-versions

Returns the historical score-model versions preserved for that operator so clients can offer a version picker or compare older receipts.

Review workflows

GET /signal/v1/review-queue?state=open&score_version=...&fraud_severity=high&sort=fraud_severity

Returns the tenant-scoped queue of operators that need attention because of low support, anomaly signals, assurance posture, or fraud signals. Use fraud_severity=elevated|high|critical to filter to operators with at least that severity, sort=fraud_severity to prioritize severe fraud signals, and state=all to include all review states.

GET /signal/v1/fraud-signals?score_version=...

Returns active, tenant-scoped settlement-abuse indicators. The fraud_signals entries summarize shadow risk, predicate failures, dispute clustering, principal cycling, intent churn, high-value-first behavior, and rail-switching patterns. Every entry has affects_score=false; these indicators route review and do not alter the canonical score. In fraud_signal_version=1.0.7, entries can also include additive review metadata: signal_source, first_seen_at, last_seen_at, evidence_binding_strength, provider_event_refs, and intent_refs.

Signal scoring uses Harbor outcome rows (released, refunded, disputed) once per intent. Gateway dispute-case statuses such as split resolution or external escalation are review context, not score inputs for score_version=1.0.

GET /signal/v1/fraud/metrics?window=24h|7d|30d&score_version=...

Returns tenant-scoped fraud backtesting and monitoring metrics for developer dashboards and API clients: flagged operator count, critical/high/elevated signal counts, active review load, reviewed outcome count, labeled_outcome_count, confirmed-risk count, false-positive count, needs-more-evidence count, review precision, false_positive_rate_bps, confirmed-risk rate, labeled_coverage_bps, median time-to-review seconds, refund-burst count, dispute-cluster count, replay/appeal abuse count, critical_signal_hold_candidate_count, provider_signal_count, stale_label_gap_seconds, stale_signal_family_label_gap_count, backtest_summary, and the 30-day release-gate metrics reliability floor. Outcome counts prefer the explicit review_outcome values confirmed_risk, false_positive, and needs_more_evidence, with legacy reason tags such as CONFIRMED_RISK and FALSE_POSITIVE used as fallback.

GET /signal/v1/fraud/release-gate?score_version=...

Returns the tenant's release-gate config and whether the tenant's fraud review feedback is reliable enough for critical-signal release holds. Missing config defaults to mode=review_only.

PUT /signal/v1/fraud/release-gate

Updates the tenant-scoped release-gate mode. mode=review_only is the default and only routes review. mode=critical_hold is tenant-admin only and can hold Harbor release attempts for operators with active critical fraud signals, but only when 30-day tenant reliability is fresh and sufficient and the active signal family has enough signal-level labels.

POST /signal/v1/operators/{operator_did}/review-events?score_version=...

Records an authenticated review workflow event such as opening review, requesting appeal, requesting replay, or recording a review outcome. Outcome writes use event_type=review_outcome_recorded with review_outcome=confirmed_risk|false_positive|needs_more_evidence and update the tenant-local feedback loop used by fraud metrics and trust-policy calibration. Outcome events can also carry optional signal-level context: signal_code, intent_id, and provider_event_id; Gateway validates tenant/operator binding for supplied intent and provider event refs before writing. These events are auditable and may be throttled, but they do not rewrite the signed score.

Tenant operations surfaces

GET /signal/v1/fairness

Returns the latest tenant-scoped processing and fairness posture for Signal work assigned to the tenant's current slice. This helps operators understand whether current review or ingest behavior is normal, constrained, or recovering.

GET /signal/v1/shadow-readiness

Returns tenant-scoped readiness evidence for Paybond's shadow comparison and operational review surfaces. This route is intended for advanced investigation and support workflows, not for partner-facing sharing.

Audit provenance

GET /audit?...

Returns tenant-scoped provenance events that connect Harbor intents and Signal operator records. Use it when a reviewer needs to trace a standing outcome back to its underlying evidence trail.

Signed artifacts and versioning

Signal responses include version fields so clients can safely reject unknown contracts before relying on them.

When handling a signed receipt or portfolio artifact:

Check schema_version before parsing deeply.
Check the score-model version your client supports.
Verify the signature before trusting score, reason codes, or digests.
Treat unsupported future versions as unknown rather than guessing.

Product boundaries

Signal artifacts are tenant-bound and private by default.
Review controls and operational posture do not silently rewrite the canonical signed score.
Fraud release gating defaults to review-only, fails open for stale or sparse metrics, and does not activate critical holds until tenant-level and signal-family evidence are reliable.
Signal does not turn unauthenticated request fields into tenant authority.