Skip to content

Deployment modes and the API base URL

Venturi has two deployment modes with one identical API contract. Which mode you run determines exactly one thing in the developer docs: the base URL you substitute into every example.

Compared on SaaS tier Self-hosted (in-VPC)
Where the data plane runs A dedicated, single-tenant data plane operated by Venturi, pinned to your residency lane A dedicated data plane deployed inside your own VPC and cloud account
Tenant API base URL https://api.venturi.systems https://<your-venturi-instance> (the host your onboarding contact gives you)
Dashboard host https://app.venturi.systems Your own instance host
API contract Identical OpenAPI contract in both modes Identical OpenAPI contract in both modes
Data residency Residency lane fixed at onboarding; fails closed Stays entirely within your environment

Either way the deployment is dedicated to you: Venturi does not pool your transactional or AI-invocation data with other tenants. You choose the mode during onboarding, before any connector setup.

On the SaaS tier, every tenant calls the same api.venturi.systems hostname, and the credential on each request decides which dedicated data plane it reaches (see Tenant routing on the SaaS host).

The base-URL rule

Every API example in these docs uses the placeholder https://<your-venturi-instance>. Substitute it by deployment mode:

  • SaaS tier: substitute https://api.venturi.systems.
  • Self-hosted: substitute your own instance host. Never point a self-hosted deployment at api.venturi.systems; it is not your tenant API host in that mode.
  • Sandbox: use the same base URL as production with a sandbox credential; the credential routes each call to your sandbox tenant (see Sandbox).

The host exposes three versioned surfaces. Choose the root by task; the deployment mode changes the host, not the path contract.

Surface Root Use it for
Tenant data API /v1 Attribution reads, analytics, OAuth, and FOCUS exports
Product API /api/v1 Ingestion, credentials, webhooks, and tenant administration
Partner API /api/partner/v1 Partner-scoped connector and marketplace integrations

For example, a tenant attribution read uses the tenant data API:

Bash
curl "https://<your-venturi-instance>/v1/attribution?limit=5" \
  -H "Authorization: Bearer $VENTURI_TOKEN"

Tenant routing on the SaaS host

Every request to https://api.venturi.systems reaches your dedicated data plane through the credential it carries, never through a tenant identifier you put in the URL, request body, or a header:

Request How Venturi identifies your tenant
Bearer JWT (Authorization: Bearer <jwt>) The signed tenant_id claim in the token.
API key (X-API-Key: <key>) The key carries no claim. Venturi looks the key up, verifies it against the stored salted hash, and routes the request to the tenant that owns the key.
Token request (POST /v1/oauth/token) The client_id, which is registered to exactly one tenant; the token it issues carries that tenant’s tenant_id.
Drop-in proxy call (/api/v1/proxy/...) The one-way fingerprint of the provider API key the call carries, which must be registered to your tenant (see Tenant admission).
OAuth discovery document, JWKS, /healthz, /readyz None. These unauthenticated routes return the same public, tenant-free response to every caller.

A tenant identifier in the URL or request body cannot override the credential’s tenant, and a mismatch returns 403 TENANT_MISMATCH. The discovery document and JWKS are shared on the SaaS host, so if you validate Venturi tokens yourself, check the tenant_id claim as well as the signature. On the SaaS tier the health probes report the shared API host, not your data plane; your tenant’s component status and incidents are on the in-product status surface.

Where Venturi runs

In self-hosted mode, the entire data plane (interceptor, processor, dashboard, and stores) runs inside your own cloud trust boundary, and your operational data never leaves it. In SaaS mode, Venturi operates that same data plane for you, single-tenant, region-pinned to the residency lane you declare at onboarding. The security architecture and tenant isolation pages describe the boundary in both modes.

Choose the cloud and region

Connect evidence from AWS, Azure, and Google Cloud through their cloud onboarding guides. The cloud account you connect is an evidence source; it does not select where your Venturi data plane runs.

Choose the hosting mode and approved residency lane during onboarding. In self-hosted mode, deploy inside your own cloud account and trust boundary. In SaaS mode, use the dedicated Venturi-operated environment named for your tenant. Confirm the selected region, provider service availability, and permitted cross-region paths before activating a source.

Cloud-specific walkthroughs use example regions to make configuration concrete. Replace each example with the region approved for your deployment and source account. A walkthrough’s example region is not a universal Venturi prerequisite. The residency contract governs processing, exports, aggregation, and support access.

The control plane is separate

One surface is the same in both modes and is not a tenant API: https://api.venturi.systems/control/v1 is the control plane. It is anonymous and CDN-cacheable, serves only signed, public, customer-data-free artifacts (pricing catalogs, release metadata, and the energy catalog that feeds the public AI Energy Index), and carries no customer data in either direction. It is distinct from the tenant API in path root, authentication, and cache policy.

Where to go next

Give feedback on this page

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

Copy page details 
Docs feedback: Deployment modes and the API base URL
Page: https://docs.venturi.systems/developers/deployment-modes/