Ingestion API¶

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

Base URL

Examples use the placeholder https://<your-venturi-instance>. On the SaaS tier, substitute https://api.venturi.systems; self-hosted, substitute your own instance host. See Deployment modes. All paths below are relative to that base.

Authentication¶

Send either header:

Authorization: Bearer <jwt>

X-API-Key: <key>

Venturi 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-venturi-instance>/api/v1/invocations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VENTURI_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"
  }'

Recommended request¶

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

curl -X POST https://<your-venturi-instance>/api/v1/invocations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VENTURI_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. Venturi’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`	Optional	Drives token attribution.
`estimated_cost_usd`	Optional	Decimal string to avoid float drift.
`attributed_identity` / `attributed_service`	Optional	Who/what made the call.
`trace_id`	Optional	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: the versioned event schema (schemas/invocationevent/v1.schema.json in the platform repository, shared during onboarding). attribution_confidence, where present, is capped at 0.95; Venturi 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 Venturi dashboard’s Attribution / Recent view within ~30 seconds. See Verify & confirm.

Prefer not to touch application code? Use the drop-in proxy