Ingest API

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 agentThe way inProvenance
Works inside the customer's help desk, CRM or calendarThe customer connects that system (sources)Connected
Runs on an agent platform or is traced in an observability toolConnect the platform account (below)Connected if it is the buyer's account, witnessed if it is yours
Runs on your own stackAn SDK or the Ingest API (this page)Witnessed
Is instrumented with OpenTelemetryExport traces (below)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). 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.
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).

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.

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()
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.

EndpointBodyAuthUse
POST /v1/ingest/eventsapplication/json: {"events": [...]}, 1 to 500 events, at most 1 MBSigned bodyBatches, and single events as they happen (a batch of one)
POST /v1/ingest/streamapplication/x-ndjson: one event per line, at most 10,000 lines and 64 KB a lineSigned handshakeOne long request that sends events as they happen; each line is stored when it arrives
POST /v1/otlp/v1/tracesOTLP/HTTP, protobuf or JSON, optionally gzipAuthorization: Bearer <key>Agents already instrumented with OpenTelemetry (below)

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:

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:

FieldTypeRule
idstring, 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
typestringOne of the types below
occurred_atRFC 3339 with an offsetWhen it happened, by the agent's clock
interactionstring, 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
streamstring, 1 to 64 of A-Za-z0-9._:-Optional, default default. One sender process: the SDKs pick a random one per process
seqinteger, 1 or morePosition 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
dataobjectBy type, below. Unknown fields are refused
typedata
deploymentagent, version, model (strings, optional): what is running
interaction.startedchannel (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
messagerole: 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
handoffto: human, agent or external; reason (optional). human and external fail a claim; agent (a handoff to another AI agent) does not
actionname: 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.claimedoutcome: 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
feedbackkind: 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.endedreason: 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).

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.

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:

{"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:

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).

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

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.

OpenTelemetryAttify 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_agentinteraction.started at its start (first time the interaction is seen)
gen_ai.input.messages (JSON string or structured), each new messagemessage at the span's start; role user → customer, assistant → agent, system and tool as they are
gen_ai.output.messagesmessage (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.channelinteraction.started fields
span event proven.feedback (kind, score, scale_max)feedback
proven.interaction.endedinteraction.ended
resource service.name, service.versiondeployment

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#

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.