ELYARA GATEWAY — INTEGRATION DOCS

Gateway API Reference

Governance Layer for AI in Production. All endpoints use the base URL:

https://elyara-site-production.up.railway.app/v1

Authentication

All endpoints (except /health) require an API key via the x-api-key header.

curl -H "x-api-key: ely_your_key_here" \
     https://elyara-site-production.up.railway.app/v1/usage

API keys are SHA-256 hashed before storage. Lost keys cannot be recovered — request a new one from your administrator.

Request Headers

Header	Required	Description
`x-api-key`	Yes*	Your API key (`ely_...`)
`x-regime`	No	Governance regime: `A` (Clinical), `B` (Regulatory), `C` (General). Default: `C`
`x-platform`	No	Platform identifier for audit tracking (e.g., `grupo-doc`)
`Content-Type`	Yes	Must be `application/json`

* Not required for GET /v1/health

Endpoints

Health Check

GET /v1/health

Public endpoint — no authentication required.

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 3600,
  "kill_switch": { "active": false }
}

Chat (Main Pipeline)

POST /v1/chat

Main AI inference endpoint. Runs the full governance pipeline: Auth → Rate Limit → Kill Switch → PII Scan → LLM → PII Mask → Audit.

Request body:

{
  "message": "What are the contraindications of metformin?",
  "context": "Patient is 65 years old with kidney disease."
}

Field	Type	Required	Description
`message`	string	Yes	The user query
`context`	string	No	Additional context prepended to the LLM prompt

Response:

{
  "response": "Based on clinical guidelines...",
  "confidence": "high",
  "regime": "A",
  "model": "claude-opus-4-0",
  "tokens": { "input": 128, "output": 256 },
  "cost_brl": 0.1163,
  "latency_ms": 3200,
  "pii_detected": false,
  "pii_fields": []
}

PII Protection: In Regime A/B, requests containing PII (CPF, email, phone, names) are blocked with HTTP 422. In Regime C, PII is warned but not blocked. Output PII is always masked.

Usage Analytics

GET /v1/usage

Returns aggregated usage statistics. Admin keys see all data; client keys see only their own.

Param	Values	Default
`period`	`day`, `week`, `month`	`month`
`platform`	Platform name filter	all

Kill Switch (Admin Only)

POST /v1/kill

Activate emergency suspension. Requires admin API key.

{
  "scope": "all",
  "reason": "Critical vulnerability detected"
}

Field	Values	Description
`scope`	`all`, `platform`, `regime`	What to suspend
`target`	string	Required for `platform`/`regime` scope
`reason`	string	Required. Logged for audit trail

DELETE /v1/kill

Deactivate kill switch. Same scope + target fields.

Governance Regimes

Regime	Model	PII Policy	Use Case
A — Clinical	`claude-opus-4-0`	Block on input	Medical queries requiring cited references
B — Regulatory	`claude-opus-4-0`	Block on input	ANVISA, CFM, LGPD compliance queries
C — General	`claude-sonnet-4-0`	Warn only	General assistance, admin queries

Rate Limits

Rate limiting uses a sliding window of 1 minute per API key. Default: 100 req/min.

Rate limit headers in response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
Retry-After: 45   (only on 429)

Error Codes

HTTP	Code	Description
400	`BAD_REQUEST`	Invalid JSON or missing required fields
401	`AUTH_MISSING`	No `x-api-key` header
401	`AUTH_INVALID`	Invalid or inactive API key
403	`FORBIDDEN`	Admin-only endpoint accessed by client key
422	`PII_BLOCKED`	PII detected in clinical/regulatory regime
429	`RATE_LIMIT`	Rate limit exceeded
502	`LLM_ERROR`	LLM provider call failed
503	Service suspended	Kill switch is active

Quick Start

# 1. Check health
curl https://elyara-site-production.up.railway.app/v1/health

# 2. Send a query (Regime C — General)
curl -X POST https://elyara-site-production.up.railway.app/v1/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -H "x-regime: C" \
  -d '{"message": "Hello, what can you help me with?"}'

# 3. Check usage
curl https://elyara-site-production.up.railway.app/v1/usage?period=day \
  -H "x-api-key: YOUR_KEY"

Architecture

Every request passes through the full governance pipeline:

Request → Auth → Rate Limit → Kill Switch → PII Scan
       → LLM (Opus/Sonnet) → PII Mask → Audit Log → Response

All inputs and outputs are SHA-256 hashed in the audit log — no raw text is stored. Cost is calculated in BRL and tracked per regime.