RGX Systems — Developer Reference

Overview

Quick Reference

System 01 — Compliance Engine

Method	Path	Description
POST	/process	AI inference with real-time compliance scrubbing. Core gateway endpoint.
POST	/ingest	Log a message batch without inference (channel ingestion).

System 02 — Tenant Isolation

Method	Path	Description
POST	/clients	Provision a new isolated tenant workspace.
GET	/clients	List all tenant workspaces on this node (paginated).
GET	/clients/:ref	Get one tenant workspace.
PATCH	/clients/:ref	Update tenant name or status.
DELETE	/clients/:ref	Delete tenant workspace and all associated data.
POST	/clients/:ref/keys	Issue a tenant-scoped sub-key.
DELETE	/clients/:ref/keys/:keyId	Revoke a sub-key.
GET	/clients/:ref/inbound-key	Get the public inbound key for this tenant.
POST	/clients/:ref/inbound	External system pushes an event into this tenant workspace (public, key-authenticated).

System 03 — Seat Metering

Method	Path	Description
GET	/usage	Node-level usage summary and estimated invoice for the current period.
GET	/billing/summary	Per-seat breakdown export for VAR invoicing.
GET	/health	Verify node connectivity and key status.

Overview

Enterprise Gateway Aliases

For enterprise and VAR integrations, three semantic aliases map to the underlying gateway endpoints. Use these aliases in documentation, contracts, and architecture diagrams — they resolve to the same routes listed in each system section below.

Alias	Resolves to	System
POST /v1/scrub	POST /api/v1/process	System 01 — Compliance Engine. In-memory PII/PHI scrubbing, token replacement, LLM routing.
POST /v1/tenant	POST /GET /api/v1/clients/:ref	System 02 — Tenant Isolation. Provision and manage isolated client workspaces.
GET /v1/meter	GET /api/v1/usage + /api/v1/billing/summary	System 03 — Seat Metering Ledger. Non-blocking async writes, per-seat attribution, VAR billing export.

→

All three aliases authenticate with the same X-Api-Key header. No additional configuration is required to use the alias form — both paths are active on every production node.

Overview

Authentication

Every request requires your Master API Key passed in the X-Api-Key header. Alternatively, pass it as a Bearer token in the Authorization header. Never expose your master key client-side — use tenant-scoped sub-keys for any client-facing access.

Two accepted formats

# Recommended — X-Api-Key header
curl https://rgxsystems.com/api/v1/health \
  -H "X-Api-Key: rgx_live_your_key_here"

# Alternative — Bearer token
curl https://rgxsystems.com/api/v1/health \
  -H "Authorization: Bearer rgx_live_your_key_here"
        

Key format	Plan	Capabilities
rgx_sandbox_…	Sandbox	500 req/month, 7-day TTL. Full platform access for evaluation.
rgx_live_…	Production node	1,000 req/hr. No expiry. Full platform + billing.
rgx_sub_…	Tenant sub-key	Scoped to a single client_ref. 403 on any other tenant. Issued via `POST /clients/:ref/keys`.

Overview

Rate Limits

Production nodes are limited to 1,000 requests per hour per API key. Rate limit state is returned on every response.

Rate limit response headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1750201200   # Unix epoch — top of next hour
        

!

When X-RateLimit-Remaining reaches 0, subsequent requests return 429 Too Many Requests until the window resets. The X-RateLimit-Reset header gives the exact Unix timestamp of reset.

Overview

Error Codes

Status	Code	Meaning
400	BAD_REQUEST	Missing or invalid request parameters. Check the `error` field for details.
401	UNAUTHORIZED	Missing or invalid API key.
402	LICENSE_EXPIRED / SEAT_LIMIT_EXCEEDED	Dedicated mode only. License past grace period or seat limit reached.
403	FORBIDDEN	Sub-key attempted to access a tenant it was not issued for.
404	NOT_FOUND	Tenant `client_ref` does not exist on this node.
429	RATE_LIMITED	1,000 req/hr limit exceeded. Retry after `X-RateLimit-Reset`.
500	INTERNAL_ERROR	Unexpected server error. Contact support with your request ID.

01

System 01

Compliance Engine

Real-time PII/PHI scrubbing before every LLM call. Zero raw identifiers forwarded to any model.

