Create Viz
POST/v1/viz
Create a dashboard, chart or blank viz, and its initial file tree.
If this call times out, the dashboard may already exist. The row is written before the slow part — the template render, the git commit, the upload — and the response is assembled after it, so a lost answer usually means a real dashboard. Repeating the call then makes a second one: a name collision is resolved by suffixing the slug, not by refusing.
Send an idempotencyKey and that stops being true. Any opaque string you can
reproduce will do; re-send the SAME key with the SAME body and you get the
first dashboard back, marked idempotentReplay: true, instead of another one.
The key is unique within the account and lives as long as the dashboard it
created. Re-using it for a different body is refused rather than answered
with the wrong dashboard, and re-sending it while the first create is still
running tells you so and names the viz to poll.
Check idempotencyKey on the response: if you sent one and it is absent, the
key was not honoured and a repeat of that call would create a second
dashboard.
Request
Responses
- 201
- 403
- 404
- 409
- 422
Successful Response
viewMode=public refused: public sharing is off for the account (PUBLIC_SHARING_DISABLED), or the caller is an API key and an admin has not turned on "Allow API keys to publish publicly" — nothing is created.
Not found
Nothing was created, and the body is not what is wrong. idempotency_key_reused: the key already created a dashboard from a different request (vizId names it). viz_creation_in_progress: the key's first create is still running (vizId and ageSeconds); poll that viz and wait for mainCommitSha. idempotency_key_claimed: another call in the account holds the key and its dashboard is not readable with this credential. Also the two slug refusals, which carry a plain string detail.
Validation Error