Aisle RSVP API

openapi: 3.2.0
info:
  title: Aisle RSVP API
  version: v1
  summary: Run a wedding on Aisle behind your own frontend.
  description: 'Aisle''s public backend API. Use it to run a wedding on Aisle while building

    and hosting your own frontend. ## Authentication


    Every request carries a wedding-scoped API key as a bearer token:


    Authorization: Bearer


    A key is scoped to exactly one wedding, and every read and write it makes

    stays inside that wedding. **Keys are server-side credentials.** Call this

    API from your own backend and never ship a key in browser JavaScript, where

    anyone loading your site can read it and act as the couple. ## Requests and responses


    Bodies are JSON. A request that sends a body must send

    `Content-Type: application/json`. Object ids are opaque strings with a type prefix, such as `gst_1042`. Treat

    them as strings: their shape may change and only the prefix is contractual. ## Dates and times


    Two kinds of value, and mixing them up is the most expensive mistake an

    integration can make here, because the result is a plausible number rather

    than an error. **Scheduled wedding times** are instants: RFC 3339 in UTC, for example

    `2026-06-13T14:00:00.000Z`. Event `starts_at` and `ends_at`,

    meal-selection deadlines and transport-leg times are all instants. **Format them in the wedding''s `timezone` from `GET /wedding`, never in

    the reader''s zone.** That ceremony is 16:00 at a wedding in `Europe/Rome`,

    and a guest browsing from California must still be told 16:00. Rendered in

    the reader''s own zone it reads 07:00, and a brunch the morning after moves to

    the previous evening. Nothing in the response marks that as wrong, so it is

    worth getting right once in a shared formatter. **Record timestamps** are instants too, and the same RFC 3339 UTC shape:

    `created_at`, `updated_at` and `rsvp_responded_at` say when something

    happened. Which zone you show those in is your choice, because they are not

    part of the wedding''s schedule. **Wall-clock values** are a day or a time the couple owns at the venue, with

    no instant behind them, so they are carried as separate date and time fields:

    `wedding_date` and `wedding_end_date`, and stay `check_in_date` with

    `check_in_time`. These are the same for every reader and need no zone. `timezone` is null on a wedding with no venue yet. Instants written before

    a venue was chosen were anchored to UTC. ## Pagination


    Collections are cursor-paged. Pass `limit` (1 to 100, default

    25) and `cursor`. Each response carries `has_more` and

    `next_cursor`; keep passing `next_cursor` back until `has_more` is false. An out-of-range `limit` is rejected rather than clamped, so a page you asked

    for is either the page you get or an error. ## Filtering


    Filters are query parameters named for the field they filter. Repeat a

    parameter, or comma-separate it, to mean "any of these":

    `?status=confirmed&status=pending`. Two different filters narrow each other. Each collection declares the filters it accepts; a parameter an endpoint does

    not declare is rejected rather than ignored, so a misspelled filter is an

    error and never a full page that looks filtered. A filter''s `next_cursor` is

    bound to that filter, so keep passing the same query string while you page. ## Errors


    Failures carry a JSON body with a stable `error.code`, a human-readable

    `error.message`, and a `request_id`. Branch on the code, log the message,

    and quote the request id when asking us about a specific call. Field-level

    problems appear in `error.details`. A field we refuse is always a `422 validation_failed`, whether it arrived in

    the query string or in the request body, and every field at fault is listed in

    `error.details` rather than only the first. Each entry names the field in the

    spelling you sent, dotted through objects and indexed through lists, such as

    `options.1.id`. `error.message` is one sentence for the whole request and

    carries nothing you need to parse. A `400 invalid_request` means the request

    itself could not be read, such as a body that is not a JSON object. ## Rate limits


    Responses carry `X-RateLimit-Limit`,

    `X-RateLimit-Remaining` and `X-RateLimit-Reset`.'
  contact:
    name: Aisle
    url: https://aisle.wedding
servers:
- url: https://api.aisle.wedding/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: RSVP
  description: Read and record guest replies and event invitations.