The Compliance Engine intercepts every POST /process payload, applies the configured industry scrub profile, replaces sensitive identifiers with sequentially numbered tokens, routes the sanitised text to the LLM, and writes an immutable entry to the compliance_redaction_events log. The LLM never sees raw PII, PHI, or financial identifiers.

System 01 — Compliance Engine

POST /process

The core gateway endpoint. Accepts arbitrary text, applies the industry compliance layer, routes to the appropriate model, and returns the AI response with full compliance metadata.

Field	Type	Description
inputrequired	string	The text payload to process. Scrubbed in-flight before reaching the LLM.
system_promptoptional	string	System-level instructions for the model. Passed unscrubbed — do not include user-supplied data here.
session_idoptional	string	Conversation session identifier for context continuity across requests.
config.industryoptional	string	Industry compliance profile. See Industry Config Values. Defaults to no scrubbing if omitted.
config.routing_profileoptional	string	`deep-reasoning` (Claude Sonnet 4.6) or `ultra-low-latency` (GPT-4o-mini). Defaults to `deep-reasoning`.
config.tenant_idoptional	string	The `client_ref` of the tenant this request belongs to. Used for seat-level billing attribution.

POST /api/v1/process — Healthcare / PHI scrubbing

curl -X POST https://rgxsystems.com/api/v1/process \
  -H "X-Api-Key: rgx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Patient John Smith DOB 04/12/1978 MRN-88821 asking about Thursday appointment. SSN 523-44-1234.",
    "system_prompt": "Summarise this clinical note. Flag any follow-up actions required.",
    "config": {
      "industry": "healthcare",
      "routing_profile": "deep-reasoning",
      "tenant_id": "riverside-dental"
    }
  }'
// LLM receives: "Patient {{REDACTED_PHI_1}} DOB {{REDACTED_PHI_2}} MRN-{{REDACTED_PHI_3}} asking...
// SSN {{REDACTED_PHI_4}}."  Raw data never leaves your infrastructure.
        

200 OKHealthcare response

{ "ok": true, "response": "Clinical summary: Patient has upcoming Thursday appointment. Follow-up: confirm appointment and check if any pre-visit forms are outstanding.", "model": "claude-sonnet-4-6", "industry": "healthcare", "phi_redactions": 4, "compliance_event_logged": true, "tokens": { "input": 38, "output": 54 }, "processing_ms": 1820 }

POST /api/v1/process — Legal / Output validation + disclaimer

curl -X POST https://rgxsystems.com/api/v1/process \
  -H "X-Api-Key: rgx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Review this NDA clause for potential issues: ...",
    "system_prompt": "You are a contract review assistant. Identify risks and ambiguous language.",
    "config": {
      "industry": "legal",
      "routing_profile": "deep-reasoning",
      "tenant_id": "sterling-law"
    }
  }'
// Output is validated for directive/liability language.
// Mandatory legal disclaimer appended before delivery.
        

200 OKLegal response (disclaimer appended)

{ "ok": true, "response": "The non-compete clause contains three areas of concern...\n\n---\nIMPORTANT: This output was generated by an AI system and does not constitute legal advice. Consult a qualified attorney before acting on this analysis.", "industry": "legal", "leg_redactions": 0, "compliance_event_logged": true, "legal_disclaimer_appended": true, "processing_ms": 2140 }

POST /api/v1/process — Finance / Full audit trail

curl -X POST https://rgxsystems.com/api/v1/process \
  -H "X-Api-Key: rgx_live_your_key" \
  -H "X-Industry: finance" \
  -H "X-Routing-Profile: ultra-low-latency" \
  -H "X-Tenant-Id: acme-capital" \
  -H "Content-Type: application/json" \
  -d '{ "input": "Summarise Q3 bond portfolio exposure for the risk committee." }'
// Full audit trail written: tenant_id, model, tokens, timestamp, seat_id.
// Industry config accepted via headers or request body interchangeably.
        

System 01 — Compliance Engine

Industry Config Values

Pass config.industry in the request body (or X-Industry header) to activate the correct compliance layer. Only the five supported verticals are listed below.

