Inference

The core endpoint. Send a prompt, get a response. Eridian handles schema normalization, routing across GPT and Gemini, caching, RAG, PII redaction, and observability before a token leaves the gateway.

Request

POST /v1/inference
Host: api.geteridian.com
Authorization: Bearer eridian_sk_...
Content-Type: application/json
Idempotency-Key: contract-summary-4821-v1
X-Eridian-Project: prj_legal_001

Required scope: inference:write

Request Body

project_id may be supplied in the body or as X-Eridian-Project. If both are present they must match.

Example Request

{
  "model": "auto",
  "project_id": "prj_legal_001",
  "messages": [
    { "role": "user", "content": "Summarize the key risks in this contract." }
  ],
  "features": ["pii_redaction", "semantic_cache", "rag"],
  "routing_policy": "quality_optimized",
  "metadata": {
    "matter_id": "MTR-4821",
    "desk": "legal-ops"
  }
}

Response

{
  "id": "axm_resp_8f3a2b1c",
  "object": "eridian.inference.response",
  "model": "gpt",
  "created": 1718400000,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The contract contains three key risks:..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1247,
    "completion_tokens": 382,
    "total_tokens": 1629
  },
  "eridian": {
    "request_id": "axm_req_8f3a2b1c",
    "route": "gpt",
    "route_fallback": false,
    "cache_hit": false,
    "cache_similarity": 0.78,
    "rag_injected": true,
    "rag_chunks": 3,
    "pii_redacted": 2,
    "pii_entities": ["name", "account_number"],
    "latency_ms": 1247,
    "cost_usd": 0.0042,
    "project_id": "prj_legal_001",
    "region": "eu-west-1",
    "template_id": "tpl_contract_summary_v3",
    "template_version": "3.2.1",
    "routing_policy": "quality_optimized",
    "structured_output_valid": true
  }
}

Retrieve a Response

GET /v1/inference/axm_resp_8f3a2b1c
Authorization: Bearer eridian_sk_...

Required scope: inference:read. Returns the original eridian.inference.response if retention policy still holds the record. Zero-data-retention projects return HTTP 404 with error.code: record_not_retained after the request completes.

Eridian Headers

Every inference response includes these headers:

Streaming

Set "stream": true to receive Server-Sent Events. First-token latency targets p99 under 500ms on Enterprise. Each event is an eridian.inference.chunk object. The terminal event is data: [DONE].

POST /v1/inference
Authorization: Bearer eridian_sk_...
Content-Type: application/json
Accept: text/event-stream

event: chunk data: {"id":"axm_resp_8f3a2b1c","object":"eridian.inference.chunk","choices":[{"delta":{"content":"The "}}]} event: chunk data: {"id":"axm_resp_8f3a2b1c","object":"eridian.inference.chunk","choices":[{"delta":{"content":"contract"}}]} event: done data: [DONE]

The final non-done chunk includes eridian metadata (route, cost, cache, PII counts). Do not treat intermediate chunks as complete for audit export.

Feature Flags

The features array activates pipeline stages. Order of execution is fixed: PII redaction → RAG retrieval → semantic cache lookup → routing → model inference → structured output validation.

Status Codes

Error bodies always include error.code, error.message, and error.request_id. See Errors.

Idempotency

Include Idempotency-Key on mutating calls that must not double-spend. Eridian stores keys for 24 hours per project. Replays with the same key and the same body return the original eridian.inference.response without a second provider hop. See Idempotency.

Cost Attribution

Every response includes eridian.cost_usd from GPT or Gemini token rates plus Eridian platform overhead. Costs roll up to project, API key, template, desk (metadata.desk), and routing policy. Use metadata to attach internal ticket IDs for finance reconciliation.

Timeouts and Retries

Configure per-project defaults for connect, read, and total timeouts. The routing engine retries transient provider errors once per model in the fallback chain before surfacing a 503. Set client-side timeouts above the sum of fallback chain worst-case latency.

SDK Examples

Python

from eridian import Eridian

client = Eridian(api_key="eridian_sk_...", project_id="prj_legal_001")

response = client.inference.create(
    model="auto",
    messages=[{"role": "user", "content": "Review this clause for termination risk."}],
    features=["semantic_cache", "pii_redaction"],
)

print(response.object)
print(response.eridian.route)
print(response.eridian.cost_usd)

TypeScript

import { Eridian } from "@eridian/sdk";

const client = new Eridian({ apiKey: process.env.ERIDIAN_API_KEY! });

const response = await client.inference.create({
  model: "auto",
  projectId: "prj_legal_001",
  messages: [{ role: "user", content: "Summarize incident timeline." }],
  features: ["semantic_cache"],
});

console.log(response.object);
console.log(response.eridian.route);

Compliance Notes

Inference requests are logged to the immutable audit trail with actor, project, model route (gpt or gemini), PII entity counts, region, and cost. Export logs via Audit Log and Evidence Export.