paths:
  /guests/{guest_id}/rsvp:
    parameters:
    - name: guest_id
      in: path
      required: true
      schema:
        type: string
        pattern: ^gst_.+$
    get:
      tags:
      - RSVP
      operationId: getGuestRsvp
      security:
      - bearerAuth: []
      summary: Get a guest reply
      responses:
        '200':
          description: The headline reply, answers, and event responses.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/GuestRsvp'
              example:
                data:
                  guest_id: gst_01J8GUEST
                  status: attending
                  stage: full
                  responded_at: '2026-08-31T12:00:00.000Z'
                  option_id: null
                  option_label: null
                  answers: {}
                  event_responses: []
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/MembershipRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      tags:
      - RSVP
      operationId: putGuestRsvp
      security:
      - bearerAuth: []
      summary: Record a guest reply
      description: The headline reply fans out through Aisle attendance rules and commits with event answers in one transaction. A ticketed event still requires a completed ticket payment, unless the couple has let that ticket be paid later (`Event.ticket.pay_later`). Retrying the same body converges on the same RSVP state; v1 does not persist a general idempotency key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuestRsvpInput'
            example:
              status: attending
              event_responses: []
      responses:
        '200':
          description: The stored reply.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/GuestRsvp'
              example:
                data:
                  guest_id: gst_01J8GUEST
                  status: attending
                  stage: full
                  responded_at: '2026-08-31T12:00:00.000Z'
                  option_id: null
                  option_label: null
                  answers: {}
                  event_responses: []
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/MembershipRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /guests/{guest_id}/event-invitations:
    parameters:
    - name: guest_id
      in: path
      required: true
      schema:
        type: string
        pattern: ^gst_.+$
    get:
      tags:
      - RSVP
      operationId: listGuestEventInvitations
      security:
      - bearerAuth: []
      summary: List explicit event invitations for a guest
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: The guest invitation rows.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - data
                - has_more
                - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GuestInvitation'
                  has_more:
                    type: boolean
                  next_cursor:
                    type:
                    - string
                    - 'null'
              example:
                data: []
                has_more: false
                next_cursor: example
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/MembershipRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /guests/{guest_id}/event-invitations/{event_id}:
    parameters:
    - name: guest_id
      in: path
      required: true
      schema:
        type: string
        pattern: ^gst_.+$
    - name: event_id
      in: path
      required: true
      schema:
        type: string
        pattern: ^evt_.+$
    put:
      tags:
      - RSVP
      operationId: putGuestEventInvitation
      security:
      - bearerAuth: []
      summary: Set one explicit event invitation
      description: Sets the invitation membership and preserves RSVP fan-out. Retry with the same invited value converges on the same invitation state.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - invited
              properties:
                invited:
                  type: boolean
            example:
              invited: false
      responses:
        '200':
          description: The invitation state.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/GuestInvitation'
              example:
                data:
                  event_id: evt_01J8EVENT
                  invited: true
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/MembershipRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ErrorDetail:
      type: object
      required:
      - field
      - issue
      additionalProperties: false
      properties:
        field:
          type: string
          description: Dotted path to the offending field.
        issue:
          type: string
    GuestInvitation:
      type: object
      additionalProperties: false
      required:
      - event_id
      - invited
      properties:
        event_id:
          $ref: '#/components/schemas/EventId'
        invited:
          type: boolean
    Error:
      type: object
      required:
      - error
      - request_id
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - code
          - message
          - details
          additionalProperties: false
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - unauthorized
              - membership_required
              - forbidden
              - not_found
              - method_not_allowed
              - conflict
              - unsupported_media_type
              - validation_failed
              - rate_limited
              - internal_error
              description: Stable machine-readable failure code.
            message:
              type: string
              description: Human-readable explanation. Wording may change; do not match on it.
            details:
              type: array
              description: Field-level problems, one entry per field at fault. Populated for validation_failed and empty for every other code.
              items:
                $ref: '#/components/schemas/ErrorDetail'
        request_id:
          type: string
    GuestEventResponse:
      type: object
      additionalProperties: false
      required:
      - event_id
      - attending
      - option_id
      - option_label
      - meal_choice_id
      - meal_notes
      - updated_at
      properties:
        event_id:
          $ref: '#/components/schemas/EventId'
        attending:
          type:
          - boolean
          - 'null'
        option_id:
          type:
          - string
          - 'null'
        option_label:
          type:
          - string
          - 'null'
        meal_choice_id:
          type:
          - string
          - 'null'
        meal_notes:
          type:
          - string
          - 'null'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    GuestId:
      type: string
      pattern: ^gst_.+$
    GuestRsvp:
      type: object
      additionalProperties: false
      required:
      - guest_id
      - status
      - stage
      - responded_at
      - option_id
      - option_label
      - answers
      - event_responses
      properties:
        guest_id:
          $ref: '#/components/schemas/GuestId'
        status:
          type: string
          enum:
          - pending
          - attending
          - declined
          - maybe
          description: On update, explicitly setting this status clears the previous RSVP option ID and label. Omit it to preserve the guest's selected answer.
        stage:
          type:
          - string
          - 'null'
        responded_at:
          oneOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        option_id:
          type:
          - string
          - 'null'
        option_label:
          type:
          - string
          - 'null'
        answers:
          type: object
          additionalProperties: true
        event_responses:
          type: array
          items:
            $ref: '#/components/schemas/GuestEventResponse'
    EventId:
      type: string
      pattern: ^evt_.+$
    Timestamp:
      type: string
      format: date-time
      description: An RFC 3339 UTC timestamp with milliseconds.
      examples:
      - '2026-08-31T01:58:35.000Z'
    GuestRsvpInput:
      type: object
      additionalProperties: false
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - attending
          - maybe
          - declined
        answers:
          type: object
          additionalProperties: true
        dietary_restrictions:
          type:
          - string
          - 'null'
        dietary_notes:
          type:
          - string
          - 'null'
        event_responses:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - event_id
            properties:
              event_id:
                $ref: '#/components/schemas/EventId'
              attending:
                type:
                - boolean
                - 'null'
              option_id:
                type:
                - string
                - 'null'
              meal_choice_id:
                type:
                - string
                - 'null'
              meal_notes:
                type:
                - string
                - 'null'
  responses:
    Forbidden:
      description: The key is valid but not permitted to do this.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Aisle-Api-Version:
          $ref: '#/components/headers/X-Aisle-Api-Version'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidRequest:
      description: The request itself could not be read, such as a body that is not a JSON object. A field we refuse is validation_failed instead.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Aisle-Api-Version:
          $ref: '#/components/headers/X-Aisle-Api-Version'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests. Retry after the time given in Retry-After.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Aisle-Api-Version:
          $ref: '#/components/headers/X-Aisle-Api-Version'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such resource inside the key's wedding.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Aisle-Api-Version:
          $ref: '#/components/headers/X-Aisle-Api-Version'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationFailed:
      description: The request was well-formed but a field was not acceptable. Every field at fault is named in error.details.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Aisle-Api-Version:
          $ref: '#/components/headers/X-Aisle-Api-Version'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Something went wrong on our side.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Aisle-Api-Version:
          $ref: '#/components/headers/X-Aisle-Api-Version'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: A request body must be sent as application/json.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Aisle-Api-Version:
          $ref: '#/components/headers/X-Aisle-Api-Version'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MembershipRequired:
      description: The operation requires an active Aisle membership for this wedding.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Aisle-Api-Version:
          $ref: '#/components/headers/X-Aisle-Api-Version'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The API key is missing, malformed, or no longer valid.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-Aisle-Api-Version:
          $ref: '#/components/headers/X-Aisle-Api-Version'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    Retry-After:
      description: Seconds to wait before retrying a rate-limited call.
      schema:
        type: integer
        minimum: 1
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix seconds at which the current window resets.
      schema:
        type: integer
    X-RateLimit-Limit:
      description: Requests permitted in the current window.
      schema:
        type: integer
    X-Aisle-Api-Version:
      description: The API version that served this request.
      schema:
        type: string
    X-Request-Id:
      description: Correlation id for this request. Quote it when reporting a problem.
      schema:
        type: string
  parameters:
    cursor:
      name: cursor
      in: query
      required: false
      description: The `next_cursor` from the previous page. Omit for the first page.
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: How many records to return, 1 to 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A wedding-scoped API key. Send it from your own server; never from a browser.
externalDocs:
  url: https://api.aisle.wedding/docs
  description: API reference