Deterministic scoring primitives for automated decision workflows.

Quick Start

1. Get an API Key

Fastest path: mint an instant no-signup trial key with POST /v1/keys/trial (no auth required).

curl -X POST https://sentinelsignal.io/v1/keys/trial

Trial keys can call POST /v1/score, GET /v1/limits, and GET /v1/usage, then upgrade the same key via POST /v1/billing/checkout-session (Bearer trial key) when quota is exhausted.

Start free via dashboard self-serve signup/login, then create a key under /v1/control-plane/workspace/api-keys.

Admin-assisted issuance remains available via POST /v1/apikeys/issue.

Self-serve onboarding is available through dashboard auth endpoints: POST /v1/control-plane/auth/signup, POST /v1/control-plane/auth/login, and workspace/key lifecycle under /v1/control-plane.

One-time setup links remain available for admin-assisted onboarding.

Workspace rename/update uses POST /v1/control-plane/workspace with payload {"workspace_name":"..."}.

For paid plans, start Stripe Checkout from /portal/dashboard (self-serve), use POST /v1/billing/checkout-session (API-key-auth trial upgrade), or use POST /v1/billing/checkout/session (admin flow).

Include the key in all requests:

Authorization: Bearer YOUR_API_KEY

2. Make Your First Request

curl https://sentinelsignal.io/v1/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "healthcare.denial",
    "payload": {
      "external_claim_id": "CLM-SS-0001",
      "service_date": "2026-02-14",
      "provider_id": 1021,
      "payer_id": 44,
      "cpt_code": "99213",
      "icd10_code": "E119",
      "billed_amount": 250.00,
      "place_of_service": "11",
      "network_status": "in_network"
    },
    "options": {
      "operating_point": "high_recall",
      "distribution_profile": "commercial_beta"
    }
  }'

3. Response

{
  "workflow": "healthcare.denial",
  "score": 0.81,
  "risk_level": "high",
  "confidence": 0.92,
  "model_version": "0.3.3",
  "explanation": {
    "top_factors": [...]
  },
  "details": {
    "workflow": "healthcare.denial",
    "denial": {
      "denial_probability": 0.81,
      "operating_point": "high_recall",
      "distribution_profile": "commercial_beta",
      "routing_source": "explicit"
    }
  },
  "scored_at": "2026-02-14T12:00:00Z"
}

4. Check Usage and Limits

GET /v1/limits
GET /v1/usage

5. Submit Outcome Feedback (Optional)

Use the scoring response x-request-id when posting feedback telemetry:

POST /v1/feedback
{
  "request_id": "<x-request-id-from-score-response>",
  "endpoint": "denial",
  "observed_outcome": "denied",
  "expected_outcome": "paid",
  "confidence_mismatch": true,
  "notes": "Unexpected denial after review"
}

Feedback calls are telemetry-only and are not counted as billable scoring calls.

Core Concepts

Scoring Call

A scoring call is one successful 2xx response from a scoring endpoint. POST /v1/score is the primary path; legacy scoring endpoints are also billable.

Every successful scoring call increments metered usage for the authenticated API key.

OpenAPI marks billable scoring operations with x-billable: true and x-meter: scoring_calls.

Each call returns:

• score - unified score (probability for denial/prior-auth; normalized risk for reimbursement)
• risk_level - categorical interpretation
• confidence - model confidence estimate
• model_version - version identifier
• explanation - top contributing factors
• details - workflow-specific detail object (denial, prior_auth, reimbursement)

Each scoring response also returns an x-request-id header used for support correlation and feedback submission.

Determinism

Given:

• Identical payload
• Identical workflow
• Identical model_version

The output will be identical.

Versioning

Models are versioned.

Each response includes:

model_version

You may pin a version explicitly.

Optional request controls are passed in options (model_version, allow_fallback, operating_point, distribution_profile).

Denial supports regime-aware routing: set options.distribution_profile (synthetic_v1, cms_v1, commercial_beta) when known.

Regime-specific denial model pins are frozen in contracts for synthetic_v1 and cms_v1; runtime default remains commercial_beta.

