{
  "openapi": "3.0.3",
  "info": {
    "title": "VICO Events API",
    "version": "1.4.1",
    "x-changelog": [
      {
        "version": "1.4.1",
        "date": "2026-11-06",
        "changes": [
          {
            "type": "fixed",
            "text": "`?lang=` with a region code now picks the matching Chinese script, as documented: `zh-HK`, `zh-TW` and `zh-MO` get the `zh-Hant` translation and labels, `zh-CN` and `zh-SG` get `zh-Hans`. Before, an organizer with both scripts could serve either, and categories and event text could come out in different scripts. Applies to events, categories, tags, the ticket page and share previews."
          }
        ]
      },
      {
        "version": "1.4.0",
        "date": "2026-11-06",
        "changes": [
          {
            "type": "added",
            "text": "`languages` on `GET /v1/events`: the organizer's languages, default first. The widget uses it to show a visitor whose browser language the organizer doesn't offer the default language instead."
          }
        ]
      },
      {
        "version": "1.3.0",
        "date": "2026-11-06",
        "changes": [
          {
            "type": "changed",
            "text": "Labels of the platform's general categories (`categoryLabel` on events, `label` on `GET /v1/categories`) now fall back to English, not the organizer's default language, when `?lang=` has no label of its own. Company categories, tags and event content still fall back to the organizer's default. Slugs are unchanged."
          }
        ]
      },
      {
        "version": "1.2.0",
        "date": "2026-10-28",
        "changes": [
          {
            "type": "added",
            "text": "`captchaProvider` on events (`turnstile`, `recaptcha_v2` or `recaptcha_v3`): bot protection can now use Google reCAPTCHA v2 (checkbox) or v3 (invisible, score-based) as well as Cloudflare Turnstile. `captchaSiteKey` belongs to that provider; send that provider’s token as `captchaToken`."
          }
        ]
      },
      {
        "version": "1.1.0",
        "date": "2026-10-28",
        "changes": [
          {
            "type": "changed",
            "text": "Publishing an event (`PATCH /v1/events/{id}` with `status: \"published\"`) on a paid plan now needs the account to send attendee email through its own SMTP server, saved and test-sent in the dashboard; until then it returns `409 smtp_required`. The free trial keeps the platform sender."
          }
        ]
      },
      {
        "version": "1.0.1",
        "date": "2026-10-23",
        "changes": [
          {
            "type": "changed",
            "text": "Versioning policy added to the reference, with this changelog. No endpoint changed."
          }
        ]
      },
      {
        "version": "1.0.0",
        "date": "2026-09-22",
        "changes": [
          {
            "type": "added",
            "text": "First published version of the v1 API: events, registrations and check-in, tickets, categories and tags, images, broadcasts, email templates, webhooks, reports, GDPR and platform endpoints."
          }
        ]
      }
    ],
    "description": "REST API for integrating events, registrations, and tickets into your own website, app, or back-office.\n\n## Authentication\n\nTwo Stripe-style bearer keys, shown in the dashboard (API keys tab):\n\n- **Publishable** (`pk_…`) — safe in browsers and apps: read published events, submit registrations, read categories/tags.\n- **Secret** (`sk_…`) — **your server only**: everything, including attendee PII, check-in, exports, broadcasts, templates, and webhooks.\n\nSend either as `Authorization: Bearer <key>`. Rotating a key immediately revokes the old one. Missing/invalid key → `401`; a publishable key on a management endpoint → `403`.\n\n**Plans.** The secret key and webhooks are included in the Pro and Business plans. On Basic the publishable key (and the widget) works as usual, but every secret-key request is refused with `403 plan_limit`, and adding, testing or pushing to a webhook endpoint returns `409 plan_limit`.\n\n## Localization\n\nPublic content endpoints accept `?lang=<BCP-47>` (e.g. `zh-Hant`). Resolution: exact locale → language family → the organizer's default (the platform's general categories fall back to English instead). Identifiers never localize — category/tag slugs, custom-field keys, and option **values** are stable; only display labels change.\n\n## Rate limits\n\nPer IP: 200 requests/min globally; stricter on sensitive endpoints (registrations 10/min/event, exports 10/min, broadcasts 5/10min). `429` means back off.\n\n## Errors\n\nEvery error is `{ \"error\": <stable code>, \"message\": <human text> }`. Codes include `invalid_request`, `not_found`, `conflict`, `plan_limit`, `trial_expired`, `invalid_locale`, `already_registered`, `sold_out`, `registration_closed`, `invalid_answers`, `unknown_placeholders`, `captcha_failed`.\n\nDashboard-session-only endpoints (login, profile, company settings, team) are out of scope here — they are not part of the key-authenticated integration surface.\n\n## Versioning\n\nThe API is versioned in the path (`/v1/`). Backwards-compatible changes — new endpoints, new optional request fields, new response fields, new webhook event types — ship within a version at any time, so ignore fields you do not recognise. Changes that would break an existing integration only ever arrive as a new path version. When a version is retired, owners of accounts that hold API keys get at least 12 months' notice and the old version keeps working, with security fixes, for that whole period. Every change is listed under **What's new** with the spec version it shipped in."
  },
  "servers": [
    {
      "url": "/",
      "description": "Your VICO Events host"
    }
  ],
  "tags": [
    {
      "name": "Events",
      "description": "Public listing (publishable key) and full event management (secret key). Recurring events carry `recurring: true` plus an `occurrences` array; attendees register per date via `occurrenceId`."
    },
    {
      "name": "Registrations & check-in",
      "description": "Registration submission is public (publishable key); attendee lists, cancel/reactivate/promote, and check-in need the secret key."
    },
    {
      "name": "Tickets",
      "description": "Token-authenticated — the ticket URL's token *is* the credential; no API key."
    },
    {
      "name": "Categories & tags",
      "description": "Company categories (plus the platform's general set) and tags. Slugs are permanent; labels translate."
    },
    {
      "name": "Images",
      "description": "Raw-body uploads — JPEG/PNG/WebP up to 10 MB, validated by magic bytes."
    },
    {
      "name": "Broadcasts",
      "description": "\"Message attendees\" — paid plans, metered by monthly recipient-message quota."
    },
    {
      "name": "Email templates",
      "description": "Per-company confirmation/reminder templates with shortcodes: [name] [email] [ticket_url] [event_title] [event_date] [event_time] [event_location] [event_message] [company_name]."
    },
    {
      "name": "Webhooks",
      "description": "HMAC-SHA256-signed deliveries with retries. See docs/WEBHOOKS.md for verification code."
    },
    {
      "name": "Reports",
      "description": "Registration/view analytics."
    },
    {
      "name": "GDPR",
      "description": "Right-to-erasure execution."
    },
    {
      "name": "Platform",
      "description": "Health and utility endpoints."
    }
  ],
  "components": {
    "securitySchemes": {
      "PublishableKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "pk_… — browser-safe: published events + registrations only."
      },
      "SecretKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "sk_… — server-side, full management access. Pro and Business plans; on Basic → 403 plan_limit."
      }
    },
    "parameters": {
      "lang": {
        "name": "lang",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "BCP-47 locale for localized labels/content (e.g. `zh-Hant`)."
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200
        },
        "description": "Page size. Omit (with offset) for the full list."
      },
      "offset": {
        "name": "offset",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 0
        },
        "description": "Rows to skip. Page with `offset += limit` until `offset >= total`."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine-readable code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable; may change."
          }
        },
        "required": [
          "error"
        ]
      },
      "CustomField": {
        "type": "object",
        "description": "Registration form field definition. `key` and option `value`s are permanent identifiers; labels translate per locale.",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-z0-9_]+$"
          },
          "label": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "textarea",
              "email",
              "phone",
              "number",
              "date",
              "url",
              "select",
              "radio",
              "multiselect",
              "checkbox"
            ]
          },
          "required": {
            "type": "boolean"
          },
          "helpText": {
            "type": "string",
            "nullable": true
          },
          "options": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "key",
          "label",
          "type"
        ]
      },
      "DescriptionBlock": {
        "type": "object",
        "description": "Ordered \"about this event\" section. `type` is one of `text` (Markdown subset — render with a whitelist parser, never as HTML), `image` (`urls` 1–10, optional `layout` text-left/text-right pairs them with `text`), `video` (YouTube/Vimeo URL; responses add `provider` + `videoId` — build embeds from those), `faq` (`items: [{id,q,a}]`), `lineup` (`items: [{id,name,tagline?,bio?,photo?}]`), `agenda` (`items: [{id,start,end?,title,desc?,host?}]`).",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "image",
              "video",
              "faq",
              "lineup",
              "agenda"
            ]
          },
          "text": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "alt": {
            "type": "string",
            "nullable": true
          },
          "layout": {
            "type": "string",
            "enum": [
              "full",
              "text-left",
              "text-right"
            ]
          },
          "provider": {
            "type": "string",
            "enum": [
              "youtube",
              "vimeo"
            ],
            "readOnly": true
          },
          "videoId": {
            "type": "string",
            "readOnly": true
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "id",
          "type"
        ]
      },
      "Occurrence": {
        "type": "object",
        "description": "One date of a recurring event. Public views list future active dates only.",
        "properties": {
          "id": {
            "type": "string"
          },
          "startsAt": {
            "type": "string",
            "format": "date-time"
          },
          "endsAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "capacity": {
            "type": "integer",
            "nullable": true,
            "description": "Per-date override; null = event default."
          },
          "spotsLeft": {
            "type": "integer",
            "nullable": true
          },
          "registrationStatus": {
            "type": "string",
            "enum": [
              "open",
              "scheduled",
              "closed",
              "disabled"
            ]
          },
          "waitlistOpen": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "cancelled"
            ],
            "description": "Management payloads only."
          },
          "registrationCount": {
            "type": "integer",
            "description": "Management payloads only."
          }
        }
      },
      "Organizer": {
        "type": "object",
        "description": "Effective \"Hosted by\" identity: per-event overrides falling back to the company profile.",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "contactEmail": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "nullable": true
          },
          "logo": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Event": {
        "type": "object",
        "description": "Public event shape. Management payloads (secret key) additionally carry `status`, `listed`, `registrationEnabled`, `publishStartsAt/EndsAt`, `confirmationMessage`, `reminderMessage`, `translations`, `registrationCount`, `waitlistEnabled`, `waitlistLimit`, `waitlistedCount`, `seriesCapacity`, `seriesSpotsLeft`, `createdAt`, `updatedAt`.",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Plain-text card summary."
          },
          "descriptionBlocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DescriptionBlock"
            },
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true
          },
          "startsAt": {
            "type": "string",
            "format": "date-time",
            "description": "For recurring events, the NEXT upcoming date."
          },
          "endsAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "capacity": {
            "type": "integer",
            "nullable": true,
            "description": "Recurring events: public value is the series total over upcoming dates."
          },
          "spotsLeft": {
            "type": "integer",
            "nullable": true,
            "description": "null = unlimited. Reported as 0 while a waitlist queue holds freed spots."
          },
          "category": {
            "type": "string",
            "nullable": true,
            "description": "Stable slug."
          },
          "categoryLabel": {
            "type": "string",
            "nullable": true,
            "description": "Localized display label."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Stable slugs."
          },
          "tagLabels": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          },
          "bannerUrl": {
            "type": "string",
            "nullable": true
          },
          "thumbnailUrl": {
            "type": "string",
            "nullable": true
          },
          "customFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomField"
            },
            "nullable": true
          },
          "registrationStatus": {
            "type": "string",
            "enum": [
              "open",
              "scheduled",
              "closed",
              "disabled"
            ]
          },
          "registrationOpensAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "registrationClosesAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "waitlistOpen": {
            "type": "boolean"
          },
          "recurring": {
            "type": "boolean"
          },
          "nextOccurrenceAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "occurrences": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Occurrence"
            }
          },
          "organizer": {
            "$ref": "#/components/schemas/Organizer"
          },
          "shareUrl": {
            "type": "string",
            "nullable": true,
            "description": "Rich-share link (`/s/<eventId>`) once the company sets its events page URL."
          },
          "timezone": {
            "type": "string",
            "nullable": true,
            "description": "IANA zone the event's wall-clock times are meant in (account-level). Datetimes stay UTC instants."
          },
          "doorsOpenMins": {
            "type": "integer",
            "nullable": true
          },
          "minAge": {
            "type": "integer",
            "nullable": true
          },
          "parking": {
            "type": "string",
            "enum": [
              "free",
              "paid",
              "none"
            ],
            "nullable": true
          },
          "captchaSiteKey": {
            "type": "string",
            "nullable": true,
            "description": "Tenant-configured bot-protection site key for `captchaProvider`. When present, browser registrations must include a verified captchaToken (the widget handles this automatically)."
          },
          "captchaProvider": {
            "type": "string",
            "nullable": true,
            "enum": [
              "turnstile",
              "recaptcha_v2",
              "recaptcha_v3"
            ],
            "description": "Which provider `captchaSiteKey` belongs to: Cloudflare Turnstile, Google reCAPTCHA v2 (\"I’m not a robot\" checkbox) or reCAPTCHA v3 (invisible; execute with action `register`). Null when bot protection is off."
          }
        }
      },
      "EventInput": {
        "type": "object",
        "description": "Create/update body. All fields optional on PATCH. `category`/`tags` accept label text in any configured language or the slug itself (find-or-create). `translations.<locale>` overlays title/description/location/messages, `descriptionBlocks` text (keyed by block/item id), and `customFieldLabels`.",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 300
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "descriptionBlocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DescriptionBlock"
            },
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true
          },
          "startsAt": {
            "type": "string",
            "format": "date-time"
          },
          "endsAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "capacity": {
            "type": "integer",
            "nullable": true
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 10
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "cancelled"
            ]
          },
          "publishStartsAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "publishEndsAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "registrationEnabled": {
            "type": "boolean"
          },
          "registrationOpensAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "registrationClosesAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "waitlistEnabled": {
            "type": "boolean"
          },
          "waitlistLimit": {
            "type": "integer",
            "nullable": true
          },
          "doorsOpenMins": {
            "type": "integer",
            "nullable": true
          },
          "minAge": {
            "type": "integer",
            "nullable": true
          },
          "parking": {
            "type": "string",
            "enum": [
              "free",
              "paid",
              "none"
            ],
            "nullable": true
          },
          "organizerName": {
            "type": "string",
            "nullable": true
          },
          "contactEmail": {
            "type": "string",
            "nullable": true
          },
          "organizerUrl": {
            "type": "string",
            "nullable": true
          },
          "organizerLogo": {
            "type": "string",
            "nullable": true
          },
          "confirmationMessage": {
            "type": "string",
            "nullable": true,
            "description": "Per-event [event_message] paragraph in confirmation emails."
          },
          "reminderMessage": {
            "type": "string",
            "nullable": true
          },
          "customFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomField"
            },
            "nullable": true
          },
          "occurrences": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Occurrence"
            },
            "description": "Replace-set: items with `id` update, missing ids delete (409 if that date has registrations — cancel instead), new items create."
          },
          "recurrence": {
            "type": "string",
            "nullable": true,
            "description": "Free-form pattern JSON the dashboard uses to regenerate the list."
          },
          "translations": {
            "type": "object",
            "additionalProperties": {
              "type": "object"
            }
          }
        }
      },
      "Registration": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "answers": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "type": "string"
            },
            "description": "Custom-field key → canonical option value(s); multiselect joins with \", \"; checkbox stores \"yes\"."
          },
          "status": {
            "type": "string",
            "enum": [
              "confirmed",
              "waitlisted",
              "cancelled"
            ]
          },
          "locale": {
            "type": "string",
            "nullable": true
          },
          "occurrenceId": {
            "type": "string",
            "nullable": true
          },
          "occurrenceStartsAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ticketUrl": {
            "type": "string",
            "nullable": true,
            "description": "Hosted QR ticket page; the embedded token is the credential."
          },
          "checkedInAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Permanent identifier, derived from the default-language label at creation."
          },
          "label": {
            "type": "string",
            "description": "Localized for the requested `lang`."
          },
          "labels": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Full per-language map (management view)."
          }
        }
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Subscribed types, e.g. event.published, registration.created."
          },
          "enabled": {
            "type": "boolean",
            "description": "Auto-disabled after 10 consecutive failures (owner emailed)."
          },
          "secret": {
            "type": "string",
            "description": "whsec_… signing secret — returned once at creation."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  },
  "paths": {
    "/v1/health": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Health check",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "List events",
        "description": "Publishable key: published events currently inside their publish window (recurring events with no upcoming dates drop out). Secret key: every event, with management fields. Pagination slices after visibility/category/tag filters, so offsets are stable against what the caller can see.",
        "security": [
          {
            "PublishableKey": []
          },
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/lang"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by category slug."
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by tag slug."
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Event list with paging metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer",
                      "nullable": true
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "languages": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "The organizer's languages (BCP-47), default first.",
                      "example": ["en", "zh-Hant"]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "Create event (draft)",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "plan_limit / invalid_locale.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{id}": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Fetch one event",
        "security": [
          {
            "PublishableKey": []
          },
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/lang"
          }
        ],
        "responses": {
          "200": {
            "description": "The event.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found, unpublished, or outside its publish window (publishable view)."
          }
        }
      },
      "patch": {
        "tags": [
          "Events"
        ],
        "summary": "Update event",
        "description": "Partial update; also flips `status` (`draft → published ⇄ cancelled`). Plan limits are enforced on publish and on custom-field counts (`409 plan_limit`). On paid plans, publishing also needs the account’s own SMTP set up and test-sent (`409 smtp_required`).",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated event (management shape)."
          },
          "409": {
            "description": "plan_limit / smtp_required / invalid_locale.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Events"
        ],
        "summary": "Delete event",
        "description": "Blocked with `409` while registrations exist — cancel the event instead. Reclaims uploaded images.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "409": {
            "description": "Has registrations."
          }
        }
      }
    },
    "/v1/events/{id}/views": {
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "Count a detail view",
        "description": "Fire-and-forget, PII-free per-day counter (the widget calls this when a visitor opens an event's detail). No body.",
        "security": [
          {
            "PublishableKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Counted."
          }
        }
      }
    },
    "/v1/events/{id}/registrations": {
      "get": {
        "tags": [
          "Registrations & check-in"
        ],
        "summary": "List an event's registrations",
        "description": "Contains PII — management only. Ordered oldest first.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "confirmed",
                "waitlisted",
                "cancelled"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Registrations with paging metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "registrations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Registration"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer",
                      "nullable": true
                    },
                    "offset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Registrations & check-in"
        ],
        "summary": "Register an attendee",
        "description": "Recurring events require `occurrenceId` (one registration per email per date). When the event/date is full but `waitlistOpen` is true, the same request succeeds with `status: \"waitlisted\"`. Never send a `website` field — it is a bot honeypot.",
        "security": [
          {
            "PublishableKey": []
          },
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "locale": {
                    "type": "string",
                    "description": "Language of the attendee's confirmation/reminder emails and ticket page."
                  },
                  "occurrenceId": {
                    "type": "string",
                    "description": "Required for recurring events."
                  },
                  "answers": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Custom-field key → canonical option value(s)."
                  },
                  "captchaToken": {
                    "type": "string",
                    "description": "Bot-protection token from the event’s `captchaProvider` (Turnstile, or reCAPTCHA v2/v3 — for v3 executed with action `register`) — required for publishable-key requests when the event’s captchaSiteKey is set. Secret-key calls are never challenged."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registered (or waitlisted).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "registration": {
                      "$ref": "#/components/schemas/Registration"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_request / invalid_answers (with per-field messages) / captcha_failed."
          },
          "409": {
            "description": "already_registered / sold_out / registration_closed / plan_limit / trial_expired / plan_expired (the trial or plan period has ended — registrations pause until a plan is chosen or renewed)."
          }
        }
      }
    },
    "/v1/events/{id}/registrations/export": {
      "post": {
        "tags": [
          "Registrations & check-in"
        ],
        "summary": "Password-protected Excel export",
        "description": "Real Office AES encryption; includes cancelled records and all custom-field columns. Password: ≥8 chars with a letter and a number.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "password"
                ],
                "properties": {
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Encrypted .xlsx file."
          }
        }
      }
    },
    "/v1/registrations/{id}/cancel": {
      "post": {
        "tags": [
          "Registrations & check-in"
        ],
        "summary": "Cancel a registration",
        "description": "Frees the spot — but never auto-promotes: freed spots are held for the waitlist queue until you promote someone.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cancelled registration."
          }
        }
      }
    },
    "/v1/registrations/{id}/reactivate": {
      "post": {
        "tags": [
          "Registrations & check-in"
        ],
        "summary": "Restore a cancelled registration",
        "description": "Capacity is re-checked — restore can't oversell (`409 sold_out`).",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Restored."
          },
          "409": {
            "description": "sold_out."
          }
        }
      }
    },
    "/v1/registrations/{id}/promote": {
      "post": {
        "tags": [
          "Registrations & check-in"
        ],
        "summary": "Promote a waitlisted registration",
        "description": "The ONLY way waitlisted becomes confirmed; the attendee gets the standard confirmation email with their ticket. Capacity re-checked.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Promoted."
          },
          "409": {
            "description": "sold_out."
          }
        }
      }
    },
    "/v1/events/{id}/checkin": {
      "post": {
        "tags": [
          "Registrations & check-in"
        ],
        "summary": "Check in by scanned ticket token",
        "description": "The event is derived from the token server-side and cross-checked against the URL: wrong event → `409` with the ticket's real event name; duplicate scan → `409` with the original check-in time. Other tenants' tokens are indistinguishable from invalid ones.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checked in."
          },
          "409": {
            "description": "Wrong event or duplicate scan."
          }
        }
      }
    },
    "/v1/registrations/{id}/checkin": {
      "post": {
        "tags": [
          "Registrations & check-in"
        ],
        "summary": "Check in by registration id (search-based flow)",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Checked in."
          }
        }
      }
    },
    "/v1/registrations/{id}/undo-checkin": {
      "post": {
        "tags": [
          "Registrations & check-in"
        ],
        "summary": "Undo a mistaken check-in",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Undone."
          }
        }
      }
    },
    "/v1/tickets/{token}": {
      "get": {
        "tags": [
          "Tickets"
        ],
        "summary": "Ticket details",
        "description": "Attendee name, status, `checkedInAt`, `locale`, `availableLocales`, and the event (title/times/location localized, `bannerUrl`, `organizer`). Build custom ticket pages from this plus the QR endpoint.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/lang"
          }
        ],
        "responses": {
          "200": {
            "description": "Ticket payload."
          },
          "404": {
            "description": "Unknown or erased token."
          }
        }
      }
    },
    "/v1/tickets/{token}/qr.svg": {
      "get": {
        "tags": [
          "Tickets"
        ],
        "summary": "Ticket QR image (SVG)",
        "description": "Encodes the bare token — scannable by the check-in endpoint.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SVG image."
          }
        }
      }
    },
    "/v1/categories": {
      "get": {
        "tags": [
          "Categories & tags"
        ],
        "summary": "List categories",
        "description": "Company categories plus the platform's general set. Management view adds full per-language label maps.",
        "security": [
          {
            "PublishableKey": []
          },
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/lang"
          }
        ],
        "responses": {
          "200": {
            "description": "Categories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "categories": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Category"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Categories & tags"
        ],
        "summary": "Create category",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "labels": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created; slug derives from the default-language label and never changes."
          }
        }
      }
    },
    "/v1/categories/{slug}": {
      "put": {
        "tags": [
          "Categories & tags"
        ],
        "summary": "Relabel/translate a category",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "labels": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated; slug stable."
          }
        }
      }
    },
    "/v1/tags": {
      "get": {
        "tags": [
          "Categories & tags"
        ],
        "summary": "List tags",
        "security": [
          {
            "PublishableKey": []
          },
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/lang"
          }
        ],
        "responses": {
          "200": {
            "description": "Tags (same model as categories, company-scoped only)."
          }
        }
      },
      "post": {
        "tags": [
          "Categories & tags"
        ],
        "summary": "Create tag",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created."
          }
        }
      }
    },
    "/v1/tags/{slug}": {
      "put": {
        "tags": [
          "Categories & tags"
        ],
        "summary": "Relabel/translate a tag",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated."
          }
        }
      }
    },
    "/v1/events/{id}/images/{kind}": {
      "put": {
        "tags": [
          "Images"
        ],
        "summary": "Upload banner or thumbnail",
        "description": "Raw image body (JPEG/PNG/WebP, up to 10 MB, magic-byte validated). Banner is 3:1 (1500×500 recommended), thumbnail square (600×600). Replacing reclaims the old file.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "banner",
                "thumbnail"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored; returns the event with the new URL."
          }
        }
      },
      "delete": {
        "tags": [
          "Images"
        ],
        "summary": "Remove banner or thumbnail",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "banner",
                "thumbnail"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed."
          }
        }
      }
    },
    "/v1/images/description": {
      "post": {
        "tags": [
          "Images"
        ],
        "summary": "Upload a content image",
        "description": "Raw image body → `{ \"url\": \"/uploads/…\" }` for use in description blocks, lineup photos, or per-event organizer logos. Uploads nothing ends up referencing are swept after ~24h.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "`{ url }`."
          }
        }
      }
    },
    "/v1/events/{id}/broadcast": {
      "post": {
        "tags": [
          "Broadcasts"
        ],
        "summary": "Message all confirmed attendees",
        "description": "Shortcodes render per recipient in the language each attendee registered in. `409 plan_limit` when the plan lacks the feature or the monthly recipient-message quota can't cover the send.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "subject",
                  "message"
                ],
                "properties": {
                  "subject": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Send accepted; history records per-recipient status."
          },
          "409": {
            "description": "plan_limit."
          }
        }
      }
    },
    "/v1/events/{id}/broadcast-test": {
      "post": {
        "tags": [
          "Broadcasts"
        ],
        "summary": "Test a broadcast (mails only you)",
        "description": "Renders with sample data — no quota use, no history entry.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sent to the caller."
          }
        }
      }
    },
    "/v1/broadcast-quota": {
      "get": {
        "tags": [
          "Broadcasts"
        ],
        "summary": "Monthly recipient-message quota",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "`{ limit, used, remaining }`."
          }
        }
      }
    },
    "/v1/events/{id}/broadcasts": {
      "get": {
        "tags": [
          "Broadcasts"
        ],
        "summary": "Broadcast history for an event",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Broadcasts with counts."
          }
        }
      }
    },
    "/v1/broadcasts/{id}/recipients": {
      "get": {
        "tags": [
          "Broadcasts"
        ],
        "summary": "Per-recipient results of a broadcast",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recipients with sent/failed status."
          }
        }
      }
    },
    "/v1/email-templates": {
      "get": {
        "tags": [
          "Email templates"
        ],
        "summary": "List effective templates",
        "description": "Optional `?locale=` for per-language templates; localized built-in defaults exist for en / zh-Hant / zh-Hans / ja.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "locale",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Templates."
          }
        }
      }
    },
    "/v1/email-templates/{type}": {
      "put": {
        "tags": [
          "Email templates"
        ],
        "summary": "Save a custom template",
        "description": "`type` is `confirmation` or `reminder`. Unknown shortcodes are rejected (`400 unknown_placeholders`).",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "confirmation",
                "reminder"
              ]
            }
          },
          {
            "name": "locale",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved."
          }
        }
      },
      "delete": {
        "tags": [
          "Email templates"
        ],
        "summary": "Revert to the built-in default",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "confirmation",
                "reminder"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reverted."
          }
        }
      }
    },
    "/v1/email-templates/{type}/test": {
      "post": {
        "tags": [
          "Email templates"
        ],
        "summary": "Mail yourself a rendered sample",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "confirmation",
                "reminder"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sent to the caller."
          }
        }
      }
    },
    "/v1/events/{id}/email-test": {
      "post": {
        "tags": [
          "Email templates"
        ],
        "summary": "Test an event's emails",
        "description": "Body: `{ type, message?, locale? }` — renders the event's confirmation/reminder with sample attendee data and mails only the caller.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sent to the caller."
          }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List webhook endpoints",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Endpoints (plan-limited: free 1 / pro 5)."
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Create a webhook endpoint",
        "description": "http(s) URLs only; hostnames resolving to private ranges are rejected (SSRF guard). The `whsec_…` signing secret is returned once.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url",
                  "events"
                ],
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhook": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Update endpoint (url / events / enabled)",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated."
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Delete endpoint",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted."
          }
        }
      }
    },
    "/v1/webhooks/{id}/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Synchronous test ping",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delivery attempt result."
          }
        }
      }
    },
    "/v1/webhooks/{id}/push-all": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Queue a full snapshot (sync.push)",
        "description": "Initial sync / recovery: queues the complete current state to the endpoint.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Queued."
          }
        }
      }
    },
    "/v1/webhooks/{id}/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Delivery log",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent deliveries with status/attempts."
          }
        }
      }
    },
    "/v1/webhooks/deliveries/{id}/redeliver": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Redeliver one delivery",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Requeued."
          }
        }
      }
    },
    "/v1/reports/overview": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "Registrations & views overview",
        "description": "Per-day registrations/views series (timezone-correct local buckets) and per-event confirmed/checked-in/attendance/fill/view counts.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                14,
                30,
                90
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Report payload."
          }
        }
      }
    },
    "/v1/gdpr/erase-attendee": {
      "post": {
        "tags": [
          "GDPR"
        ],
        "summary": "Erase an attendee (right to erasure)",
        "description": "Anonymizes every registration and broadcast-recipient record for the email across your account: identity, answers, and ticket QR are gone; counts and statistics stay truthful; the email may register again. Irreversible.",
        "security": [
          {
            "SecretKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "`{ erased: { registrations, broadcastRecipients } }`."
          },
          "404": {
            "description": "No records for that email."
          }
        }
      }
    }
  }
}
