Developer reference

Send traces. Run gates. Export evidence.

Plug AegisRail into any production AI workflow. Authenticated trace ingest, eval gate API, and audit-ready evidence with one ingest endpoint.

REST · JSONStablev1

Quickstart

Three steps to first value.

01
Create an AI system
Register the workflow you want to govern in the AegisRail registry. Copy its system ID.
02
Issue an ingest API key
Create an ingest-scoped key from the Settings page. Store it as AEGISRAIL_API_KEY.
03
Send your first trace
POST a trace to /api/ingest/traces. It appears in Observe instantly.

Official Node SDK

Zero-dependency client for Node 18+. Ingest calls never throw, so trace delivery failures cannot crash your application, and getEvalGate turns a suite into a CI release gate.

pnpm add @aegisrail/sdk
# or: npm install @aegisrail/sdk

Authentication

All ingest, eval, and evidence routes require a workspace-scoped API key in the Authorization header. Use ingest-only scopes for production trace senders; use admin keys only for backend tooling.

Header: Authorization: Bearer …
Scope: ingest · read · admin
Rotation: rotate every 90 days
Storage: hashed at rest, prefix shown to admins

Single trace ingest

One trace per request. Available on every plan.

const response = await fetch("https://YOUR_APP_URL/api/ingest/traces", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.AEGISRAIL_API_KEY}`,
  },
  body: JSON.stringify({
    systemId: "SYSTEM_ID_FROM_AEGISRAIL",
    provider: "google",
    model: "gemini-3-flash-preview",
    inputSummary: "Customer requested refund exception.",
    outputSummary: "Drafted escalation response with policy reference.",
    latencyMs: 1240,
    costUsd: 0.012,
    promptTokens: 1468,
    completionTokens: 312,
    status: "success",
    riskFlags: ["policy_reference"],
    toolCalls: [{ name: "lookup_policy", status: "success", latencyMs: 180 }],
    userFeedback: "positive",
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

Batch ingest

Send up to your plan's batch size with { traces: [...] }. Available on Growth and Scale plans.

OpenTelemetry ingest

Already instrumented with OpenTelemetry? Point an OTLP/HTTP exporter (JSON encoding) at /api/ingest/otlp and GenAI spans become AegisRail traces with zero code changes. Spans resolve their system from the aegis.system.id resource attribute or the x-aegis-system-id header; non-GenAI spans are skipped and reported via partialSuccess.

exporters:
  otlphttp/aegisrail:
    traces_endpoint: https://YOUR_APP_URL/api/ingest/otlp
    encoding: json
    headers:
      authorization: Bearer ${env:AEGISRAIL_API_KEY}
      x-aegis-system-id: sys_abc123

service:
  pipelines:
    traces:
      exporters: [otlphttp/aegisrail]

TypeScript client

A copy-paste client wrapping single + batch ingestion against the same endpoint.

type AegisTrace = {
  systemId: string;
  provider:
    | "google"
    | "openai"
    | "anthropic"
    | "azure_openai"
    | "bedrock"
    | "mistral"
    | "ollama"
    | "custom";
  model: string;
  inputSummary?: string;
  outputSummary?: string;
  latencyMs: number;
  status: "success" | "failed" | "flagged";
  riskFlags?: string[];
};

export function createAegisRailClient(config: { apiKey: string; baseUrl: string }) {
  async function ingest(trace: AegisTrace) {
    return ingestBatch([trace]);
  }

  async function ingestBatch(traces: AegisTrace[]) {
    const body = traces.length === 1 ? traces[0] : { traces };
    const response = await fetch(`${config.baseUrl}/api/ingest/traces`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${config.apiKey}`,
      },
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      throw new Error(await response.text());
    }

    return response.json() as Promise<{ id?: string; ids: string[]; count: number }>;
  }

  return { ingest, ingestBatch };
}

Trace schema

Required identifiers: systemId, provider, model, status, latencyMs
Operational metrics: latencyMs, costUsd, promptTokens, completionTokens
Trust signals: riskFlags[], toolCalls[], userFeedback, inputSummary, outputSummary
Status enum: success · failed · flagged

Errors & limits

401 Unauthorized: Missing or invalid bearer token
403 Forbidden: Wrong scope or revoked key
422 Validation: Schema mismatch; body returns the field name
429 Rate limited: Plan ingest rate exceeded

Need higher batch size or trace volume? Upgrade your plan or contact support.

Quickstart

Three steps to first value.

Create an AI system

Issue an ingest API key

Create an ingest-scoped key from the Settings page. Store it as AEGISRAIL_API_KEY.

Send your first trace

POST a trace to /api/ingest/traces. It appears in Observe instantly.

Authentication

All ingest, eval, and evidence routes require a workspace-scoped API key in the Authorization header. Use ingest-only scopes for production trace senders; use admin keys only for backend tooling.

Header

Authorization: Bearer …

Scope

ingest · read · admin

Rotation

rotate every 90 days

Storage

hashed at rest, prefix shown to admins

Single trace ingest

One trace per request. Available on every plan.

const response = await fetch("https://YOUR_APP_URL/api/ingest/traces", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.AEGISRAIL_API_KEY}`,
  },
  body: JSON.stringify({
    systemId: "SYSTEM_ID_FROM_AEGISRAIL",
    provider: "google",
    model: "gemini-3-flash-preview",
    inputSummary: "Customer requested refund exception.",
    outputSummary: "Drafted escalation response with policy reference.",
    latencyMs: 1240,
    costUsd: 0.012,
    promptTokens: 1468,
    completionTokens: 312,
    status: "success",
    riskFlags: ["policy_reference"],
    toolCalls: [{ name: "lookup_policy", status: "success", latencyMs: 180 }],
    userFeedback: "positive",
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

OpenTelemetry ingest

exporters:
  otlphttp/aegisrail:
    traces_endpoint: https://YOUR_APP_URL/api/ingest/otlp
    encoding: json
    headers:
      authorization: Bearer ${env:AEGISRAIL_API_KEY}
      x-aegis-system-id: sys_abc123

service:
  pipelines:
    traces:
      exporters: [otlphttp/aegisrail]

TypeScript client

A copy-paste client wrapping single + batch ingestion against the same endpoint.

type AegisTrace = {
  systemId: string;
  provider:
    | "google"
    | "openai"
    | "anthropic"
    | "azure_openai"
    | "bedrock"
    | "mistral"
    | "ollama"
    | "custom";
  model: string;
  inputSummary?: string;
  outputSummary?: string;
  latencyMs: number;
  status: "success" | "failed" | "flagged";
  riskFlags?: string[];
};

export function createAegisRailClient(config: { apiKey: string; baseUrl: string }) {
  async function ingest(trace: AegisTrace) {
    return ingestBatch([trace]);
  }

  async function ingestBatch(traces: AegisTrace[]) {
    const body = traces.length === 1 ? traces[0] : { traces };
    const response = await fetch(`${config.baseUrl}/api/ingest/traces`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${config.apiKey}`,
      },
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      throw new Error(await response.text());
    }

    return response.json() as Promise<{ id?: string; ids: string[]; count: number }>;
  }

  return { ingest, ingestBatch };
}