# Ingest API, schema `proven.ingest/1`

Send each interaction to Attify as it happens, signed with your deployment's key, through the Python or TypeScript SDK, `POST /v1/ingest/events`, or OpenTelemetry. Streamed data is witnessed: it counts toward an audited score once the customer consents and reconciles it each month.

| Your agent | The way in | Provenance |
|---|---|---|
| Works inside the customer's help desk, CRM or calendar | The customer connects that system ([sources](/docs/sources)) | Connected |
| Runs on an agent platform or is traced in an observability tool | Connect the platform account ([below](#reading-your-platform-account-instead)) | Connected if it is the buyer's account, witnessed if it is yours |
| Runs on your own stack | An SDK or the Ingest API (this page) | Witnessed |
| Is instrumented with OpenTelemetry | Export traces ([below](#opentelemetry)) | Witnessed |

Header, package and schema names use Attify's working name (`proven`, `Proven-*`).

How an AI agent that runs on its own platform streams its interactions to Attify, so they can be audited. Data that arrives this way is **witnessed**: the vendor sends each interaction as it happens, signed with its deployment's key, and Attify timestamps every event when it arrives. Witnessed data counts toward a verification or a badge only after the customer consents in Attify and reconciles it against its own records ([VERIFICATION.md](VERIFICATION.md#witnessed-data)). Until then it feeds the vendor's private report only.

This page is also served at `/docs/ingest`. Machine-readable: the event's JSON Schema (`schemas/ingest-event.schema.json`, `urn:proven:ingest-event:1`, served at `/docs/ingest/schema.json`) and the OpenAPI document of these endpoints (`api/openapi-ingest.json`, served at `/docs/ingest/openapi.json`).

## Quickstart

1. Signed in as a vendor's owner, open **Agents** (`/deployments`) and create a deployment for one customer, attesting that you may share its interaction data. Copy the key: Attify shows it once.
2. Send events as each interaction happens, with an SDK, any HTTP client (below) or OpenTelemetry.
3. Read the private report on the deployment's page: witnessed data the customer has not reconciled is labeled so, and counts toward nothing else.
4. To count toward a verification, invite the customer from a program, naming the deployment. The customer consents in Attify, then reconciles each month: its own total for the month, then a random spot check.

```bash
export ATTIFY_KEY=pdk_...                 # from step 1
export ATTIFY_URL=https://api.attify.app  # the API's own host
# export ATTIFY_URL=http://localhost:8000 # local development
```

## SDKs

Thin clients that sign, number (`stream`, `seq`), buffer and retry; nothing else: `attify-ingest` for Python (standard library only) and for TypeScript (no dependencies), with examples for the Anthropic SDK, LangChain, the Vercel AI SDK and a plain HTTP agent. Both default to `https://api.attify.app`. Any HTTP client works too ([Signing](#signing)).

```bash
pip install attify-ingest
npm install attify-ingest
```

Python from python.org on macOS comes without CA certificates: add `certifi` (`pip install attify-ingest certifi`), which the Python client then uses.

```python
from attify_ingest import Attify

attify = Attify(key=os.environ["ATTIFY_KEY"])
chat = attify.interaction("conv_123", channel="chat", customer="cust_42", external_ref="ticket_9")
chat.message("customer", "Where is my order?")
chat.message("agent", "It ships tomorrow.")
chat.claim("resolved")
chat.end("completed")
attify.close()
```

```ts
import { Attify } from "attify-ingest";

const attify = new Attify({ key: process.env.ATTIFY_KEY! });
const chat = attify.interaction("conv_123", { channel: "chat", customer: "cust_42", externalRef: "ticket_9" });
chat.message("customer", "Where is my order?");
chat.message("agent", "It ships tomorrow.");
chat.claim("resolved");
chat.end("completed");
await attify.close();
```

`customer` and `external_ref` are the ids **in the customer's own systems**: they are how a repeat contact is found in its help desk, and how a spot check finds the interaction there.

## Endpoints

All on the API's own host (locally `http://localhost:8000`), never through the web app. The deployment's key is the credential; the API's `X-API-Key` is not used here.

| Endpoint | Body | Auth | Use |
|---|---|---|---|
| `POST /v1/ingest/events` | `application/json`: `{"events": [...]}`, 1 to 500 events, at most 1 MB | Signed body | Batches, and single events as they happen (a batch of one) |
| `POST /v1/ingest/stream` | `application/x-ndjson`: one event per line, at most 10,000 lines and 64 KB a line | Signed handshake | One long request that sends events as they happen; each line is stored when it arrives |
| `POST /v1/otlp/v1/traces` | OTLP/HTTP, protobuf or JSON, optionally gzip | `Authorization: Bearer <key>` | Agents already instrumented with OpenTelemetry ([below](#opentelemetry)) |

Rate limit: `INGEST_RATE_PER_MINUTE` requests per minute per deployment (default 600), answered `429` with `Retry-After` beyond it. The SDKs wait as long as `Retry-After` says.

## The deployment key

A deployment is one agent deployed for one customer. A signed-in vendor creates it (web: Deployments; API: `POST /v1/deployments`), attesting that it has the right to share that customer's interaction data with Attify. Attify issues its key once:

```
pdk_<key id: 16 hex digits>_<secret: base64url>
```

Attify keeps the secret sealed and shows it only at creation. Rotation: create a second key, switch, revoke the first; both work in between.

## Signing

`POST /v1/ingest/events` sends three headers:

```
Proven-Key: pdk_<key id>
Proven-Timestamp: <unix seconds>
Proven-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>
```

The HMAC key is the secret as UTF-8 bytes; the message is the timestamp, a dot, and the body exactly as sent. A timestamp more than 300 seconds from Attify's clock is refused (`stale_signature`), which stops replays. With curl:

```bash
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST "$ATTIFY_URL/v1/ingest/events" -H "Content-Type: application/json" \
  -H "Proven-Key: pdk_$KEY_ID" -H "Proven-Timestamp: $TS" -H "Proven-Signature: v1=$SIG" \
  --data "$BODY"
```

`POST /v1/ingest/stream` signs the handshake instead of the body (which is not finished when the request starts): the message is `"<timestamp>.stream"`. Each line is protected by TLS, as OTLP is.

Every event records how it was authenticated (`signed`, `signed_stream`, `bearer`), and every batch's answer carries Attify's receipt: the body's SHA-256, when it arrived and the counts, signed with Attify's Ed25519 attestation key (`/.well-known/proven-keys.json`), so the vendor can show what it sent and when.

## Events

Every event is one JSON object:

| Field | Type | Rule |
|---|---|---|
| `id` | string, 1 to 128 of `A-Za-z0-9._:-` | Idempotency key, unique within the deployment. Sending it again with the same content is a `duplicate` and changes nothing; with other content it is rejected (`conflict`) and counts as a sequence break |
| `type` | string | One of the types below |
| `occurred_at` | RFC 3339 with an offset | When it happened, by the agent's clock |
| `interaction` | string, 1 to 128 of `A-Za-z0-9._:-` | The interaction it belongs to (a conversation, a call, a task). Required for every type except `deployment` |
| `stream` | string, 1 to 64 of `A-Za-z0-9._:-` | Optional, default `default`. One sender process: the SDKs pick a random one per process |
| `seq` | integer, 1 or more | Position in the stream: 1, 2, 3, ... with no gaps. Optional, but without it gaps cannot be seen. The same stream and `seq` with another `id` is rejected (`seq_conflict`) and counts as a sequence break |
| `data` | object | By type, below. Unknown fields are refused |

| `type` | `data` |
|---|---|
| `deployment` | `agent`, `version`, `model` (strings, optional): what is running |
| `interaction.started` | `channel` (chat, email, voice, ...), `customer` (the end user's id **in the customer's own system**, so a repeat contact can be found), `external_ref` (this interaction's id in the customer's own system: a ticket, a CRM record, a calendar event), all optional |
| `message` | `role`: `customer` (the end user), `agent` (the AI), `human` (a person on the customer's side), `system` or `tool`; `text`: up to 20,000 characters. System and tool messages are counted, their text is not kept |
| `handoff` | `to`: `human`, `agent` or `external`; `reason` (optional). `human` and `external` fail a claim; `agent` (a handoff to another AI agent) does not |
| `action` | `name`: the tool or function the agent called (`book_appointment`); `status`: `succeeded`, `failed` or `unknown` (default); `kind` (optional): what it did, in the job type's words (`booking.created`, `meeting.scheduled`); `external_ref` (optional): the record it made or changed in the customer's own system, which a spot check looks up; `detail` (optional, up to 500 characters, redacted) |
| `outcome.claimed` | `outcome`: the vendor's own claim, from the job type's vocabulary (support: `resolved`, `not_resolved`; sales meetings: `meeting_booked`, `no_meeting`; bookings: `booked`, `not_booked`); `detail` (optional). The latest claim of an interaction is the one tested. For sales meetings and bookings, the interaction's `external_ref` names the meeting or appointment it booked (its id in the customer's calendar, CRM or booking system): that is where the outcome is checked, and what a spot check looks up |
| `feedback` | `kind`: `resolution` (score 1 yes, 0 no), `csat`, `thumbs`, `nps` or `other`; `score` (number); `scale_max` (optional); `text` (optional). Only `resolution`, an explicit yes or no to whether the issue was resolved, can count as customer-confirmed; ratings are reported as satisfaction, never as confirmation |
| `interaction.ended` | `reason`: `completed`, `abandoned`, `timeout` or `transferred` (optional) |

Message, feedback and action detail text is redacted when it arrives (`proven.redact`, the same rules as connected data) and purged `TEXT_RETENTION_DAYS` (30 by default) after it arrives, as connected text is. Events keep no text at all, only their type, times, ids and a digest.

## What makes data count

- **You attest** in the terms that you may share the customer's interaction data, when you create the deployment.
- **The customer consents** in Attify to its data counting toward your verification.
- **The customer reconciles each month**: its own total for the month within 2% of what you streamed, then 10 seeded spot checks against its own systems.
- **The stream is whole**: under 0.1% missing sequence numbers and under 1% late interactions in the period.
- **Every conversation your AI handled is claimed** (support resolution): `outcome.claimed` with `resolved` or `not_resolved` on each one. An audit counts every conversation the AI handled, so above 2% left with no claim either way, the data stops counting.

Until all of these hold, witnessed data feeds your private report only ([reconciliation](/glossary/reconciliation)).

## Reading your platform account instead

An agent built on an agent platform or traced in an observability tool needs no code: create the deployment with **Attify reads my platform**, choose the platform (Vapi, Retell AI, ElevenLabs, Bland, Voiceflow, Langfuse, LangSmith), and paste a key (API: `POST /v1/deployments` with `source: {"platform": "vapi", "fields": {"token": "...", ...}}`; `GET /v1/connectors/{job_type}` lists each platform's fields). When the account runs agents for several customers, its scope field (the agent or assistant ids, a project, a tag) picks out this customer's. Attify reads the account every 15 minutes and sends what it finds through the same pipeline as the events above, with the platform's own timestamps, so everything below applies; a deployment read this way is witnessed data, like a streamed one. Its events are authenticated as `pulled`.

- An interaction Attify first reads more than `PLATFORM_MAX_DELAY_MINUTES` (120) after it happened is late. The first read reaches `CONNECT_BACKFILL_DAYS` (90) back, so it is late throughout: those interactions show on the private report's coverage, never as witnessed.
- A read that starts more than that delay after the last good one records a `pull_gap` break.
- Interaction ids are the platform's own, prefixed with the platform (`vapi:<call id>`), so you can still send events for them yourself (a claim, feedback) with the deployment's key.
- The key is sealed like every connector token and deleted with the deployment. None of these platforms revokes a key through its API: revoke it on the platform's keys page (the deployment links to it).

How each platform's records map onto these events is in [docs/sources/research.md](sources/research.md).

## What Attify checks on arrival

- **Late events.** An event that arrives more than 5 minutes after its `occurred_at` is accepted and flagged `late` (`INGEST_MAX_DELAY_SECONDS`, for operators). An interaction with a late event is not witnessed live: it is stored and counted on the deployment's health, and never scored as witnessed data. An event more than 300 seconds in the future is rejected (`future_event`).
- **Gaps.** Per stream, the `seq` numbers never received between the first and the last, once older than the delay above.
- **Sequence breaks.** A reused `id` with other content, or a reused `seq` with another `id`.
- **Volume.** Interactions per calendar month, for the customer's reconciliation.

All four show on the deployment and, once a customer links it, on the vendor's program (`ingest` on each customer). Above 0.1% missing sequence numbers, or 1% late interactions, in the scoring period, the deployment's health is `degraded` and its data stops counting toward verification until it is back under both. For support resolution, so does leaving more than 2% of the conversations the AI handled without a claim either way (`unclaimed_share`), once they are 7 days old.

## Answers

`POST /v1/ingest/events` and `/v1/ingest/stream` answer `200` when the request was authenticated, even if some events were refused:

```json
{"schema": "proven.ingest.result/1", "deployment": "dep_...", "received_at": "...",
 "accepted": 2, "duplicates": 0, "rejected": 1, "late": 0,
 "results": [{"id": "e1", "status": "accepted"}, {"id": "e2", "status": "accepted"},
             {"id": "e3", "status": "rejected", "code": "invalid_event", "message": "..."}],
 "receipt": {"payload": {...}, "signature": {"alg": "EdDSA", "kid": "...", "value": "..."}}}
```

Keep the receipt: it is Attify's signed statement of what you sent and when it arrived. Check it yourself against the public keys at `/.well-known/proven-keys.json` (Ed25519 over the payload as canonical JSON: sorted keys, no whitespace, UTF-8), or at `/verify`.

Retry the whole request on `429`, `5xx` or a network error: ids make it safe. Never retry a `rejected` event unchanged. Errors for the whole request: `400` (not JSON, or no `events` array), `401` (`missing_signature`, `stale_signature`, `unknown_key`, `key_revoked`, `bad_signature`), `413` (too many events or bytes), `429`.

## OpenTelemetry

An agent instrumented with the OpenTelemetry generative-AI semantic conventions sends to Attify with configuration only:

```bash
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.attify.app/v1/otlp/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer pdk_..."
OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental   # instrumentations that support it
```

`OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` asks instrumentations that honour it (the OpenTelemetry Python and JavaScript gen-ai instrumentations among them) to emit the latest gen-ai attributes, including the message contents Attify maps below ([the conventions](https://github.com/open-telemetry/semantic-conventions/tree/v1.41.1/docs/gen-ai)).

A minimal span, in Python with the OpenTelemetry SDK: one exchange, the agent's claim and no handoff.

```python
from opentelemetry import trace

tracer = trace.get_tracer("my-agent")
with tracer.start_as_current_span(
    "chat",
    attributes={
        "gen_ai.operation.name": "chat",
        "gen_ai.conversation.id": "conv_123",
        "proven.customer": "cus_456",
    },
) as span:
    span.set_attribute(
        "gen_ai.input.messages",
        '[{"role": "user", "parts": [{"type": "text", "content": "Where is my order?"}]}]',
    )
    span.set_attribute(
        "gen_ai.output.messages",
        '[{"role": "assistant", "parts": [{"type": "text", "content": "It ships today."}]}]',
    )
    span.set_attribute("proven.outcome", "resolved")
```

Mapped against **semantic conventions v1.41.1** (2026-05-11), the last release that carries the gen-ai conventions; from v1.42.0 they moved to `open-telemetry/semantic-conventions-genai`, which has no release yet. Status: Development.

| OpenTelemetry | Attify event |
|---|---|
| `gen_ai.conversation.id` on a span (else the trace id) | `interaction` |
| a span with `gen_ai.operation.name` `chat`, `generate_content`, `text_completion` or `invoke_agent` | `interaction.started` at its start (first time the interaction is seen) |
| `gen_ai.input.messages` (JSON string or structured), each new message | `message` at the span's start; role `user` → `customer`, `assistant` → `agent`, `system` and `tool` as they are |
| `gen_ai.output.messages` | `message` (`agent`) at the span's end |
| span events `gen_ai.user.message`, `gen_ai.assistant.message`, `gen_ai.choice` (deprecated since v1.37.0, still sent by older instrumentations) | `message` at the event's time |
| `proven.outcome` (attribute or span event `proven.outcome.claimed`) | `outcome.claimed` |
| `proven.handoff` (`human`, `agent`, `external`) | `handoff` |
| `proven.customer`, `proven.external_ref`, `proven.channel` | `interaction.started` fields |
| span event `proven.feedback` (`kind`, `score`, `scale_max`) | `feedback` |
| `proven.interaction.ended` | `interaction.ended` |
| resource `service.name`, `service.version` | `deployment` |

Messages repeat in every call's history, so a message's event id is derived from the interaction, its role and a digest of its text: sending the same history again adds nothing. Spans carry no sequence numbers, so gaps are not measured for OpenTelemetry data (its health says so). Without new code Attify sees interactions and messages; the outcome the agent claims needs one attribute, `proven.outcome`. Logs (`/v1/logs`, where `gen_ai.client.inference.operation.details` travels) are not read yet. Mapping fixtures: `engine/tests/fixtures/otlp/`.

## Questions

### Do I need the customer's consent?

Yes, for the data to count toward a verification: the customer consents in Attify and reconciles each month. Without it, the data feeds your private report only.

### What happens to late events?

They are accepted and flagged. An interaction with a late event is stored and counted on the deployment's health, but never scored as witnessed data.

### Can I send history?

Yes, but every past interaction arrives late, so it is never scored as witnessed. Connecting the customer's own system reads history as connected data instead.

### How do I rotate the key?

Create a new key on the deployment's page, switch your agent to it, then revoke the old one. Events signed with a revoked key are refused.

### Which job types?

Support resolution, sales meetings and bookings: the outcome vocabularies are in the `outcome.claimed` row above.
