# Vizen API: 15-minute quickstart

**Status:** current · **Verified:** 2026-10-25, checked against the passport,
product-list handler and request/response schema; no live credentials used
**Owner:** Vizen API documentation · **Serves:** `GET /docs/quickstart`

## 1. Minutes 0–5: obtain a key

Follow [Authentication: key and permissions](/docs/authentication) to issue a
key in the shop cabinet and supply it securely to your process as `VIZEN_TOKEN`.
That document owns the issuance, secret handling, permission and contour rules.
The examples use Bash, curl and jq. API base: `https://api.vizen.shop`.

Use the examples below with shell tracing and HTTP header logging disabled.
Never paste the key into source code, HTML, a report or a chat message.

## 2. Minutes 5–8: read the key's passport

Make this your first authenticated request:

```bash
PASSPORT=$(curl --fail-with-body -sS https://api.vizen.shop/v1/account/token \
  -H "Authorization: Bearer $VIZEN_TOKEN")
printf '%s\n' "$PASSPORT" | jq .
VIZEN_COMPANY_ID=$(printf '%s\n' "$PASSPORT" | jq -er '.company_id')
```

Read the actual `scopes`, `capabilities`, `contour` and `warnings` before choosing
an operation. The [generated scope reference](/docs/scopes.json) lists current rights.
Use `store.storefront_url` for the shop address. A preset name is
not evidence of access. Follow the [passport field guide](/docs/authentication#2-authenticate-and-read-the-passport)
for the meaning of each field and what to do when access is missing.

**Verify:** the passport succeeds and identifies the intended shop and workflow.
If it fails or names the wrong shop, stop here and follow the authentication
guide; do not test access by creating a product. This quickstart makes no writes.

## 3. Minutes 8–10: make a safe first GET

Read one catalogue entry without changing anything:

```bash
curl --fail-with-body -sS \
  "https://api.vizen.shop/products?page.number=1&page.limit=1&filter.company_id=$VIZEN_COMPANY_ID" \
  -H "Authorization: Bearer $VIZEN_TOKEN"
```

**Verify:** inspect `result.items` and `result.total` in the JSON response.
An empty shop can return an empty list; no fixture needs to be created.
The shop id comes from the passport; it selects the shop without granting
additional access. Both pagination parameters are supplied deliberately; the catalogue API uses
`/products`, without `/v1`. Read [Catalogue](/docs/catalogue) for filtering and
[the method schema](/openapi.json?scope=catalog) before expanding the request.

A **200 on this public catalogue endpoint does not prove private access**:
it can return an anonymous view. The passport from step 2 is the authentication
check. For a folder-bound or otherwise restricted key, continue only along the
workflow its passport allows; this GET does not widen its permissions.

## 4. Minutes 10–15: choose the guide for your task

| Your task | Continue here | What to verify next |
|---|---|---|
| Create products and upload photos; import a catalogue | [Catalogue import](/docs/catalog-import), including the product-and-photo recipe in §7.3 | Reread the created object and its gallery before publication. |
| Build a reusable family-card component | [Family-card tutorial](/docs/guide-family-cards) | Check two insertions and the rollback path. |
| Move an existing site or template | [Site transfer](/docs/transfer) | Follow its preflight and draft acceptance steps. |
| Build a shop page with your own HTML/CSS/JS | [Web coding](/docs/webcoding) | Choose the supported markup level and check the rendered page. |
| Configure platform blocks | [Widgets guide (prose)](/docs/widgets-area) | Reread nested props; consult [Widgets schema (JSON)](/docs/widgets) for the exact kind. |
| Collect form submissions | [Forms and leads](/docs/forms) | Check forms permissions separately from access to submitted lead data. |

Read one task guide, then only the reference sections it needs. Product creation,
photo upload and batch-import instructions live in [Catalogue import](/docs/catalog-import);
there is no second copy in this quickstart. Follow the task guide's checks before
publishing or reporting a result to the owner.

Find other tasks in the [documentation index](/docs/index.json). Agents can use
[the reading map](/llms.txt) and [the entry skill](/docs/skill/vizen-start).
For errors use [Troubleshooting](/docs/troubleshooting); for recent changes use
[Changelog](/docs/changelog).