conversation_id field (the trace ID); the field keeps its name for backwards compatibility. Use it when your language has no Moda SDK, when data originates outside your application process (backfills, message queues, webhook consumers), or when you need channel formats such as email and call transcripts.
Base URL
/v1 prefix.
Authentication
Every endpoint exceptGET /health requires an API key (called an ingestion key in the dashboard) in the Authorization header:
401. The message field names the failure — Missing Authorization header when the header is absent, Invalid or expired API key otherwise:
The
Bearer prefix is optional: a bare key in the Authorization header is also accepted. CLI session tokens are not valid here — only moda_sk_ API keys.Request IDs
You can send an optionalX-Request-ID header on any request. If the value is a valid UUID, it is echoed back as requestId in the JSON response; otherwise the server generates a random UUID. Use it to correlate requests, responses, and retries in your own logs.
GET /health
Health check. No authentication. Returns200 with the plain-text body ok.
POST /v1/ingest
Sends trace events as simple JSON. Each event is one message in a trace. Events with the sameconversation_id are grouped into one trace.
Request body
Environment for all events in the request. Must be exactly
development, staging, or production (defaults to production); any other value is rejected with 400. Individual events can override it with their own environment field.Up to 1,000 events per request. An empty or absent array returns
200 with count: 0 and the message No events provided.Event fields
Who produced the message — typically
user, assistant, or system. Events with role assistant are recorded as model output; all other roles are recorded as input to the model.The message content, either as a string or as an array of content blocks (see below). If both
content and message are present, content takes precedence.Structured content blocks for tool use, extended thinking, or images (see below). Used when
content is absent.ISO 8601 date-time of the event, for example
2026-08-16T10:30:00Z. Defaults to the time the event is received. A timestamp that is present but unparseable is rejected with 400.Optional OpenTelemetry-style trace ID stored on the event. Defaults to
conversation_id. Grouping into a Moda trace is by conversation_id, not this field.Per-event override of the request-level environment. Common aliases are normalized (
dev/develop → development, stg/stage → staging, prod → production); unrecognized values fall back to production.Events carrying a
messageType field are rejected with 400. Channel-specific events (chat platforms, email, calls, tool invocations) belong on POST /v1/ingest/multi.Content blocks
Use content blocks (incontent or content_blocks) when a message contains more than plain text:
Every block accepts an optional numeric
index (defaults to the block’s position in the array). Anthropic API field names are also accepted: name is normalized to tool_name, id to tool_use_id, and a thinking field on thinking blocks to text.
Example
400 with a message naming the first failing event; nothing from the batch is stored:
503 with retryable: true:
POST /v1/ingest/multi
Ingests traces that span channels: chat platform messages, tool invocations, emails, and call transcripts. Each event declares its shape withmessageType.
Common event fields
Your stable, unique ID for the event (non-empty). It becomes the event’s
external_message_id.Trace ID (session or thread ID) that groups events into one trace, required for all four event types.
Free-form object. Accepted, but its contents are not currently attached to the stored message.
/v1/ingest: an optional request-level environment plus an events array of up to 1,000 events.
Type-specific fields
channel — a message in a chat or messaging platform:
tool_call — a tool or function invocation:
email — one email in a thread:
call — a phone, video, or voice call. Each call is stored as a single record containing the full transcript:
Example
details breaks the accepted count down by event type:
details.call_transcript_messages is always 0; it is retained for backward compatibility. Calls are counted under details.call.400 with a per-event message (for example Event 0: Missing or invalid 'id' field), and nothing from the batch is stored.
POST /v1/traces
The OpenTelemetry OTLP/HTTP trace endpoint. Both Moda SDKs export here by default, and any OTLP-capable exporter can target it directly.- Accepts OTLP/JSON, and OTLP/protobuf when the
Content-Typeheader containsprotobuf. - The body is a standard
ExportTraceServiceRequest(resourceSpans→scopeSpans→spans). - Moda traces are extracted from GenAI span attributes: OTel GenAI semantic conventions (
gen_ai.*), OpenLLMetry (llm.prompts.*/llm.completions.*), Vercel AI SDK (ai.*), andmoda.*attributes for the trace ID (moda.conversation_id), user ID, environment, and prompt attribution. - Only the 5 MB body cap applies; there is no per-request span count limit.
200 with {"success": true, "count": N, "requestId": "..."}, 400 with the message Invalid OTLP format on parse failure). Successful protobuf requests get an OTLP ExportTraceServiceResponse body instead; parse failures and 401 auth failures return the JSON envelope regardless of request format, while a 503 (including API-key validation being temporarily unavailable) returns an OTLP protobuf body.
See OpenTelemetry for the full list of supported span attributes and the trace ID precedence rules.
Next steps
- Reliability — status codes, retry guidance, and limits.
- OpenTelemetry — supported span attributes for
POST /v1/traces. - Authentication — creating and revoking ingestion keys.