AITracer
Docs
Trace Ingestion API

Trace Ingestion API

Submit trace records, specialized ingest events, and Bifrost proxy traffic.

AITracer ingestion endpoints accept workspace API keys (Authorization: Bearer akt_...) and enrich incoming data for governance, verification, alerts, and audit workflows.

Core endpoints

POST /api/traces
POST /api/integrations/openai-agents
POST /api/integrations/openai-guardrails
POST /api/integrations/otlp/v1/traces

Specialized ingest endpoints

POST /api/ingest/tool-calls
POST /api/ingest/feedback
POST /api/ingest/webhooks
  • Tool calls: function-call telemetry with arguments, result/error, optional trace link
  • Feedback: human thumbs-up/down signals linked to trace IDs
  • Webhooks: external security alerts (Dependabot/Snyk/etc.) for correlation

POST /api/ingest/webhooks also supports optional signed delivery headers:

  • X-AITracer-Delivery-Timestamp: <unix-seconds>
  • X-AITracer-Signature: v1=<hmac_sha256_hex>

When provided and workspace signing secrets exist, signatures are verified and replayed signatures are rejected.

Bifrost proxy endpoint

POST /api/proxy/openai/responses

The proxy route performs governance preflight checks, forwards to OpenAI Responses, and persists trace telemetry in one hop.

  • stream: false → JSON response
  • stream: true → text/event-stream passthrough (SSE)

Native trace example

{
  "actionName": "finance-review",
  "environment": "prod",
  "status": "completed",
  "requestId": "req_finance_001",
  "model": "gpt-4o",
  "prompt": "Summarize this report",
  "response": "Summary text",
  "metrics": {
    "promptTokens": 420,
    "completionTokens": 155,
    "totalTokens": 575,
    "latencyMs": 830,
    "estimatedCostUsd": 0.0042,
    "finishReason": "stop"
  }
}

Bifrost quick test body

{
  "model": "gpt-4o-mini",
  "input": "Give me a one-line incident summary.",
  "stream": false
}

Captured metadata and outcomes

  • prompts / responses
  • latency + token usage
  • provider metadata + request IDs
  • governance findings + policy records
  • audit logs + alert signals
  • verification records

Rate limiting

Ingest and proxy endpoints apply request throttling. Bursts beyond route limits return:

  • 429 Too Many Requests
  • Retry-After header with retry seconds
  • X-RateLimit-Remaining header

Response

{
  "trace": {
    "traceId": "req_finance_001",
    "status": "completed"
  }
}

OpenAPI reference

See /developers for the full OpenAPI schema, including specialized ingest and proxy routes.

SDKsVerification API