API reference

Basics

• Host api.vizzit.studio, under the /api/v1/public/ prefix. Read-only: every request is a GET.
• Each request is for one store, and returns only what that store chose to show in Website and API.
• JSON with snake_case names. Ids are opaque strings: use them, never read meaning into them.
• Times are in UTC (RFC 3339, ending in Z). Opening hours carry the store’s time zone.
• Lists come a page at a time, with a cursor for the next page.

Authentication

Every request carries a website key made in Website and API. A key is publishable: it reads only public information, so it can sit in your page. It works only from the websites you allow. The examples on this site send it in an X-Vizzit-Key header; the final header is fixed at launch.

Resources

Store

The store’s name and its business’s name, address and phone, as customers see them.

Services and prices

Each service the store offers: its name, category, duration and price, with GST as the store shows it.

Running offers

Offers on sale now: their name, what they apply to, and when they end.

Opening hours

The store’s weekly hours, breaks and holidays, in its own time zone.

Team profiles

For team members the store shows: name, photo and short bio only.

Photos and videos

Pictures of the store and its work that customers approved for use.

Free times and bookingLater

Free times and online booking come with the next phase, with webhooks for your site.

Responses

A single item comes as data with meta.request_id; a list adds the cursor for the next page in meta.pagination. Responses are cached for a short time, so a change in Vizzit can take a moment to appear.

Rate limits

Each key has a limit on calls per minute, published with the first release. Over it, the API answers 429 RATE_LIMITED with retry_after_ms: wait that long, then try again.

Errors

An error comes as error, with code, message, details and request_id. Match on the code, never on the message. The codes come from the error list every Vizzit API shares; which one each key problem returns is fixed in the public contract at launch.

400 VALIDATION_ERROR

A parameter is wrong; details.fields says which. Do not retry unchanged.

400 CURSOR_INVALID

The cursor is old or was used with other filters. Start again from the first page.

401 UNAUTHENTICATED

The request did not prove who it is for.

403 FORBIDDEN

The request is understood but not allowed.

404 RESOURCE_NOT_FOUND

No such store or item, or one this key cannot see. Both look the same on purpose.

429 RATE_LIMITED

Too many calls. Wait retry_after_ms, then try again.

500 INTERNAL_ERROR

Something went wrong on our side. Quote the request_id if you write to us.