If no explicit profile is provided, routing uses payload.data_source hint first, then auto-detection (CPT pattern, allowed-amount band, payer id bucket).

Denial responses include details.denial.distribution_profile and details.denial.routing_source for routing auditability.

Workflows

payload schema depends on workflow; validation is applied per workflow.

OpenAPI includes x-workflowSchemas metadata to map workflow ids to payload schemas.

healthcare.denial

Predicts claim denial risk using structured claim attributes.

Payload fields:

Future workflows will follow the same API surface.

Feedback API

POST /v1/feedback accepts structured, non-PHI outcome telemetry linked to prior scoring calls.

• request_id must be recent and must match the caller + endpoint family.
• notes are optional, short, and screened for PHI-like patterns.
• Validation is backed by persisted request-id events for multi-instance consistency.

Billing & API Key Lifecycle

• POST /v1/keys/trial - issue tightly-limited no-signup trial API key
• POST /v1/billing/checkout-session - create Stripe Checkout session using an API key (same-key trial upgrade)
• POST /v1/billing/checkout/session - create Stripe Checkout session (paid plans)
• POST /v1/billing/webhooks/stripe - receive Stripe lifecycle events
• GET /v1/control-plane/workspace/billing/status - dashboard session billing snapshot
• POST /v1/control-plane/workspace/billing/checkout/session - dashboard session Stripe Checkout session
• POST /v1/apikeys/issue - issue persistent API key
• POST /v1/apikeys/{api_key_id}/revoke - revoke key
• GET /v1/billing/accounts/{email}/usage - admin usage summary
• GET /v1/billing/accounts/{email}/status - admin billing status (plan, renewal, payment, key-state)
• POST /v1/control-plane/setup-links - create one-time setup link
• POST /v1/control-plane/setup-links/redeem - redeem setup link into dashboard session
• POST /v1/control-plane/auth/signup - self-serve workspace signup + session
• POST /v1/control-plane/auth/login - self-serve login + session
• POST /v1/control-plane/workspace - create/update workspace name ({"workspace_name":"..."})
• GET/POST /v1/control-plane/workspace/api-keys - self-serve key list/create
• POST /v1/control-plane/sessions/logout - revoke dashboard session token

Account-level usage reports are DB-backed and reflect flushed usage batches (eventually consistent within the batch flush interval).

Billing/account endpoints are managed by the token-service and appear in the integrated portal spec.

Errors

Standard HTTP codes:

• 400 - invalid request
• 401 - missing/invalid API key
• 402 - billing account inactive/payment issue, or trial quota exhausted (includes upgrade URL)
• 409 - requested model version unavailable with fallback disabled
• 429 - rate limit exceeded
• 500 - internal error

Feedback-specific validation errors use 422 (unknown/expired request_id, endpoint mismatch, or disallowed note content).

Example error response:

{
  "detail": "Requested model_version `0.9.9` is unavailable for workflow `healthcare.denial`."
}

Latest Validation Snapshot (2026-02-17 UTC)

• Local full 5-seed pack: denial 20/25, prior-auth 20/20, reimbursement 13/15, overall p95 latency 66.87 ms.
• Fly 5-seed fast pack: denial 20/25, prior-auth 20/20, reimbursement 11/15, overall p95 latency 3482.47 ms.
• Fly dual-machine rerun: cross-model 6/7, overall p95 latency 529.02 ms, latency gate < 500 ms narrowly missed.
• Fly dual-machine profile used in rerun: API 2 x shared 4 vCPU / 4096 MB, DB shared 4 vCPU / 4096 MB, token service shared 2 vCPU / 1024 MB (all iad).

Security Overview

• API auth is enabled by default with bearer token enforcement.
• Token issuance and API key lifecycle actions require admin token controls.
• TLS is enforced at the Fly edge via HTTPS-only app routing.
• Runtime readiness checks expose dependency status via /readyz.
• Observability endpoints: /metrics (Prometheus, public, text/plain; version=0.0.4; charset=utf-8) and /metrics.json (debug snapshot, schema 1, requires metrics:read scope).

OpenAPI

Machine-readable spec available at:

/openapi.json