REST & OTLP Wire Protocol

Afforde AI Telemetry API Reference

The Afforde Ingestion & Query API accepts structured execution traces, token distributions, and deterministic schema verification payloads over HTTPS (JSON or Protobuf/zstd). All endpoints strictly enforce TLS 1.3.

Base URLs & Regional Isolation

To guarantee strict compliance with European GDPR and US enterprise data residency policies, telemetry ingestion is physically isolated by cluster region:

CLUSTER REGION	BASE ENDPOINT	RESIDENCY GUARANTEE
EU-Central (Berlin / Frankfurt)	https://ingest.eu.affor.de	100% EU storage & processing (GDPR Art. 28 DPA)
US-West (Oregon)	https://ingest.us.affor.de	US-only storage & processing (SOC 2 Type II)
Global Geo-Routed Alias	https://ingest.affor.de	Routes automatically based on workspace tenant region

Authentication

Authenticate every API request by passing your workspace API key in the Authorization HTTP header using the Bearer scheme. Ingestion keys (aff_ingest_*) are write-only and cannot query historical logs.

Authorization: Bearer aff_ingest_98a7bc65d4e3f2a109f8e7d6
Content-Type: application/json
X-Afforde-Client-Version: 2.4.0

Batching & Rate Limits

Each POST /v1/traces request may contain up to 500 span objects or a maximum uncompressed payload size of 4 MB. Default private beta workspaces are provisioned with a sustained ingestion ceiling of 2,500 spans/second.

POST /v1/traces

Ingests a batch of one or more inference execution spans, recording token counts, sub-span latency metrics, and client-side PII sanitization attestations.

Request Body Schema (Span Object)

FIELD	TYPE	REQUIRED	DESCRIPTION
trace_id	string	required	Unique 128-bit W3C TraceContext identifier (`tr_*` or hex).
pipeline	string	required	Logical service or prompt pipeline identifier (e.g., `invoice-extractor-v3`).
timestamp_unix_ns	int64	required	UTC epoch timestamp in nanoseconds when the request was initiated.
metrics.ttft_ms	float64	required	Time-to-First-Token in milliseconds measured at client runtime.
metrics.total_ms	float64	required	End-to-end completion duration in milliseconds.
tokens.input	uint32	required	Prompt and system context token count.
tokens.output	uint32	required	Generated completion token count.
audit.pii_redacted	boolean	optional	Indicates whether client-side regex/NER scrubbing was executed before emission.

EXAMPLE REQUEST

POST /v1/traces HTTP/1.1
Host: ingest.eu.affor.de
Authorization: Bearer aff_ingest_98a7bc65d4e3
Content-Type: application/json

{
  "spans": [
    {
      "trace_id": "tr_9041f8a2b7c1",
      "pipeline": "invoice-extractor-v3",
      "timestamp_unix_ns": 1762948800000000000,
      "model_id": "gemini-2.5-pro",
      "metrics": {
        "retrieve_ms": 96.0,
        "scrub_ms": 12.4,
        "ttft_ms": 142.4,
        "total_ms": 690.1
      },
      "tokens": {
        "input": 1840,
        "output": 412,
        "cached_prefix": 1024
      },
      "audit": {
        "pii_redacted": true,
        "schema_id": "schema_inv_v2",
        "payload_sha256": "e3b0c44298fc1c149afbf4c8996fb924"
      }
    }
  ]
}

EXAMPLE RESPONSE (202 ACCEPTED)

HTTP/1.1 202 Accepted
Content-Type: application/json
X-Afforde-Cluster: eu-central-1a

{
  "status": "accepted",
  "ingested_count": 1,
  "batch_id": "bat_01jch8k9w2m4x8",
  "schema_evaluations": [
    {
      "trace_id": "tr_9041f8a2b7c1",
      "conformance": "VALIDATED",
      "anomaly_score": 0.008,
      "optimization_hint": "NONE"
    }
  ]
}

POST /v1/schemas/validate

Synchronously validates a structured LLM output against a registered JSON Schema draft-2020-12 contract and computes semantic drift scores against golden baseline vectors.

POST /v1/schemas/validate HTTP/1.1
Host: ingest.eu.affor.de
Authorization: Bearer aff_ingest_98a7bc65d4e3
Content-Type: application/json

{
  "schema_id": "schema_inv_v2",
  "trace_id": "tr_89f2a1c4",
  "candidate_json": {
    "invoice_number": "INV-2026-0891",
    "currency": "EUR",
    "total_net": 4250.00
  }
}

GET /v1/metrics/latency

Retrieves aggregated P50, P95, and P99 Time-to-First-Token (TTFT) and total execution duration percentiles grouped by pipeline and time bucket. Requires a read-scoped key (aff_read_*).

GET /v1/metrics/latency?pipeline=invoice-extractor-v3&window=24h&step=1h HTTP/1.1
Host: ingest.eu.affor.de
Authorization: Bearer aff_read_44c910a8b2e1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pipeline": "invoice-extractor-v3",
  "window": "24h",
  "summary": {
    "request_count": 148920,
    "ttft_p50_ms": 168.2,
    "ttft_p95_ms": 390.5,
    "ttft_p99_ms": 740.0,
    "schema_pass_rate": 0.9994
  }
}

HTTP Status & Error Codes

HTTP STATUS	ERROR CODE	CAUSE & RESOLUTION
202 Accepted	BATCH_QUEUED	Span batch passed structural validation and was committed to the ingestion ring.
400 Bad Request	INVALID_SPAN_PAYLOAD	Missing required fields (`trace_id`, `timestamp_unix_ns`) or malformed JSON.
401 Unauthorized	INVALID_API_KEY	Bearer token is missing, revoked, or belongs to a different regional cluster.
429 Too Many Requests	INGEST_RATE_EXCEEDED	Tenant exceeded sustained span/sec ceiling; honor the `Retry-After` header.