# OpenTelemetry convention

Send OTLP/HTTP **JSON** traces to your tenant's keyed endpoint:

```
POST {API_URL}/v1/otel/{endpoint_key}/v1/traces
Content-Type: application/json
```

Any span that carries the outcome attributes becomes a **claim** with `vendor = internal`. Any span with action attributes becomes a **fact**. All other attributes are dropped at ingestion; message bodies are never accepted.

## Span attributes

| Attribute | Required | Meaning |
|---|---|---|
| `agent.outcome.type` | yes (claim) | Outcome type: `resolution`, `procedure_handoff`, `lead_qualified`, `meeting_booked`, `refund_processed`, `record_processed`, or a custom type mapped in the source's mapping |
| `agent.outcome.subject_id` | yes (claim) | The system-of-record id the outcome is about (ticket id, case id, order id). Must match the subject id used by your fact sources (e.g. `zendesk_ticket_123`) or be linkable through identity resolution |
| `agent.outcome.claimed_at` | no | ISO-8601 timestamp; defaults to the span end time |
| `agent.outcome.unit_price` | no | Internal transfer price for definition-delta reporting |
| `agent.name` | no | Agent identifier, kept as a claim attribute |
| `agent.channel` | no | `chat`, `email`, `voice`, … (used by `channel_in` exclusions) |
| `agent.action.type` | yes (fact) | `status_change`, `escalate`, `handoff`, `reply`, or a custom action |
| `agent.action.subject_id` | yes (fact) | Subject the action was taken on |
| `agent.action.from` / `agent.action.to` | no | Status transition for `status_change` |

## Minimal example (no SDK)

```bash
curl -X POST "$API_URL/v1/otel/$ENDPOINT_KEY/v1/traces" -H 'Content-Type: application/json' -d '{
  "resourceSpans": [{"resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "billing-agent"}}]},
    "scopeSpans": [{"spans": [{
      "traceId": "5b8aa5a2d2c872e8321cf37308d69df2", "spanId": "051581bf3cb55c13", "name": "resolve_ticket",
      "startTimeUnixNano": "1756742400000000000", "endTimeUnixNano": "1756742460000000000",
      "attributes": [
        {"key": "agent.outcome.type", "value": {"stringValue": "resolution"}},
        {"key": "agent.outcome.subject_id", "value": {"stringValue": "zendesk_ticket_48213"}},
        {"key": "agent.name", "value": {"stringValue": "billing-agent"}}
      ]}]}]}]}'
```

Claims created this way flow through the same contract engine and statements as vendor claims, under the `internal_agent_otel` contract (or the contract mapped per outcome type in the source mapping).
