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.
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#
- 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. - Send events as each interaction happens, with an SDK, any HTTP client (below) or OpenTelemetry.
- Read the private report on the deployment's page: witnessed data the customer has not reconciled is labeled so, and counts toward nothing else.
- 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.
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:
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.claimedwithresolvedornot_resolvedon 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 reachesCONNECT_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_gapbreak. - 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_atis accepted and flaggedlate(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
seqnumbers never received between the first and the last, once older than the delay above. - Sequence breaks. A reused
idwith other content, or a reusedseqwith anotherid. - 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.
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.