AI-Agent Integration Kit (v1)

Status: Active
Version: v1.1.0
Last updated: 2026-03-03

This kit is the fastest path for AI agents and integrators to reach first value using the public API contract.

Companion docs:

OpenAPI contract: docs/api/openapi/rgl8r-public-api-v1.1.0.yaml
Public API contract pack: docs/api/public-api-contract-v1.md
Channel playbooks: docs/api/playbooks/ai-channel-playbooks-v1.md

Prerequisites

Set these env vars:


export BASE_URL="https://rgl8r-staging-api.onrender.com"
export RGL8R_INTEGRATION_KEY="sk_int_..."

Notes:

Use staging first.
POST /api/auth/token/integration requires header x-api-key.

Canonical 3-Flow Quickstart

Flow 1: Exchange integration key for bearer token


TOKEN_JSON=$(curl -sS -X POST "$BASE_URL/api/auth/token/integration" \
  -H "x-api-key: $RGL8R_INTEGRATION_KEY")
 
export RGL8R_BEARER_TOKEN=$(echo "$TOKEN_JSON" | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")

Expected success shape:


{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "default_adapter": "catalog-excel"
}

Flow 1.5 (optional): Create billing setup session

Use this flow when onboarding a tenant for Stripe payment method capture.


curl -sS -X POST "$BASE_URL/api/public/billing/setup-session" \
  -H "Authorization: Bearer $RGL8R_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"billingEmail":"billing@example.com"}'

Expected 201 shape:


{
  "tenantId": "<tenant-uuid>",
  "setupIntentId": "seti_...",
  "clientSecret": "seti_..._secret_...",
  "stripeCustomerId": "cus_..."
}

Flow 2: Enqueue screening work

Use SIMA batch to avoid file-upload handling in first integration.


ENQUEUE_JSON=$(curl -sS -X POST "$BASE_URL/api/sima/batch" \
  -H "Authorization: Bearer $RGL8R_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"skus":null,"runPolicy":"always","screeningAuthority":"US"}')
 
export RGL8R_JOB_ID=$(echo "$ENQUEUE_JSON" | python3 -c "import sys,json;print(json.load(sys.stdin)['jobId'])")

Expected 202 shape:


{
  "jobId": "<uuid>",
  "status": "PENDING",
  "message": "Batch validation started"
}

Flow 3: Poll job status, then fetch results


# Poll every 3s for up to 40 attempts (~2 min)
for i in $(seq 1 40); do
  JOB_JSON=$(curl -sS "$BASE_URL/api/jobs/$RGL8R_JOB_ID" \
    -H "Authorization: Bearer $RGL8R_BEARER_TOKEN")
  STATUS=$(echo "$JOB_JSON" | python3 -c "import sys,json;print(json.load(sys.stdin)['status'])")
  echo "attempt=$i status=$STATUS"
  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
    break
  fi
  sleep 3
done
 
# Fetch SIMA outcomes
curl -sS "$BASE_URL/api/sima/results?limit=20" \
  -H "Authorization: Bearer $RGL8R_BEARER_TOKEN"

Retry + Backoff Contract

Recommended policy:

Token exchange: retry up to 3 times on 429/5xx using exponential backoff with jitter (1s, 2s, 4s base).
Enqueue: retry once on 5xx; do not blind-retry indefinitely.
Polling: every 2-3s in first minute, then every 5-10s with jitter.
Terminal states: COMPLETED, FAILED.
Non-terminal states: PENDING, PROCESSING.

Minimal Code Examples

TypeScript: docs/api/examples/rgl8r_quickstart.ts
Python: docs/api/examples/rgl8r_quickstart.py

Both examples implement token -> enqueue -> poll -> fetch.

Postman Quickstart

Collection: docs/postman/RGL8R-Agent-Quickstart.postman_collection.json
Environment: docs/postman/RGL8R-Agent-Quickstart.postman_environment.json

Collection variables:

base_url
integration_key
bearer_token
job_id

Expected Terminal Response Shapes

`GET /api/jobs/:id` success


{
  "id": "<uuid>",
  "type": "sima_validation",
  "status": "COMPLETED",
  "progress": 100,
  "result": {},
  "reconciliation": {},
  "skippedRows": {},
  "warnings": null,
  "outcomes": {
    "atRisk": 0,
    "cleared": 0,
    "needsReview": 0,
    "falsePositive": 0
  },
  "error": null,
  "createdAt": "2026-02-24T00:00:00.000Z",
  "updatedAt": "2026-02-24T00:00:00.000Z"
}

canonical error envelope


{
  "code": "INVALID_REQUEST",
  "message": "...",
  "details": {}
}

Troubleshooting

Symptom	Likely cause	Action
`401 INVALID_API_KEY` on token exchange	bad key	rotate/reissue key and retry
`401 INVALID_TOKEN` on tenant endpoints	bearer expired/invalid	re-run token exchange
`403 SCOPE_DENIED`	missing scope (for scoped endpoints like carrier upload)	reissue key with required scopes
`400 INVALID_REQUEST` on SIMA batch	malformed `screeningAuthority` or payload	validate request against OpenAPI
polling never reaches terminal	worker backlog or failure loop	inspect `/api/jobs/:id` `error` + server logs

Dry-Run Evidence Tracker

Evidence ledger: docs/api/playbooks/p11-c-channel-dry-run-evidence.md
Required channels for P11-C gate:
- Claude
- ChatGPT
- GitHub Copilot Chat
- Gemini