Sandbox¶

The sandbox is a tenant-isolated test environment that serves synthetic but schema-faithful data, so your engineers can build and validate a Venturi integration without touching production data or real spend. Everything you learn in the sandbox transfers directly: responses carry the same schema, the same interpretation evidence card, and the same error model as production.

What the sandbox gives you¶

Synthetic, schema-faithful data. Attribution records, coverage, budgets, and exports are generated from the platform’s synthetic-data capability. The shapes are identical to production; only the underlying data is fabricated.
Disposable test credentials. Sandbox API keys and OAuth clients are issued for development and can be thrown away. They are scoped exactly like production credentials, so you exercise the real scope model.
A safe place for mutations. Create exports, register webhooks, rotate keys, and adjust budgets freely; nothing affects production or real billing.

Sandbox credentials never authorize against production

A sandbox credential is rejected by production, and a production credential is rejected by the sandbox. There is no path for sandbox traffic to read, write, or bill against real data: the isolation is enforced, not conventional.

Getting sandbox credentials¶

Your onboarding contact provisions a sandbox tenant on your Venturi instance and issues disposable test credentials. Treat them like any other secret, but know they carry no production authority.

The sandbox has no separate hostname. It uses the same base URL as production, chosen by the base-URL rule: https://api.venturi.systems on the SaaS tier, or your own instance host when self-hosted. The sandbox credential routes each call to your sandbox tenant: a JWT by its signed tenant_id claim, an API key by the tenant that owns it (see Tenant routing on the SaaS host).

Bash

export VENTURI_TOKEN="<sandbox-token>"
export VENTURI_BASE_URL="https://api.venturi.systems"  # self-hosted: your instance host

Running against the sandbox¶

Point your client or SDK at that base URL with the sandbox credential. The request and response surface is identical to production:

Bash

curl "$VENTURI_BASE_URL/v1/attribution?limit=5" \
  -H "Authorization: Bearer $VENTURI_TOKEN"

JSON

{
  "data": [
    {
      "id": "attr_sbx_01HF82RCN2GFRCBZH5KVSKZ4HB",
      "provider": "anthropic",
      "served_model": "claude-sonnet-4-6",
      "cost_usd": "0.0089",
      "output_state": "strongly_inferred",
      "interpretation": {
        "stage_origin": "stage_b",
        "confidence": 0.88,
        "confidence_band": "chargeback_ready",
        "evidence_basis": "service_resolved",
        "model_version": "rail-2025.11",
        "degradation_state": "none",
        "freshness": "fresh",
        "export_eligibility": "eligible"
      }
    }
  ],
  "page": {
    "next_cursor": "eyJzb3J0IjoiLWNyZWF0ZWRfYXQifQ.IrYusFGVqRpbbQNLuBAHozf0AEG04Xie",
    "limit": 5,
    "has_more": true
  }
}

Because the interpretation block, output states, confidence semantics, and error codes are the same as production, you can build and verify your handling of real-world cases (high vs. low confidence, degraded serving, export eligibility) entirely in the sandbox.

Testing webhooks¶

Register a webhook against the sandbox to exercise the full lifecycle (ownership verification, the SSRF egress guard, signed delivery, and retries) without production traffic. The verification handshake and signing work exactly as in production, so the receiver you validate here is the receiver you ship.

Bash

# A sandbox endpoint gets its own signing secret; store it in your secret manager.
VENTURI_WEBHOOK_SECRET="$(openssl rand -hex 32)"

curl -X POST "$VENTURI_BASE_URL/api/v1/webhooks" \
  -H "Authorization: Bearer $VENTURI_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "url": "https://hooks.example.com/venturi-test",
  "events": ["export.completed", "budget.threshold.crossed"],
  "hmac_secret": "$VENTURI_WEBHOOK_SECRET"
}
EOF

See webhooks for the signing secret, verification, signatures, and retry behavior.

Sample apps¶

Each SDK ships reference sample apps (a chargeback exporter, a webhook receiver, and an anomaly-alert forwarder) that run end-to-end against the sandbox using only the artifacts in your onboarding bundle. They are the fastest way to confirm your environment is wired correctly before you write integration code.

Moving to production¶

When your integration works against the sandbox, the move to production is a credential swap, with no other code changes:

Obtain production credentials with the least scope your integration needs.
Keep the same base URL; the production credential routes each call to your production tenant: a JWT by its signed tenant_id claim, an API key by the tenant that owns it (see Tenant routing on the SaaS host).
Keep idempotency keys and webhook signature verification in place: they behave identically in production.

Build sandbox-first

Develop and test every integration against the sandbox before pointing it at production data. It is the supported, safe path to a working integration, and the schema parity means there are no surprises at cutover.

Next steps¶

REST API: the full request/response contract.
SDKs: typed clients and sample apps.
Webhooks: event-driven integrations.

Give feedback on this page

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

Copy page details

Docs feedback: Sandbox
Page: https://docs.venturi.systems/developers/sandbox/