Aisle Wedding API

openapi: 3.2.0
info:
  title: Aisle Wedding 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: Wedding
  description: Wedding identity and dates.
paths:
  /wedding:
    get:
      operationId: getWedding
      tags:
      - Wedding
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success.
          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:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: '#/components/schemas/Wedding'
                required:
                - data
              example:
                data:
                  id: wed_01J8WEDDING
                  slug: maya-and-theo
                  partner_1_name: Maya
                  partner_2_name: Theo
                  couple_display_name: Maya & Theo
                  wedding_date: '2027-06-13'
                  wedding_end_date: '2027-06-15'
                  timezone: Europe/Rome
                  currency: EUR
                  location: Ravello, Italy
                  venue:
                    name: Villa Cimbrone
                    place_id: null
                    latitude: '40.6499'
                    longitude: '14.6117'
                    city: Ravello
                    country: Italy
                  room_selection_mode: guest_choice
                  guest_pays_platform_fee: false
                  room_payment_on_rsvp: false
                  public_registry_enabled: true
                  published: true
                  created_at: '2026-08-31T12:00:00.000Z'
                  updated_at: '2026-08-31T12:00:00.000Z'
        '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'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      summary: Get wedding
      x-summary-source: derived
    patch:
      operationId: updateWedding
      tags:
      - Wedding
      security:
      - bearerAuth: []
      description: Retrying with the same values is safe and converges on the same stored state.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                slug:
                  type: string
                partner_1_name:
                  type: string
                partner_2_name:
                  type: string
                couple_display_name:
                  type:
                  - string
                  - 'null'
                wedding_date:
                  type:
                  - string
                  - 'null'
                  format: date
                  description: A calendar day the couple owns in the venue's zone, with no instant behind it. It is the same day for every reader.
                wedding_end_date:
                  type:
                  - string
                  - 'null'
                  format: date
                  description: A calendar day the couple owns in the venue's zone, with no instant behind it. It is the same day for every reader.
                location:
                  type:
                  - string
                  - 'null'
                venue_name:
                  type:
                  - string
                  - 'null'
                place_id:
                  type:
                  - string
                  - 'null'
                latitude:
                  description: A decimal from -90 through 90.
                  oneOf:
                  - type: number
                    minimum: -90
                    maximum: 90
                    multipleOf: 1.0e-07
                  - type: string
                    pattern: ^-?(?:[0-8]?\d(?:\.\d{1,7})?|90(?:\.0{1,7})?)$
                  - type: 'null'
                longitude:
                  description: A decimal from -180 through 180.
                  oneOf:
                  - type: number
                    minimum: -180
                    maximum: 180
                    multipleOf: 1.0e-07
                  - type: string
                    pattern: ^-?(?:(?:[0-9]?\d|1[0-7]\d)(?:\.\d{1,7})?|180(?:\.0{1,7})?)$
                  - type: 'null'
                city:
                  type:
                  - string
                  - 'null'
                country:
                  type:
                  - string
                  - 'null'
                timezone:
                  type:
                  - string
                  - 'null'
                  description: The IANA zone of the venue, such as `Europe/Rome`. Every instant this API returns is meant to be read in this zone. Null on a wedding with no venue yet, in which case instants were written against UTC.
                room_selection_mode:
                  description: 'Legacy bulk setter: updates the wedding fallback and clears every property override, including when the value is unchanged. Prefer property room_selection_mode for individual Hosted places.'
                  type: string
                  enum:
                  - couple_assigned
                  - guest_choice
                public_registry_enabled:
                  type: boolean
            example:
              wedding_date: '2027-06-13'
              venue_name: Villa Cimbrone
      responses:
        '200':
          description: Success.
          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:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: '#/components/schemas/Wedding'
                required:
                - data
              example:
                data:
                  id: wed_01J8WEDDING
                  slug: maya-and-theo
                  partner_1_name: Maya
                  partner_2_name: Theo
                  couple_display_name: Maya & Theo
                  wedding_date: '2027-06-13'
                  wedding_end_date: '2027-06-15'
                  timezone: Europe/Rome
                  currency: EUR
                  location: Ravello, Italy
                  venue:
                    name: Villa Cimbrone
                    place_id: null
                    latitude: '40.6499'
                    longitude: '14.6117'
                    city: Ravello
                    country: Italy
                  room_selection_mode: guest_choice
                  guest_pays_platform_fee: false
                  room_payment_on_rsvp: false
                  public_registry_enabled: true
                  published: true
                  created_at: '2026-08-31T12:00:00.000Z'
                  updated_at: '2026-08-31T12:00:00.000Z'
        '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'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      summary: Update wedding
      x-summary-source: derived
components:
  schemas:
    ErrorDetail:
      type: object
      required:
      - field
      - issue
      additionalProperties: false
      properties:
        field:
          type: string
          description: Dotted path to the offending field.
        issue:
          type: string
    Wedding:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          pattern: ^wed_.+$
        slug:
          type: string
        partner_1_name:
          type: string
        partner_2_name:
          type: string
        couple_display_name:
          type:
          - string
          - 'null'
        wedding_date:
          type:
          - string
          - 'null'
          format: date
          description: A calendar day the couple owns in the venue's zone, with no instant behind it. It is the same day for every reader.
        wedding_end_date:
          type:
          - string
          - 'null'
          format: date
          description: A calendar day the couple owns in the venue's zone, with no instant behind it. It is the same day for every reader.
        timezone:
          type:
          - string
          - 'null'
          description: The IANA zone of the venue, such as `Europe/Rome`. Every instant this API returns is meant to be read in this zone. Null on a wedding with no venue yet, in which case instants were written against UTC.
        currency:
          type: string
        location:
          type:
          - string
          - 'null'
        venue:
          type: object
          additionalProperties: false
          properties:
            name:
              type:
              - string
              - 'null'
            place_id:
              type:
              - string
              - 'null'
            latitude:
              type:
              - string
              - 'null'
            longitude:
              type:
              - string
              - 'null'
            city:
              type:
              - string
              - 'null'
            country:
              type:
              - string
              - 'null'
        room_selection_mode:
          type: string
        guest_pays_platform_fee:
          type: boolean
        room_payment_on_rsvp:
          type: boolean
          description: When true, a guest's yes on the couple's Aisle site waits for the first payment on their room. `PUT /v1/guests/{guest_id}/rsvp` does not apply this rule.
        public_registry_enabled:
          type: boolean
        published:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - slug
      - partner_1_name
      - partner_2_name
      - couple_display_name
      - wedding_date
      - wedding_end_date
      - timezone
      - currency
      - location
      - venue
      - room_selection_mode
      - guest_pays_platform_fee
      - room_payment_on_rsvp
      - public_registry_enabled
      - published
      - created_at
      - updated_at
    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
  responses:
    Conflict:
      description: The request collided with the current state of the resource.
      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'
    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
  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