config.industry	Compliance layer	Recommended routing_profile
"healthcare"	PHI scrubbing — SSNs, MRNs, DOBs, insurance IDs, and addresses replaced with `{{REDACTED_PHI_N}}` tokens before LLM call. HIPAA-ready.	deep-reasoning
"legal"	Output validated for directive or liability language. Mandatory legal disclaimer appended to every AI response.	deep-reasoning
"finance"	Full immutable audit trail per request: tenant_id, model, tokens, timestamps, seat_id. Mapped for regulatory reporting.	either
"real_estate"	Standard processing — no additional compliance layer. Full audit log still written.	ultra-low-latency
"professional_services"	PII scrubbing — EINs, SSNs, routing numbers, account numbers, and card data replaced with `{{REDACTED_FIN_N}}` tokens. Right-to-erasure purge endpoint included.	deep-reasoning

System 01 — Compliance Engine

Scrub Token Format

Every redacted identifier is replaced with a numbered token before the payload reaches any model. Tokens are sequentially numbered per request and namespaced by compliance type.

Token pattern	Used for	Example input	Scrubbed form
`{{REDACTED_PHI_N}}`	Healthcare — SSN, MRN, DOB, insurance ID, address, name	John Smith DOB 04/12/1978	{{REDACTED_PHI_1}} DOB {{REDACTED_PHI_2}}
`{{REDACTED_FIN_N}}`	Finance & Professional Services — EIN, SSN, routing, account, card	EIN 45-2312890, account 0012334	EIN {{REDACTED_FIN_1}}, account {{REDACTED_FIN_2}}
`{{REDACTED_LEG_N}}`	Legal — attorney privilege markers, case references flagged for review	Case No. 2024-CV-88121	Case No. {{REDACTED_LEG_1}}

→

Token numbers reset to 1 on each new request. They are never reused across requests. The mapping (token → original value) is never stored — raw identifiers are discarded immediately after the scrub pass and never written to any log or database.

System 01 — Compliance Engine

Compliance Event Log

Every request that produces at least one redaction fires a non-blocking write to the compliance_redaction_events table. The write is asynchronous and never adds latency to the API response. The log is immutable — entries cannot be modified or deleted.

Field	Description
event_id	Unique identifier for this compliance event.
node_id	The VAR node this request was processed on.
tenant_id	The `client_ref` of the tenant, if provided.
seat_id	The authenticated seat that made the request, if present.
industry	The industry compliance profile applied.
redaction_count	Number of tokens replaced in this request.
token_namespace	PHI, FIN, or LEG — the type of scrub applied.
created_at	ISO 8601 UTC timestamp. Immutable after write.

02

System 02

Tenant Isolation Architecture

Each client_ref is a fully isolated workspace at the data layer. Cross-tenant access returns 403 at infrastructure level — not application logic.

Each client you onboard becomes an isolated tenant node identified by a client_ref you assign. All integrations, credentials, data, and AI context are scoped to that ref. A sub-key issued for sterling-law cannot access riverside-dental — enforced at the database query level, not application-layer checks.

System 02 — Tenant Isolation

POST /clients

Provision a new isolated tenant workspace. The client_ref you assign here is used in every subsequent API call for this tenant. Choose it carefully — it is permanent.

Field	Type	Description
client_refrequired	string	Unique, URL-safe, lowercase identifier. Hyphens permitted. Permanent.
namerequired	string	Tenant company or display name.
emailoptional	string	Primary contact email.
metadataoptional	object	Arbitrary key-value pairs stored with this tenant record.

POST /api/v1/clients

curl -X POST https://rgxsystems.com/api/v1/clients \
  -H "X-Api-Key: rgx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "client_ref": "sterling-law",
    "name": "Sterling & Associates",
    "email": "ops@sterlinglaw.com",
    "metadata": { "industry": "legal", "seats": 12 }
  }'
        

201 CreatedResponse

{ "ok": true, "client": { "id": "vc_01j9x...", "client_ref": "sterling-law", "name": "Sterling & Associates", "status": "active", "created_at": "2026-07-09T14:22:00Z" } }

System 02 — Tenant Isolation

GET /clients

List all provisioned tenant workspaces on this node. Paginated — pass ?page=2&limit=50 for subsequent pages.

GET /api/v1/clients

curl https://rgxsystems.com/api/v1/clients?limit=50 \
  -H "X-Api-Key: rgx_live_your_key"
        

System 02 — Tenant Isolation

PATCH /clients/:ref

Update the tenant's display name or status. client_ref itself cannot be changed.

Field	Type	Description
nameoptional	string	Updated display name.
statusoptional	string	`active` or `suspended`. Suspended tenants reject all API calls for that ref.

