Skip to content

Ingestion API

Emit AI inference events to Argmin with a single HTTP POST. Use this when your code or pipeline already has a point that observes each AI call.

Base URL

Argmin deploys a dedicated data plane inside your trust boundary, so the base URL is your deployed instance — e.g. https://<your-argmin-instance>. Your onboarding contact provides the exact host. All paths below are relative to that host.

Authentication

Send either header:

Authorization: Bearer <jwt>

X-API-Key: <key>

Argmin issues the credential during tenant provisioning. Health endpoints are the only unauthenticated routes.

POST /api/v1/invocations

Record one AI inference as an InvocationEvent. Returns 202 Accepted — the event is queued for the attribution pipeline.

Minimal request

These fields are required by the controlled schema:

curl -X POST https://<your-argmin-instance>/api/v1/invocations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ARGMIN_API_KEY" \
  -d '{
    "event_id": "8f3c…",                       # unique id you generate (UUID)
    "ingestion_layer": "application",          # where the event was captured
    "ingestion_timestamp": "2026-05-29T18:30:00Z",
    "provider": "openai",
    "requested_model": "gpt-4o"
  }'

Add the fields that make attribution useful — tokens, cost, and the identity or service responsible:

curl -X POST https://<your-argmin-instance>/api/v1/invocations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ARGMIN_API_KEY" \
  -d '{
    "event_id": "8f3c…",
    "ingestion_layer": "application",
    "ingestion_timestamp": "2026-05-29T18:30:00Z",
    "provider": "openai",
    "requested_model": "gpt-4o",
    "input_tokens": 1200,
    "output_tokens": 350,
    "estimated_cost_usd": "0.0123",
    "latency_ms": 840,
    "attributed_identity": "alice@example.com",
    "attributed_service": "checkout-api",
    "trace_id": "c0ffee…"
  }'

Never send message content

The schema has no field for prompt or completion text, by design. Send metadata only — tokens, model, cost, identity, latency. Argmin's pipeline does not store content.

Key fields

Field Required Notes
event_id ✅ Unique per event; used for dedup.
ingestion_layer ✅ Capture layer, e.g. application, gateway, proxy.
ingestion_timestamp ✅ RFC 3339 / ISO 8601 UTC.
provider ✅ openai, anthropic, bedrock, …
requested_model ✅ The model you asked for.
input_tokens / output_tokens — Drives token attribution.
estimated_cost_usd — Decimal string to avoid float drift.
attributed_identity / attributed_service — Who/what made the call.
trace_id — Correlate multi-step agent workflows.

The full field set (cost breakdown, energy/carbon, Kubernetes and SPIFFE identity, workflow correlation) is defined in the controlled schema: schemas/invocationevent/v1.schema.json. attribution_confidence, where present, is capped at 0.95 — Argmin never claims certainty.

POST /api/v1/events

For generic observability events that aren't a single model invocation. Same auth, also returns 202 Accepted.

Responses

Status Meaning
202 Accepted Event queued.
401 Unauthorized Missing/invalid credential.
422 Unprocessable Entity Payload failed schema validation — check required fields and estimated_cost_usd is a string.

Verifying it worked

After a successful 202, the event appears in the Argmin dashboard's Attribution / Recent view within ~30 seconds. See Verify & confirm.

Prefer no code changes? Use the drop-in proxy