# 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[​](#request "Enlace directo al request")

## Responses[​](#responses "Enlace directo al 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