System 02 — Tenant Isolation

DELETE /clients/:ref

Permanently delete this tenant workspace. All associated credentials, integration tokens, and data are purged. This operation supports right-to-erasure requirements. Irreversible.

!

Deletion is immediate and permanent. The client_ref can be reused after deletion, but all previous data is unrecoverable. Compliance event log entries are not deleted — they are retained for audit purposes.

System 02 — Tenant Isolation

Tenant Seat Authentication

Each tenant workspace enforces its own seat authentication mode. All API requests routed through a tenant workspace must include a valid seat credential — the gateway validates it before processing. See Seat Attribution for the full four-mode reference.

PATCH /api/v1/clients/:ref — set seat_auth_mode

curl -X PATCH https://rgxsystems.com/api/v1/clients/sterling-law \
  -H "X-Api-Key: rgx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "seat_auth_mode": "oidc",
    "oidc_issuer": "https://dev-123456.okta.com/oauth2/default",
    "oidc_audience": "api://default"
  }'
// Supported modes: "rgx_jwt" | "oidc" | "saml" | "header"
// OIDC and SAML validated per-request by the gateway — no client secret stored.
        

→

Once seat_auth_mode is set on a tenant, every POST /process call must include a valid credential for that mode. Requests without a valid seat credential return 401. Enterprise SSO configuration: OIDC / SAML Authentication →

System 02 — Tenant Isolation

Sub-Keys

Issue a scoped API key locked exclusively to a single tenant workspace. A sub-key (rgx_sub_…) returns 403 on any API call for a different client_ref. Use sub-keys for client-facing integrations where you cannot proxy through your own backend.

POST /api/v1/clients/:ref/keys — issue sub-key

curl -X POST https://rgxsystems.com/api/v1/clients/sterling-law/keys \
  -H "X-Api-Key: rgx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Sterling internal integration" }'

// Returns: { "key": "rgx_sub_...", "client_ref": "sterling-law" }
// This key only works for sterling-law. Any other client_ref = 403.
        

DELETE /api/v1/clients/:ref/keys/:keyId — revoke

curl -X DELETE https://rgxsystems.com/api/v1/clients/sterling-law/keys/key_01j9... \
  -H "X-Api-Key: rgx_live_your_key"
// Key revoked immediately. In-flight requests using it return 401.
        

System 02 — Tenant Isolation

Inbound Events

Each tenant can receive events from external systems (web forms, Stripe webhooks, custom CRMs) without exposing your master API key. Retrieve the tenant's inbound key and give it to the external system. That system POSTs directly into the tenant workspace using only the inbound key.

GET /api/v1/clients/:ref/inbound-key

curl https://rgxsystems.com/api/v1/clients/sterling-law/inbound-key \
  -H "X-Api-Key: rgx_live_your_key"
// Returns: { "inbound_key": "inb_0x9f...", "inbound_url": "https://rgxsystems.com/api/v1/clients/sterling-law/inbound" }
        

POST /api/v1/clients/:ref/inbound — external system call (public)

curl -X POST "https://rgxsystems.com/api/v1/clients/sterling-law/inbound?key=inb_0x9f..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "web-form",
    "event": "new_inquiry",
    "from": "sarah.johnson@email.com",
    "payload": { "name": "Sarah Johnson", "matter_type": "estate_planning" }
  }'
// Event stored in tenant workspace. Master key never exposed.
        

03

System 03

Seat Metering Ledger

Non-blocking async writes. Per-seat attribution. VAR billing export at any price point.

Every API call is attributed to a seat asynchronously — the ledger write is fire-and-forget and never adds latency to the API response. VARs pull /billing/summary to build per-seat invoices at any price point. RGX charges $2,000/mo node fee + $20/active seat — the margin between that and what you charge your clients is entirely yours.

System 03 — Seat Metering

GET /usage

Node-level usage summary for the current billing period. Returns active seat count, estimated invoice, and aggregate token consumption.

GET /api/v1/usage

curl https://rgxsystems.com/api/v1/usage \
  -H "X-Api-Key: rgx_live_your_key"
        

200 OKResponse

{ "period": "2026-07", "requests_this_month": 6241, "active_seats": 47, "base_fee_usd": 2000, "seat_fee_usd": 20, "seat_charges_usd": 940, "estimated_invoice_usd": 2940, "ai_tokens_used": 1847200 }

