Overview Quick Start API Reference Trace Types SDK Guide Gateway Setup Pricing & Limits

API Reference

Complete reference for all Observe and Guard Gateway endpoints.

On this page

Authentication
POST /api/observe/traces/batch
POST /api/observe/traces/otel
POST /api/gateway/v1/messages
Error Codes

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer as_live_your_api_key_here

API keys start with as_live_ followed by 32 random characters. Get yours from the Setup tab in your agent's Observe dashboard.

Keys are hashed at rest (SHA-256) and encrypted (AES-256-GCM). They cannot be recovered — regenerate if lost.

POST /api/observe/traces/batch

Send up to 100 traces in a single batch request. This is the primary ingestion endpoint.

Request

cURL

curl -X POST https://agentscrimmage.com/api/observe/traces/batch \
  -H "Authorization: Bearer as_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [
      {
        "traceId": "unique-id",
        "sessionId": "conversation-id",
        "userId": "end-user-id",
        "timestamp": "2026-07-08T12:00:00Z",
        "type": "llm_call",
        "llm": {
          "provider": "anthropic",
          "model": "claude-sonnet-4",
          "inputMessages": [
            {"role": "user", "content": "What is my order status?"}
          ],
          "outputMessage": "Your order #1234 shipped on July 5th.",
          "inputTokens": 32,
          "outputTokens": 15,
          "latencyMs": 650
        }
      }
    ]
  }'

Required fields

Field	Type	Description
traceId	string	Unique identifier for this trace
sessionId	string	Groups traces into conversations
type	string	llm_call \| tool_call \| user_message \| agent_response \| error

Optional fields

Field	Type	Description
userId	string	End-user identifier for per-user analytics
timestamp	string	ISO 8601 timestamp. Defaults to server time if omitted.
llm	object	LLM call details: provider, model, outputMessage (required), inputMessages, inputTokens, outputTokens, latencyMs, temperature
tool	object	Tool execution: name (required), arguments, result, latencyMs, success
response	object	Response text: text (required), latencyMs
metadata	object	Arbitrary key-value pairs for custom data
retrievedContext	object	RAG grounding: documents [{content, source?, score?}], query?
availableTools	array	Agent tools: [{name, description?, parameters?}]

Response

202 Accepted

{
  "ingested": 1,
  "flagged": 0
}

ingested — number of traces stored. flagged — number that triggered Tier 1 flags.

Limits

Maximum 100 traces per batch request
Monthly trace limit depends on your tier (5K / 25K / 100K / unlimited)
Returns 429 when monthly limit is reached

POST /api/observe/traces/otel

Accepts traces in OpenTelemetry OTLP JSON format. Use this if your stack already exports OTel spans (Datadog, Grafana, etc.).

Same authentication, same rate limits, same response shape as the batch endpoint. Traces are automatically converted from OTLP spans to Observe's internal format.

cURL

curl -X POST https://agentscrimmage.com/api/observe/traces/otel \
  -H "Authorization: Bearer as_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceSpans": [
      {
        "resource": {
          "attributes": [
            {"key": "session.id", "value": {"stringValue": "conv-1024"}}
          ]
        },
        "scopeSpans": [
          {
            "spans": [
              {
                "traceId": "abc123",
                "name": "llm.completion",
                "attributes": [
                  {"key": "gen_ai.system", "value": {"stringValue": "anthropic"}},
                  {"key": "gen_ai.response.model", "value": {"stringValue": "claude-sonnet-4"}},
                  {"key": "gen_ai.completion", "value": {"stringValue": "Your order shipped."}},
                  {"key": "gen_ai.usage.prompt_tokens", "value": {"intValue": "32"}},
                  {"key": "gen_ai.usage.completion_tokens", "value": {"intValue": "15"}}
                ]
              }
            ]
          }
        ]
      }
    ]
  }'

POST /api/gateway/v1/messages

The Guard Gateway intercepts LLM calls in real time. It runs Tier 1 guardrail checks before and after the LLM call, blocking or masking content that violates your PII config.

Accepts both Anthropic Messages and OpenAI Chat Completions format. Auto-detected — no configuration needed.

Anthropic format

Request

curl -X POST https://agentscrimmage.com/api/gateway/v1/messages \
  -H "Authorization: Bearer as_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "What is my account balance?"}
    ],
    "max_tokens": 1024
  }'

OpenAI format

Request

curl -X POST https://agentscrimmage.com/api/gateway/v1/messages \
  -H "Authorization: Bearer as_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is my account balance?"}
    ],
    "max_completion_tokens": 1024
  }'

Response headers

Header	Values
X-Guard-Decision	allowed \| blocked \| mask \| redact
X-Guard-Flag	The issue type that triggered the action (e.g. ssn_exposed)
X-Gateway-Generation-Id	LLM provider's response ID (when available)

Decision outcomes

allowed — response passed all checks, returned unchanged
blocked — CRITICAL behavioral issue detected, response replaced with fallback message
mask — PII partially masked (e.g. SSN → ***-**-6789, last 4 preserved)
redact — PII fully removed and replaced with [REDACTED]

Custom endpoints

Connect any OpenAI-compatible provider by setting a custom endpoint URL in the Gateway tab:

Provider	Endpoint
Anthropic	Leave empty (default)
OpenAI	Leave empty (default)
DeepSeek	https://api.deepseek.com
Grok / xAI	https://api.x.ai
Ollama (local)	http://localhost:11434
Groq	https://api.groq.com/openai
Together AI	https://api.together.xyz
Mistral	https://api.mistral.ai
vLLM	Your server URL

Error Codes

Code	Meaning
202	Traces accepted and queued for processing
200	Gateway response returned (check X-Guard-Decision header)
400	Invalid JSON, missing required fields, or batch too large (max 100)
401	Missing Authorization header
403	Invalid API key, disabled agent, or BYOK key exceeded failure limit
429	Monthly trace or gateway limit reached — upgrade or wait for reset
502	Failed to reach LLM provider (Gateway only)

Error response shape

{
  "error": "TRACE_LIMIT_REACHED",
  "message": "Monthly trace limit reached (5000/5000). Upgrade your Observe plan to continue.",
  "tier": "Free"
}

The error field is always present. message and tier are included when relevant.

SDK Guide →Trace Types →Gateway Guide →