---
name: convova
description: Read a Convova event's program, people, organizations, and tickets for sale from the public API, build an event site or landing page from it, sell tickets through Convova's checkout, and add attendees from your own registration form with an API key. Use when the user mentions Convova, convova.app, an event slug on Convova, or wants to render or sell a Convova event on their own website.
license: MIT
metadata:
  author: convova
  docs: https://convova.app/docs
---

# Convova

Convova runs events: the program, the tickets, the door. A host publishes an event
there and can show and sell it on its own website through the public API. This skill
is how an agent does that correctly.

Base URL: `https://convova.app/api/public/v1`. No key, no session, any origin. It sees published
events only; a draft and an unknown slug both answer 404. The full reference with
request samples is at
[https://convova.app/docs/api](https://convova.app/docs/api).

## Pick the job

1. **Show an event on a site**: the program, the people, the organizations, what is
   for sale. Read [references/quickstart.md](references/quickstart.md), then
   [references/api.md](references/api.md) for every endpoint and field.
2. **Sell tickets from that site**: the five-step checkout. Read
   [references/selling.md](references/selling.md).
3. **Add attendees from your own registration form**: one route with an API key.
   Read [references/api-keys.md](references/api-keys.md).

## Rules that hold everywhere

- Every response is `{ data, error, pagination }`. `data` is the answer, or `null`
  when `error` holds a message. Check `error` before reading `data`.
- Lists return up to 1,000 items unless you pass `offset` or `limit`; then
  `pagination` is `{ offset, limit, total, hasMore }` and you page until `hasMore`
  is false. `limit` is at most 100. A list that may be long, people at a big
  event, is paged with `limit=100`.
- Times are ISO 8601 strings with an offset. Show them in the reader's timezone;
  never strip the offset or assume the server's. An event carries no timezone of
  its own: group a schedule by the reader's local day, or by a fixed `timeZone` in
  `Intl.DateTimeFormat` when your site knows the venue's.
- Money is an integer in the currency's minor unit with a lowercase ISO code:
  `{ unitAmount: 15000, currency: "usd" }` is $150.00. Format it, never divide
  blindly by 100; some currencies have no minor unit.
- A contributor is a person and an organization is a company; neither has a
  built-in role. Their capacity, Speaker, Sponsor, Judge, comes from their tags.
  Fetch the tag list, render one section per tag in the order the list returns,
  and order within a section by each item's `sortOrder`.
- Hidden items never appear in the API. Do not look for them.
- 404 means not published or not there. 400 names the first invalid field.
  429 means slow down: read `Retry-After` in seconds and wait that long.

## Never

- Never call routes outside `/api/public/v1` and `/api/integrations`; the rest
  of `/api` is the app's own, needs a session, and is not for sites.
- Never scrape the event page's HTML; the API has everything the page shows.
- Never store a `buyerToken` beyond the checkout it was made for, and never log
  it. It proves a buyer's email for a short while and nothing more.
- Never retry a 429 in a loop, and never fetch a list on every render; fetch at
  build time or cache for a minute.
- Never send an API key to a browser. It belongs on your server.

## Checking your work

- The event's own page on Convova is the reference render:
  `https://convova.app/events/{slug}`. Your sections should match its groups and order.
- A fresh checkout should quote before it asks for an email; a quote needs no
  buyer.
- If something on the event page is missing from the API, it is hidden on purpose.