System 03 — Seat Metering

GET /billing/summary

Per-seat breakdown for the current billing period. Use this to build your own invoices to your clients at whatever per-seat price you charge them.

GET /api/v1/billing/summary

curl https://rgxsystems.com/api/v1/billing/summary \
  -H "X-Api-Key: rgx_live_your_key"
        

200 OKResponse

{ "period": "2026-07", "active_seats": 4, "seats": [ { "client_ref": "sterling-law", "seat_id": "user@sterlinglaw.com", "first_seen": "2026-07-01T09:14:22Z", "last_active": "2026-07-09T16:02:11Z", "requests": 142, "ai_tokens": 284000 }, { "client_ref": "riverside-dental", "seat_id": "front-desk@riverside.com", "first_seen": "2026-07-02T08:30:00Z", "last_active": "2026-07-09T15:44:03Z", "requests": 89, "ai_tokens": 176400 }, { "client_ref": "acme-capital", "seat_id": "portfolio-analyst@acme.com", "first_seen": "2026-07-03T11:00:00Z", "last_active": "2026-07-09T12:18:44Z", "requests": 211, "ai_tokens": 422000 }, { "client_ref": "hartley-cpa", "seat_id": "tax-lead@hartleycpa.com", "first_seen": "2026-07-05T09:00:00Z", "last_active": "2026-07-09T14:55:00Z", "requests": 76, "ai_tokens": 151800 } ] }

System 03 — Seat Metering

Seat Attribution

A seat is auto-provisioned on first appearance. RGX supports four attribution modes, resolved in order. No configuration is required for modes 1 or 4 — they work out of the box.

Mode	How to send	Notes
RGX JWT	`Authorization: Bearer <hs256_jwt>`	Sign with `JWT_SIGNING_SECRET + ":" + node_id`. Payload must include `seat_id`.
OIDC	`Authorization: Bearer <rs256_token>`	Okta, Azure AD, Google. Configure once via `POST /api/admin/var/:id/idp`.
SAML 2.0	`X-Saml-Assertion: <base64 SAMLResponse>`	Azure AD, ADFS, Okta SAML. Configure IdP cert once.
Header / Body	`X-Seat-Id: user@company.com`	Simplest option for server-side VAR apps. No token signing.

Enterprise

OIDC / SAML Authentication

Configure enterprise SSO once via the admin API. After configuration, every inbound token from that provider is validated automatically — no per-request configuration changes required.

POST /api/admin/var/:id/idp — OIDC (Okta)

curl -X POST https://rgxsystems.com/api/admin/var/vn_01j.../idp \
  -H "X-Api-Key: ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "oidc",
    "issuer": "https://dev-123456.okta.com/oauth2/default",
    "audience": "api://default",
    "seat_id_claim": "sub"
  }'
        

POST /api/admin/var/:id/idp — SAML (Azure AD / ADFS)

curl -X POST https://rgxsystems.com/api/admin/var/vn_01j.../idp \
  -H "X-Api-Key: ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "saml",
    "idp_certificate": "MIICpDCCAYwCCQ...",
    "seat_id_attribute": "http://schemas.microsoft.com/identity/claims/objectidentifier"
  }'
        

→

See the Deployment Guide → Seat Authentication for the full four-mode reference including RGX JWT signing and header-based attribution.

Enterprise

Dedicated Deployment

For data residency, VPC isolation, or air-gapped requirements. Deploy RGX entirely within your own cloud account — Terraform for AWS or GCP, Helm for Kubernetes, Docker Compose for on-prem. Offline RS256 license verification — no outbound network call required. Contact licensing@rgxsystems.com for a license JWT.

→

Full deployment reference with Terraform, Helm, and Docker Compose examples: Deploy Guide → Dedicated Deployment

Enterprise

License Verification

In dedicated mode, the GET /api/v1/license endpoint returns the current license status. This endpoint is not available on shared-infrastructure nodes.

GET /api/v1/license — dedicated mode only

curl https://your-instance.internal/api/v1/license \
  -H "X-Api-Key: rgx_live_your_key"
        

200 OKResponse

{ "valid": true, "company": "Acme Enterprise", "plan": "enterprise", "seat_limit": 500, "features": ["oidc", "saml", "hipaa", "on_prem"], "expires_at": "2027-07-09T00:00:00Z", "grace_period_days": 14 }

Three Systems. One API Key.