paybondpaybond
Sign in

Signal API reference

Reputation receipts, score snapshots, portfolio artifacts, and audit provenance exposed by Signal (via the Paybond Gateway).

Signal API reference

Signal turns Harbor's ledger events into deterministic operator scores and signed receipts. All reads go through the Paybond Gateway, scoped to the authenticated tenant realm. The scoring contract itself is frozen in docs/signal/score-model-v1.md.

Every response includes schema_version and score_model_version (1.0 today). Parsers must reject unknown schema_version before verifying signatures.

Route map

All routes require a session Bearer JWT with signal.read RBAC (or an audited support session). Tenant scope is derived from the tid claim and is the filter on every database query.

Reputation receipt

GET /reputation/{operator_did}?score_version=1.0

Returns a signed receipt for one operator under the active score model (or the explicitly requested score_version).

Response envelope: { schema_version, updated_at, receipt }. Each receipt carries:

  • scoring_model (paybond.signal.v1), score_version (1.0), receipt_version (3).
  • metrics — terminal counts, rate basis points, latency, receipted volume.
  • receipt_version = 3 rows additionally carry confidence, support_depth, review_state, and explanation_delta.
  • score (0–1000), plus canonical signing material (signing_algorithm = ed25519-sha256-json-v1, signing_public_key_hex, signature_hex, message_digest_hex).

404 is returned when no row exists for this operator under the requested score model. The gateway never upserts receipts on read; absence means "never scored in this model".

Portfolio rollups

GET /signal/v1/overview

Tenant-wide rollups plus each operator's current score. Used by the admin Signal workbench.

The overview response now also carries the tenant-scoped trust-policy contract:

  • trust_policy_version — explicit version for automated reliance and deferral behavior
  • trust_policy_calibration — tenant-scoped threshold window, routing precision, and drift counters
  • trust_policy_health — whether the current routing posture is healthy, degraded, sparse, or stale
  • trust_policy_control — rolling backtest window, routing mode, and explicit sequential risk-budget posture
  • each operator row may include trust_policy with decision_band (clear, review_recommended, review_required) plus routing reasons
  • each operator row may include operator_assurance with a separate assurance tier, explicit reason set, key-health posture, and recommended review priority or friction

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

Aggregates (operator count, average score, total terminal intents, total receipted volume) for one score model.

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

Signed JSON portfolio artifact for partner verification (requires PAYBOND_SIGNAL_ARTIFACT_SIGNING_KEY_HEX on the Gateway). Operators are sorted by operator_did for canonical JSON signing. Each row: { operator_did, score, ledger_watermark_seq, receipt_message_digest_hex }.

Score history

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

Append-only score snapshots for a single operator. Returns snapshots[] with snapshot_seq, ledger_watermark_seq, score, metrics, reason_codes, and captured_at. The server caps limit to 200.

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

Operator-facing support/confidence metadata, the current trust-policy decision band, and the signed “why did this move?” delta derived from the previous stored snapshot. Older pre-v3 receipts return 404 instead of being silently reinterpreted as review-bearing artifacts.

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

Explicit review state (none, open, in_review, closed) plus the anti-gaming trust-policy surface for the tenant-scoped operator row:

  • trust_policy — current decision_band, version, operator-readable reasons, and the calibration / health snapshot used for this decision
  • trust_policy.control — rolling backtest status, routing mode (healthy, constrained, failsafe), and false-clear / routing-mismatch budgets that can force safer review posture
  • operator_assurance — additive identity-assurance posture derived from tenant-scoped credential provenance, verified-domain or IdP binding, key-health inputs, and suspicious identity structure
  • shadow_risk — tenant-scoped graph / temporal manipulation findings, review priority, related operators, and recommended friction posture
  • maturity_tier from durable support factors already present in Signal
  • canonical_input_policy stating that only signed terminal settlement evidence affects score_version = 1.0
  • active_annotations for shadow anomaly or manipulation flags
  • friction and recent_events for replay, appeal, and review-open controls, including any assurance-driven tightening

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

Authenticated workflow request for review_open_requested, appeal_requested, or replay_requested. The gateway records an auditable event and returns 202 when accepted or 429 when throttled by the current policy window. These events do not change the canonical score.

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

All historical score_version rows preserved for that operator (version picker).

GET /signal/v1/review-queue?state=open&score_version=…

Tenant-scoped queue view over explicit review rows for low-support, anomaly-triggered, or assurance-limited outcomes. Rows may now include both shadow_risk and operator_assurance, and the queue is ordered so higher shadow-risk or assurance review priority surfaces first within the authenticated tenant.

Fairness controller

GET /signal/v1/fairness

Returns the latest tenant-scoped adaptive fairness-controller decision for the active shared-SaaS slice. The response includes mode, workload class, lag severity, requested / recommended / applied page quotas, operator-readable reason codes, and a rollback hint. The surface is intentionally tenant-scoped: it may describe slice pressure, but it must not reveal another tenant's identifiers or raw workload values.

Shadow shared-indexer readiness

GET /signal/v1/shadow-readiness

Returns the latest tenant-scoped shadow shared-indexer readiness artifact for the authenticated tenant. The surface is evidence-only and keeps the current topology decision explicit:

  • current and shadow observations are compared with stable per-operator receipt digests
  • strict parity requires tenant, score-model version, checkpoint, operator set, receipt version, watermark, and digest equality
  • diff.status = checkpoint_gap means receipt digests match but checkpoint parity is still open
  • fairness and rollback evidence are carried as separate gates
  • review_eligible = true means the topology decision record may be reopened for review, not that production cutover is approved
  • cutover_approved remains false on this surface

Operator-level diff items are tenant-scoped only. The route must not expose another tenant's operators, receipts, or workload shape.

Audit provenance

GET /audit?…

Tenant-scoped Signal provenance events joining Harbor intent rows to Signal operator rows. Each event exposes harbor_intent_path and signal_operator_path so investigations can cross-link the ledger and Signal canonicals without guessing identifiers.

Parsing contract

The admin console validates every response before rendering with apps/admin/lib/signal.ts. External consumers should follow the same shape:

  1. Reject non-object top-level JSON.
  2. Reject missing/null schema_version, tenant_id, score_model_version.
  3. Verify Ed25519 signatures on any receipt or signed artifact before trusting score.
  4. Treat score_version != "1.0" as unknown until docs/signal/score-model-v1.md is updated.

Tenant & security

  • Cross-tenant reads are a severity-zero defect — the Gateway filters by JWT tid on every query.
  • Signal never trusts unauthenticated tenant identifiers in request bodies or query strings; tenant_id fields on wire objects are output only, derived from authenticated context.
  • Rollups are ingested idempotently from the Harbor ledger (ON CONFLICT DO NOTHING); lowering the checkpoint alone does not re-apply counters. Controlled tenant rebuilds require PAYBOND_SIGNAL_ALLOW_DESTRUCTIVE_RESET=true and PAYBOND_SIGNAL_RESET_MODE=full_tenant_signal on the indexer.
  • Review-event throttles key on the authenticated tenant realm and operator row together. There is no global cross-tenant appeal or replay bucket.