Sandbox

The sandbox is a second base URL that serves the same /v1 code as production, deployed to Vaki’s staging environment and backed by staging data. It exists so you can shape requests, read real responses and see real problem documents without creating anything on the live platform.

https://public-api-staging.vaki.co/v1

Everything else is identical: the same paths, the same DTOs, the same error codes, the same idempotency behaviour. Only the host changes.

Flip every example on this site

The Examples switcher in the header (and in the menu on a narrow screen) rewrites the base URL in every code block on every page, including what the copy button puts on your clipboard. Set it to Sandbox and the whole site is pasteable against staging. Your choice is remembered on this browser.

Read this before you build anything on it

The sandbox is shared infrastructure that we deploy to constantly. It is the environment Vaki’s own engineers use all day.

• Data may be reset. A vaki or a checkout link you created yesterday may not exist today. Nothing there is durable, and there is no restore.
• It may be briefly unavailable. Deploys land on it several times a day, and a request during one can fail or hang. That is not your integration.
• Behaviour can lead production. Staging sometimes runs a change that has not shipped yet, so a response there is not a promise about production today.
• It is not a place for a test suite. Do not point CI at it. A red build caused by somebody else’s deploy teaches you nothing, and you will learn to ignore it — which is worse than not having the test.

Use it to explore, to develop against, and to check a request shape. Do not use it as an environment you depend on.

Keys are per environment

A production key does not work against the sandbox, and a sandbox key does not work against production — they are different deployments with different databases. Ask for a sandbox key alongside your live one when your key is issued; see Authentication.

Keep the base URL beside the credential in configuration, never hardcoded in your client, so the two can never disagree:

# .env.sandbox
VAKI_API_BASE="https://public-api-staging.vaki.co"
VAKI_API_KEY="…your sandbox key…"

Your production file is the same two variables with the live base URL and the live key. Read both from configuration and the only difference between your environments is a file.

Check that it answers before you debug your own code

curl -i https://public-api-staging.vaki.co/v1/checkout_links \
  -H "Authorization: Bearer $VAKI_API_KEY"

A 405 or a problem document means the deployment is up and talking to you. A connection error or a timeout means the sandbox is having a moment — retry in a few minutes before looking at your client.

What is coming, and why it is better than this

The durable answer is test-mode keys: a vk_test_ key against production uptime, where test objects live in the same well-run environment as live ones and are simply marked as test. That is what makes a sandbox trustworthy enough to put in CI — production’s availability, with none of production’s consequences.

That is the plan, and it is why we are not investing in making this staging URL feel like a stable product. Key prefixes are being settled now; see Known limitations.

Next

• Quickstart — flip the switcher to Sandbox and run it
• Known limitations — what does not work yet, in writing
• Errors — the problem documents you will meet first