API v1

API Documentation

Everything you need to send W3C trace context, ingest spans, complete async work, query aggregation, and use MCP Trace Observatory tools. Public reads are open; ingestion, span completion, replay, forks, syncs, and reports require PLATPHORM_API_KEY.

Check API HealthLLM Reference

Quick Start

Send traces with the shared platform key. Public-safe trace browsing, aggregation summaries, docs, and discovery files stay readable without auth.

curl -X POST https://trace.platphormnews.com/api/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PLATPHORM_API_KEY" \
  -d '{
            "name": "Multi-tool trace",
            "agentName": "my-agent",
            "spans": [
              {
                "spanId": "00f067aa0ba902b7",
        "name": "tools/call search",
        "startTime": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",
        "endTime": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",
        "attributes": {
          "mcp.method.name": "tools/call",
          "gen_ai.tool.name": "search"
                },
                "status": "ok"
              },
              {
                "spanId": "00f067aa0ba902b8",
                "name": "tools/call summarize",
                "startTime": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",
                "endTime": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",
                "attributes": {
                  "mcp.method.name": "tools/call",
                  "gen_ai.tool.name": "summarize"
                },
                "status": "ok"
              }
            ]
          }'

Trace stores a complete span batch only when persisted structure proves a meaningful action. Rudimentary requests and insufficient-action batches return collected=false without a durable write; accepted responses include spans_received, spans_ingested, spans_skipped, assessment_reason, and span_persistence_reason. Public lists, live feeds, search, sessions, maps, statistics, direct trace views, comparisons, and exports apply the same rule. Historical rudimentary records require authenticated, no-store forensic scope.

W3C Trace Context

Trace accepts standard traceparent and safe tracestate, then maps them to PlatPhorm enrichment headers. Do not put secrets in baggage, tracestate, spans, evidence, or public artifacts.

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate: platphorm=trace
X-PlatPhorm-Trace-Id: 4bf92f3577b34da6a3ce929d0e0e4736
X-PlatPhorm-Span-Id: 00f067aa0ba902b7
X-PlatPhorm-Source-Site: cli.platphormnews.com
X-PlatPhorm-Target-Site: trace.platphormnews.com

Async Jobs and Span Completion

Span lifecycle
Start, heartbeat, complete, fail, and late spans.
curl -X POST https://trace.platphormnews.com/api/v1/spans/start \
  -H "Authorization: Bearer $PLATPHORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"traceId":"4bf92f3577b34da6a3ce929d0e0e4736","spanId":"00f067aa0ba902b7","name":"BrowserOps journey","kind":"browser"}'

curl -X POST https://trace.platphormnews.com/api/v1/spans/complete \
  -H "X-PlatPhorm-API-Key: $PLATPHORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"traceId":"4bf92f3577b34da6a3ce929d0e0e4736","spanId":"00f067aa0ba902b7"}'
Async job envelope
Durable when storage is configured; degraded honestly otherwise.
curl -X POST https://trace.platphormnews.com/api/v1/async/jobs \
  -H "Authorization: Bearer $PLATPHORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"traceId":"4bf92f3577b34da6a3ce929d0e0e4736","jobType":"sandbox.command","queueName":"sandbox"}'

API Endpoints

POST/api/v1/traces
Ingest Trace
Submit a complete trace; only structurally meaningful action batches are persisted
GET/api/v1/traces
List Traces
Browse and filter public traces
GET/api/v1/traces/{id}
Get Trace
Retrieve full trace with spans
POST/api/v1/spans/start
Start Span
Start or attach a span to a trace
POST/api/v1/spans/complete
Complete Span
Complete a span and recompute trace lifecycle
POST/api/v1/traces/{id}/fork
Fork Trace
Create a what-if scenario
GET/api/v1/aggregate/summary
Aggregation Summary
Lifecycle, latency, service, and JA4 redaction summaries
POST/api/v1/async/jobs
Create Async Job
Create a trace-linked async job
GET/api/v1/observatory
Truth Model
Homepage metrics with value, source, fetchedAt, state, and next action
GET/api/v1/integrations/status
Integration Matrix
Observed, registered, degraded, and unknown integration state
GET/api/v1/playbooks
Debugging Playbooks
Deterministic playbooks for incomplete, failed, late, and orphaned workflows
POST/api/v1/workflows/{id}/run
Run Registered Trace Demo
Launch a protected, trace-linked 10-, 15-, or 100-step workflow selected from the public registry
GET/api/v1/search
Search
Search public-safe traces, spans, evidence, and playbooks
POST/api/v1/evidence
Link Evidence
Protected redacted evidence linking for trace proof
POST/api/v1/reports/trace-summary
Trace Report
Public-safe report generation from persisted evidence

Rate Limits

2,000/min
Premium
With API key
1,000/min
Network
*.platphormnews.com
500/min
Recognized
Returning visitors
60/min
Public
Anonymous access

Security

Authentication
Required for mutations and operational actions
# With API key (higher rate limits)
curl -H "Authorization: Bearer $PLATPHORM_API_KEY" \
  https://trace.platphormnews.com/api/v1/traces
Trusted Domains
Automatic elevated trust for known domains
  • Network*.platphormnews.com
  • PlatformVercel metadata is captured only as safe redacted runtime metadata

Ready to start observing?

Public reads are open. Send traces with PLATPHORM_API_KEY.

View Live TracesComplete Reference