# Connect V4 Documentation

> Documentation for Connect V4

Append .md to any documentation page URL to get its markdown version.

## API Reference
- [Obtain JWT token](https://docs-connect-api-v4.eventtia.com/reference/authenticateuser.md): Exchanges email/password credentials for a JWT token.  On success returns a `token` that must be included on every subsequent request as an HTTP header:  ``` Authorization: Bearer <token> ```  **Runtime override (MCP / FastMCP integration):** Clients built on top of this spec (e.g. an MCP server generated with FastMCP via `FastMCP.from_openapi`) can override the `Authorization` header per-request at runtime to rotate tokens or impersonate users without restarting the MCP server.  **Rate limit:** 100 requests/minute per IP. Auth failures do not leak which of (email, password) was wrong.
- [List events](https://docs-connect-api-v4.eventtia.com/reference/listevents.md): Returns a paginated list of events belonging to the authenticated user's account.  Events are filtered by the user's security access level and account scope. Archived events are excluded automatically.  **Sorting:** Use the `order` parameter to sort results. Format: `column_name direction` (e.g., `start_date desc`, `name asc`). Supports up to two sort fields separated by comma.  **Pagination:** Default page size is 24 (max 24). Use `page[number]` and `page[size]` to control pagination.  **Caching:** Responses are cached for 1 minute.  **Rate limit:** 100 requests/minute per IP (600 for whitelisted IPs).
- [Create event](https://docs-connect-api-v4.eventtia.com/reference/createevent.md): Creates a new event in the authenticated user's account.  **Attendance mode rules:** - `offline`: Requires `city_id`. Timezone derived from the city. - `online`: Requires `virtual_timezone`. No `city_id` needed. - `mixed`: Requires both `city_id` and `virtual_timezone`.  Dates must be sent as `dd/mm/yyyy - HH:MM`.
- [Get event](https://docs-connect-api-v4.eventtia.com/reference/getevent.md): Returns the details of a single event by its UUID.  Authentication is optional. When unauthenticated, only non-archived public events are returned.
- [Update event](https://docs-connect-api-v4.eventtia.com/reference/updateevent.md): Updates an existing event. Only the provided fields are modified.
- [Get event modules](https://docs-connect-api-v4.eventtia.com/reference/geteventmodules.md): Returns boolean flags indicating which modules (activities, checkpoints) are enabled for the event.
- [Get event summary](https://docs-connect-api-v4.eventtia.com/reference/geteventsummary.md): Returns lightweight aggregated metrics for an event: attendee totals (active, confirmed, checked-in, drafts, rejected), date range with timezone, per-attendee-type seat usage, and top 5 workshops by check-in count.  All counts are computed with grouped SQL queries (no N+1) regardless of the number of attendee types or workshops.  **Caching:** Responses are cached for 1 minute.
- [List event custom fields](https://docs-connect-api-v4.eventtia.com/reference/listeventcustomfields.md): Returns the account-level custom field definitions applicable to every event in the authenticated user's account. This endpoint is **account-scoped**, not event-scoped: it takes no `uuid` path parameter. The `id` of each definition (cast to string) is the key expected inside `custom_fields_data` on `createEvent` / `updateEvent`.  Only active fields are returned (`archived: false`, `draft: false`), ordered by `order` ASC.  **Caching:** Responses are cached for 30 minutes.
- [List attendee types](https://docs-connect-api-v4.eventtia.com/reference/listattendeetypes.md): Returns a paginated list of attendee types for an event. Only non-archived, non-draft types are returned.
- [Create attendee type](https://docs-connect-api-v4.eventtia.com/reference/createattendeetype.md): Creates a new attendee type. Required fields: `name` and `limit`.
- [Get attendee type](https://docs-connect-api-v4.eventtia.com/reference/getattendeetype.md): Returns a single attendee type by ID.
- [Update attendee type](https://docs-connect-api-v4.eventtia.com/reference/updateattendeetype.md): Updates an existing attendee type. Only provided fields are modified.
- [List attendee type group limits](https://docs-connect-api-v4.eventtia.com/reference/listattendeetypegrouplimits.md): Returns per-group capacity limits for an attendee type.
- [Get admin form schema for an attendee type](https://docs-connect-api-v4.eventtia.com/reference/getattendeetypeformschema.md): Returns the ordered list of form fields the admin uses to create an Attendee of this AttendeeType. Includes default fields (first_name, email, etc.) and custom fields. Includes admin-only fields. Skips fields with display=false.
- [List attendees](https://docs-connect-api-v4.eventtia.com/reference/listattendees.md): Returns a paginated list of attendees for a given event.  By default only non-archived, non-draft, non-rejected attendees are returned. Use the filter query parameters to change this scope.
- [Get attendee](https://docs-connect-api-v4.eventtia.com/reference/getattendee.md): Returns a single attendee scoped to the event by its `attendee_uuid`. Cached for 5 minutes.
- [Update attendee](https://docs-connect-api-v4.eventtia.com/reference/updateattendee.md): Updates the profile of an existing attendee. Payload is wrapped under the `attendee` key. Only provided fields are modified.
- [Confirm attendee registration](https://docs-connect-api-v4.eventtia.com/reference/confirmattendee.md): Confirms a pending attendee registration. Sets `confirmed = true` and records the confirming user.
- [Reject attendee registration](https://docs-connect-api-v4.eventtia.com/reference/rejectattendee.md): Rejects an attendee registration. Archives the attendee if previously confirmed and unchecks-in if checked in.
- [Register attendee](https://docs-connect-api-v4.eventtia.com/reference/createattendee.md): Registers a new attendee for the event. The payload is wrapped under the `attendee` key.  **Required fields:** `first_name`, `last_name`, `email`, `attendee_type_id`. (`email` may be skipped only when the selected `attendee_type` has `email_required` disabled; default is required.)  If a draft attendee already exists for the same email + event it is promoted; otherwise a new attendee is created and registered.  An optional top-level `coupon_code` is applied after a successful registration.  **Precondition:** registration must be enabled for the event; otherwise the request fails with `422 "Registration for this event is not enabled"`.
- [List attendee payments](https://docs-connect-api-v4.eventtia.com/reference/listpayments.md): Returns the payments (deposits and charges) for a given attendee.
- [Register manual deposit](https://docs-connect-api-v4.eventtia.com/reference/createpayment.md): Creates a manual deposit payment for an attendee.  Internally calls `Payment.manual_payment(attendee, params, current_user)` with operation_type set to `deposit`.
- [Delete deposit payment](https://docs-connect-api-v4.eventtia.com/reference/deletepayment.md): Deletes a deposit payment. Only payments with `operation = deposit` are deletable.
- [Get attendee event check-in status](https://docs-connect-api-v4.eventtia.com/reference/getattendeeeventcheckin.md): Returns the event-level check-in status of an attendee. Indicates whether the attendee has checked in to the event and, if so, the check-in timestamp converted to the event's local timezone (format: YYYY-MM-DD HH:MM:SS).
- [List attendee checkpoint check-ins](https://docs-connect-api-v4.eventtia.com/reference/listattendeecheckpointcheckins.md): Returns a paginated list of checkpoint check-in logs for an attendee. Each log records an entry (and optional exit) at a named checkpoint. Includes the checkpoint name, entry timestamp, and checkout status. Logs are ordered by creation time descending (most recent first). The response includes `total_entries` for the unfiltered count.
- [List attendee workshop check-ins](https://docs-connect-api-v4.eventtia.com/reference/listattendeeworkshopcheckins.md): Returns a paginated list of workshop check-ins for an attendee. Only includes workshops where the attendee has an active registration AND has physically checked in (checked_in = true). Results are ordered by check-in date descending (most recent first). The response includes `total_entries` for the unfiltered count.
- [Resend welcome / confirmation email](https://docs-connect-api-v4.eventtia.com/reference/resendattendeeemail.md): Resends the welcome/confirmation email to a confirmed attendee. Returns 422 if the attendee is not eligible (draft, archived, unconfirmed, missing email, no attendee_type, or unpaid when payment is required).
- [List attendee type custom fields](https://docs-connect-api-v4.eventtia.com/reference/listattendeetypecustomfields.md): Returns the form fields configured for an attendee type. Default fields (`first_name`, `email`, etc.) and custom fields are both included.  **Filters:** by default returns only active fields (`archived: false`, `draft: false`). Override with `?archived=true|all` and `?draft=true|all`.
- [Create attendee type custom field](https://docs-connect-api-v4.eventtia.com/reference/createattendeetypecustomfield.md): Creates a new custom field on an attendee type. Required: `name`, `input_type`.  **Multiple-choice inputs** (`select`, `checkbox`, `radio`) require `values` as a JSON array. Each value must be a non-empty string without commas (the legacy storage uses comma-separated serialization).  **`terms_conditions`** input requires `terms_url`. File uploads are not supported via API — the server always forces `terms_mode=url`.  Default fields cannot be created via this endpoint (they are auto-created with the AttendeeType).
- [Update attendee type custom field](https://docs-connect-api-v4.eventtia.com/reference/updateattendeetypecustomfield.md): Updates an existing custom field. Default fields support a restricted set of mutations (only `required`, `display`, `allow_duplicate_values` for `email`, `min_age` for `birthdate`).
- [Search cities by name](https://docs-connect-api-v4.eventtia.com/reference/searchcities.md): Case-insensitive substring search over the global `cities` catalog. Useful to resolve a human-readable location into a numeric `city_id` before creating an offline or mixed event.  Each result is preloaded with its `region` and `country` to avoid N+1 queries on the caller side.  **Behavior:** - Matches `name LIKE "%q%"` (substring, case-insensitive in MySQL `utf8_general_ci`). - Wildcards `%` and `_` in `q` are escaped — no client-side wildcard matching. - Optional `country_iso_code` narrows results to a single country (case-insensitive). - Results are ordered by `name ASC`. - Capped at **20 results** (no pagination — refine the query instead). - Response is cacheable for 30 minutes (`Cache-Control: public, max-age=1800`).  **Rate limit:** 100 requests/minute per IP (600 for whitelisted IPs).
- [Create a checkpoint](https://docs-connect-api-v4.eventtia.com/reference/createcheckpointv4.md): Creates a new checkpoint for the given event. Requires `create_checkpoints` permission.  Fails with 422 if: - `name` or `checkpoint_type` are missing - The event has exceeded its checkpoint plan limit
- [Update a checkpoint](https://docs-connect-api-v4.eventtia.com/reference/updatecheckpointv4.md): Updates an existing checkpoint. Requires `edit_checkpoints` permission. Only fields included in the request body are updated.
- [Archive a checkpoint](https://docs-connect-api-v4.eventtia.com/reference/deletecheckpointv4.md): Soft-deletes a checkpoint by setting `archived: true`. Requires `delete_checkpoints` permission. The checkpoint is no longer returned in listings but is not removed from the database.   **⚠️ DESTRUCTIVE OPERATION**  LLM/MCP clients MUST obtain explicit end-user confirmation before invoking: present the target resource with user-recognizable identifiers and receive an affirmative response. Confirmation MUST NOT be inferred from dialogue or context.
- [List workshop sessions](https://docs-connect-api-v4.eventtia.com/reference/listsessions.md): Returns the sessions (concrete time-slots) registered under a WorkshopDefinition.
- [Create workshop session](https://docs-connect-api-v4.eventtia.com/reference/createsession.md): Creates a new session (Workshop slot) under a WorkshopDefinition. Required fields: `start_date` and `end_date`. The session inherits the WorkshopDefinition's name/description. Streaming, chat, Zoom and related integrations are not configurable via this API.  **Precondition:** the event must have multiple sessions enabled; otherwise the request fails with `422 "You cannot create a workshop session because multiple sessions are disabled for this event."`. A workshop's first session is created through `createWorkshop` (via `workshops_attributes`).
- [Get workshop session](https://docs-connect-api-v4.eventtia.com/reference/getsession.md): Returns a single workshop session by GUID.
- [Update workshop session](https://docs-connect-api-v4.eventtia.com/reference/updatesession.md): Updates an existing workshop session. Only the provided fields are modified. Streaming, chat, Zoom and related integrations are not configurable via this API.
- [List workshop definitions](https://docs-connect-api-v4.eventtia.com/reference/listworkshops.md): Returns a paginated list of workshop definitions for an event. Excludes archived, sponsor-owned and empty (no active sessions) definitions by default.
- [Create workshop definition](https://docs-connect-api-v4.eventtia.com/reference/createworkshop.md): Creates a new workshop definition together with at least one session (`workshops_attributes`). Required fields: `name` (multilingual hash) and `workshops_attributes` (non-empty). Image fields (`banner_image`, `background_image`) are not supported via this API.
- [Get workshop definition](https://docs-connect-api-v4.eventtia.com/reference/getworkshop.md): Returns a single workshop definition by GUID.
- [Update workshop definition](https://docs-connect-api-v4.eventtia.com/reference/updateworkshop.md): Updates a workshop definition. Only `name` and `description` (multilingual) are accepted; nested `workshops_attributes` is ignored on update.
- [Get workshop session stats](https://docs-connect-api-v4.eventtia.com/reference/getworkshopstats.md): Returns used seats and check-in counts for a single workshop session. `guid` is the workshop session GUID (the same GUID used by `getWorkshop`), not the workshop definition GUID.
- [Archive workshop session](https://docs-connect-api-v4.eventtia.com/reference/destroysession.md): Performs a destructive mutation to transition a workshop session state to 'archived'.   - **Cascade Behavior:** Atomically tearing down all related active enrollment fixtures. - **Idempotency:** Non-idempotent lookup; subsequent DELETE operations on the same GUID scope will resolve to a 404 response.   **⚠️ DESTRUCTIVE OPERATION**  LLM/MCP clients MUST obtain explicit end-user confirmation before invoking: present the target resource with user-recognizable identifiers and receive an affirmative response. Confirmation MUST NOT be inferred from dialogue or context.
- [Enroll an attendee in a session](https://docs-connect-api-v4.eventtia.com/reference/enrollattendeeinsession.md): Enrolls an attendee in a specific workshop session. This endpoint safely handles concurrent requests to prevent overbooking and automatically recomputes related attendee charges.  ### Validation Rules * **Availability:** Checks seat capacity and enforces per-attendee-type limits. * **Scheduling:** Prevents double-enrollment and time overlaps with other registered sessions. * **Timeline:** Ensures the booking deadline has not passed.
- [Unenroll an attendee from a session](https://docs-connect-api-v4.eventtia.com/reference/unenrollattendeefromsession.md): Removes an attendee's enrollment from a specific workshop session.  ### Key Effects * **Participation:** Cancels the attendee's registration for this session. * **Charges:** Triggers an automatic recomputation of the associated attendee charges.   **⚠️ DESTRUCTIVE OPERATION**  LLM/MCP clients MUST obtain explicit end-user confirmation before invoking: present the target resource with user-recognizable identifiers and receive an affirmative response. Confirmation MUST NOT be inferred from dialogue or context.
- [List speakers](https://docs-connect-api-v4.eventtia.com/reference/listspeakers.md): Returns a paginated list of speakers for an event. By default only non-archived, non-draft speakers are returned. Use `?archived=true` to list only archived speakers, or `?archived=all` to include both.
- [Create speaker](https://docs-connect-api-v4.eventtia.com/reference/createspeaker.md): Creates a new speaker. Required field: `name`. Image fields (`picture`, `banner`) are not supported via this API. The `attendee` association is not exposed in this version.
- [Get speaker](https://docs-connect-api-v4.eventtia.com/reference/getspeaker.md): Returns a single speaker by ID, scoped to the event.
- [Update speaker](https://docs-connect-api-v4.eventtia.com/reference/updatespeaker.md): Updates an existing speaker. Only provided fields are modified. Image fields (`picture`, `banner`) are not supported via this API. The `attendee` association is not exposed in this version.