Skip to content

Developer platform

The Venturi developer platform exposes the same attribution graph that powers the dashboard as a first-class, versioned API. Read attributed cost, energy, and carbon; create exports; manage budgets, API keys, and webhooks; and stream attribution events into your own tooling: all over a stable REST contract with typed SDKs, a sandbox, and a deprecation policy designed to operate for years without breaking downstream systems.

Every tenant runs on a dedicated data plane: inside your own cloud account when self-hosted, or operated single-tenant by Venturi on the SaaS tier (see Deployment modes). Every response is tenant-scoped, and no prompt or completion content is ever stored or returned: attribution results carry metadata, evidence, and confidence, never the underlying AI content.

What you can build

Goal Surface
Push AI inference events into the attribution pipeline Ingestion API
Read attributed cost / energy / carbon for chargeback REST API: GET /v1/attribution
Generate FOCUS-aligned chargeback exports REST API: POST /v1/exports/focus
React to attribution, coverage, budget, and connector events Webhooks
Ship integrations in TypeScript or Python SDKs
Develop and test against synthetic data Sandbox
Plan for limits, versions, and deprecations Versioning & rate limits

The surfaces

Venturi exposes three API surfaces from the same deployment host. Use the tenant data API for attributed results and exports, the product API for configuration and ingestion, and the partner API for partner-scoped integrations.

All three surfaces have a ≥12-month deprecation window. Product API operations are permission-scoped; Partner API tokens are partner-scoped.

Surface Audience Base path
Tenant data API Your engineers and FinOps teams /v1
Product API Tenant admins and event producers /api/v1
Partner API iPaaS / connector / marketplace partners /api/partner/v1

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. Every path in these pages is relative to that base.

Core principles

The developer platform is built on a small set of guarantees you can design against:

  • Read-only by default. Connectors and integrations read; they never write to your AI systems. Attribution runs asynchronously, off the request path of your AI traffic. The optional drop-in proxy, which does sit in that path, runs the decision-time interceptor and fails open.
  • Fail-open never blocks your AI. Venturi processing never blocks or fails AI traffic it has admitted: a slow or unavailable Venturi dependency means the request is forwarded unmodified. In Active (Gate) mode, Venturi issues a signed enforcement recommendation and your own enforcement point decides whether to apply it. Attribution that cannot be resolved is reported with its actual output state (see confidence and evidence) rather than guessed. Security-relevant operations (authentication, authorization, tenant isolation, exports, and billing) fail closed, so the drop-in proxy rejects a provider key that is not registered to your tenant before it forwards anything (see tenant admission).
  • No content capture. Request and response bodies of your AI calls are never stored. Error and event payloads are scrubbed of any content keys.
  • Every result is explainable. Attribution responses carry an evidence card: which pipeline stage produced the result, its confidence band, the evidence basis, the model version, the current degradation state, and data freshness.
  • Stable for years. Within a major version no field is removed, renamed, retyped, or narrowed, and no closed enum loses a member. Breaking changes ship as a new major version served in parallel.

A first call

Every read is authenticated and tenant-scoped. The smallest useful call lists recent attribution records:

Bash
curl "https://<your-venturi-instance>/v1/attribution?limit=5" \
  -H "Authorization: Bearer $VENTURI_TOKEN"
JSON
{
  "data": [
    {
      "id": "attr_01HF8SNWNW4VMC42M411HGMRWC",
      "invocation_id": "inv_01HF8YKE42NXAT95733Q9N16Q2",
      "provider": "openai",
      "served_model": "gpt-4o",
      "cost_usd": "0.0142",
      "output_state": "strongly_inferred",
      "interpretation": {
        "stage_origin": "stage_b",
        "confidence": 0.91,
        "confidence_band": "chargeback_ready",
        "evidence_basis": "identity_resolved",
        "model_version": "rail-2025.11",
        "degradation_state": "none",
        "freshness": "fresh",
        "export_eligibility": "eligible"
      }
    }
  ],
  "page": {
    "next_cursor": "eyJzb3J0IjoiLWNyZWF0ZWRfYXQifQ.IrYusFGVqRpbbQNLuBAHozf0AEG04Xie",
    "limit": 5,
    "has_more": true
  }
}

Continue to the REST API reference for authentication, scopes, pagination, idempotency, and the full error model.

Where to go next

Give feedback on this page

Sign in to send feedback. Opens in a new tab.

Copy page details 
Docs feedback: Developer platform
Page: https://docs.venturi.systems/developers/