Quickstart

Call Sentra's scoring API, inspect the decision, save a review case, and submit analyst feedback.

This quickstart shows the minimum integration path for using Sentra as a real-time Risk Control Intelligence service.

1. Choose environment

Mode	API base	Auth
Local demo	`http://localhost:8000`	Mock bearer token, such as `local-analyst` or `local-admin`
Production	Your AWS API or ALB URL	Cognito JWT with `Analyst` or `Admin` group

Health check:

curl "$SENTRA_API_BASE/healthz"

Expected response:

{ "status": "ok" }

2. Score a transaction

curl "$SENTRA_API_BASE/v1/risk/score" \
  -H "Authorization: Bearer $SENTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "tx_id": "m2txn_260605_001",
      "created_at": "2026-06-05T10:00:00Z",
      "amount": 84250,
      "currency": "BRL",
      "direction": "pay_out",
      "channel": "bank_transfer",
      "psp": "airwallex",
      "route_id": "route_latam_220",
      "status": "completed",
      "status_reason": "approved",
      "fee_total": 684.5,
      "fx_rate": 1
    },
    "entities": {
      "user_id": "user_1088",
      "merchant_id": "merchant_9001",
      "sender_entity_id": "user_1088",
      "receiver_entity_id": "merchant_9001",
      "sender_country": "BR",
      "receiver_country": "MX",
      "ip_hash": "ip_112233",
      "device_id_hash": "dev_445566"
    },
    "kyc_refs": [
      {
        "entity_id": "user_1088",
        "doc_hash": "doc_kyc_001",
        "doc_s3_url": "s3://sentra-kyc-docs/manual/example.txt",
        "text_blob": "Ownership unclear and passport mismatch observed in onboarding review."
      }
    ]
  }'

3. Interpret response

{
  "risk_score": 742,
  "decision": "HOLD",
  "reasons": [
    "Large ticket amount exceeds demo high-risk band",
    "Cross-border corridor increased review pressure"
  ],
  "evidence": [
    { "source": "field", "key": "amount", "quote": "84250" },
    { "source": "field", "key": "cross_border", "quote": "BR->MX" }
  ],
  "model_version": "sentra-score-xgb-v0.seed",
  "llm_version": "sentra-llm-qwen2.5-7b",
  "request_id": "req_or_uuid_value",
  "latency_ms": 42,
  "llm_status": "pending"
}

llm_status may be pending even when the scoring response succeeds. Sentra intentionally does not wait for LLM enrichment in the synchronous scoring path.

4. Apply platform behavior

Decision	Suggested behavior
`PASS`	Continue authorization, payout, or settlement flow.
`REVIEW`	Create a pending state and wait for analyst action.
`HOLD`	Freeze or delay settlement while verification continues.
`BLOCK`	Stop the transaction and show an internal support reason.

5. Save as a case

Manual scoring creates a risk_scores row. To force a transaction into the review queue, save it as a case:

curl "$SENTRA_API_BASE/v1/cases/from-score" \
  -H "Authorization: Bearer $SENTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tx_id": "m2txn_260605_001" }'

6. Submit feedback

After investigation, send a feedback label. Feedback is stored in the database; it does not trigger training directly.

curl "$SENTRA_API_BASE/v1/risk/feedback" \
  -H "Authorization: Bearer $SENTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_id": "m2txn_260605_001",
    "label_type": "false_positive",
    "label_value": 1,
    "source": "manual",
    "note": "Analyst confirmed legitimate high-value vendor payout."
  }'

7. Use the Console

Open Sentra Console:

/manual-score: test the scoring contract.
/cases: monitor escalated transactions.
/cases/{case_id}: review evidence, notes, feedback, and AI signal status.
/admin: manage thresholds, data imports, models, and the data contract.