> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fesutibaru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List events

> The edition's events: drafts as well as confirmed, public or not.



## OpenAPI

````yaml https://api-test.fesutibaru.com/api/v1/openapi.json get /events
openapi: 3.1.0
info:
  title: Fesutibaru Planner API
  version: 0.17.0
  description: >-
    The festival's working data, read as a signed-in person: what they can see
    in Planner, they can read here, and nothing else.


    Each festival has its own address: https://<festival>.fesutibaru.com/api/v1.


    Field names are the database's own, so a field you read is the field you
    change in a proposal. Times are instants (ISO 8601 with offset); the
    festival's own wall-clock time is alongside as <field>_local.


    Editions: event, travel, stay, pick-up, document and media records belong to
    one edition. Reads default to the current edition; ?edition=2027 reads
    another.


    Custom fields appear on records as cf_<field_key> (see /custom-fields).


    Changes are proposed, never made directly: POST /proposals, and the person
    accepts or rejects them in their Planner inbox.


    Public listings for websites, with an API key, are under /api/v1/public.
servers:
  - url: https://{festival}.fesutibaru.com/api/v1
    variables:
      festival:
        default: demo
        description: The festival's subdomain.
security:
  - agent:
      - planner:read
paths:
  /events:
    get:
      tags:
        - Events
      summary: List events
      description: 'The edition''s events: drafts as well as confirmed, public or not.'
      operationId: list_events
      parameters:
        - name: edition
          in: query
          description: >-
            Read another edition by its year, e.g. 2027. Default: the current
            edition.
          schema:
            type: integer
        - name: edition_id
          in: query
          description: Read another edition by its id.
          schema:
            type: string
            format: uuid
        - name: include
          in: query
          description: >-
            Add related records, comma-separated: venue (The venue); authors
            (Authors and speakers); chairs (Chairs); interviewers
            (Interviewers); intro_wrap (Intro / wrap); staff (Staff (front of
            house, security, technicians)); books (Books at the event).
          schema:
            type: string
          examples:
            all:
              value: venue,authors,chairs,interviewers,intro_wrap,staff,books
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: q
          in: query
          description: Search title, description (part of the value, any case).
          schema:
            type: string
        - name: updated_since
          in: query
          description: >-
            Only records changed at or after this time: for keeping a copy in
            sync.
          schema:
            type: string
            format: date-time
        - name: status
          in: query
          description: draft, confirmed, cancelled…
          schema:
            type: string
        - name: venue_id
          in: query
          description: Events at this venue.
          schema:
            type: string
            format: uuid
        - name: event_type
          in: query
          description: Events of this type.
          schema:
            type: string
        - name: is_public
          in: query
          description: true for events on the public listing.
          schema:
            type: boolean
        - name: starts_after
          in: query
          description: Starting at or after this time (ISO 8601).
          schema:
            type: string
            format: date-time
        - name: starts_before
          in: query
          description: Starting at or before this time (ISO 8601).
          schema:
            type: string
            format: date-time
        - name: tag
          in: query
          description: Events carrying this schedule tag.
          schema:
            type: string
      responses:
        '200':
          description: A page of events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Events'
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      edition:
                        $ref: '#/components/schemas/Edition'
        '400':
          description: 'Something in the request is wrong: detail says what.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Not signed in.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Not allowed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: No such record, edition or resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: 'Too many requests: wait for Retry-After seconds.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Events:
      type: object
      description: >-
        The edition's events: drafts as well as confirmed, public or not. Fields
        you may not see are left out. Custom fields appear as cf_<field_key>.
      properties:
        id:
          type: string
          format: uuid
        festival_id:
          type: string
          format: uuid
        title:
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
        event_type:
          anyOf:
            - type: string
            - type: 'null'
        venue_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
        start_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          description: >-
            When it starts, as an instant (ISO 8601 with offset).
            start_time_local is the same in the festival’s own time.
        start_time_local:
          anyOf:
            - type: string
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$
            - type: 'null'
          description: start_time in the festival’s own time zone, as wall-clock time.
        end_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          description: When it ends. end_time_local is the festival’s own time.
        end_time_local:
          anyOf:
            - type: string
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$
            - type: 'null'
          description: end_time in the festival’s own time zone, as wall-clock time.
        capacity:
          anyOf:
            - type: integer
            - type: 'null'
        status:
          anyOf:
            - type: string
            - type: 'null'
          description: draft, confirmed, cancelled…
        is_public:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Shown on the public listing.
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        duration:
          anyOf:
            - type: string
            - type: 'null'
        signing:
          anyOf:
            - type: boolean
            - type: 'null'
        signing_location:
          anyOf:
            - type: string
            - type: 'null'
        speaker_notes:
          anyOf:
            - type: string
            - type: 'null'
        age_category:
          anyOf:
            - type: string
            - type: 'null'
        ticket_price_full:
          anyOf:
            - type: number
            - type: 'null'
        ticket_price_conc:
          anyOf:
            - type: number
            - type: 'null'
        ticket_price_kids:
          anyOf:
            - type: number
            - type: 'null'
        event_copy:
          anyOf:
            - type: string
            - type: 'null'
          description: The full programme copy.
        event_copy_summary:
          anyOf:
            - type: string
            - type: 'null'
          description: A short version of the copy.
        stage_requirements:
          anyOf:
            - type: string
            - type: 'null'
        reserved_seating:
          anyOf:
            - type: string
            - type: 'null'
        accessibility_seating:
          anyOf:
            - type: string
            - type: 'null'
        equipment_notes:
          anyOf:
            - type: string
            - type: 'null'
        technical_notes:
          anyOf:
            - type: string
            - type: 'null'
        box_office_link:
          anyOf:
            - type: string
            - type: 'null'
        event_notes:
          anyOf:
            - type: string
            - type: 'null'
        foh_notes:
          anyOf:
            - type: string
            - type: 'null'
        edition_id:
          type: string
          format: uuid
        schedule_tags:
          type: array
          items:
            type: string
          description: Tags used on the schedule (mass, reception, hide…).
        repeat_group_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: Events repeated from one another share this.
        bsl_interpreted:
          anyOf:
            - type: boolean
            - type: 'null'
        captioned:
          anyOf:
            - type: boolean
            - type: 'null'
        audio_described:
          anyOf:
            - type: boolean
            - type: 'null'
        relaxed_performance:
          anyOf:
            - type: boolean
            - type: 'null'
        live_stream:
          anyOf:
            - type: string
            - type: 'null'
          description: The live stream link, if any.
        event_assets_url:
          anyOf:
            - type: string
            - type: 'null'
        subtitled:
          anyOf:
            - type: boolean
            - type: 'null'
        venue:
          anyOf:
            - $ref: '#/components/schemas/Venues'
            - type: 'null'
          description: The venue. Only with ?include=venue.
        authors:
          type: array
          items:
            $ref: '#/components/schemas/People'
          description: Authors and speakers. Only with ?include=authors.
        chairs:
          type: array
          items:
            $ref: '#/components/schemas/People'
          description: Chairs. Only with ?include=chairs.
        interviewers:
          type: array
          items:
            $ref: '#/components/schemas/People'
          description: Interviewers. Only with ?include=interviewers.
        intro_wrap:
          type: array
          items:
            $ref: '#/components/schemas/People'
          description: Intro / wrap. Only with ?include=intro_wrap.
        staff:
          type: array
          items:
            $ref: '#/components/schemas/People'
          description: >-
            Staff (front of house, security, technicians). Only with
            ?include=staff.
        books:
          type: array
          items:
            $ref: '#/components/schemas/Books'
          description: Books at the event. Only with ?include=books.
      additionalProperties: true
    Edition:
      type: object
      properties:
        id:
          type: string
          format: uuid
        year:
          type: integer
        name:
          type: string
        is_current:
          type: boolean
    Problem:
      type: object
      description: 'An error (RFC 9457): detail says what went wrong and what to do.'
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
      required:
        - title
        - status
        - detail
    Venues:
      type: object
      description: >-
        The festival's venues. Fields you may not see are left out. Custom
        fields appear as cf_<field_key>.
      properties:
        id:
          type: string
          format: uuid
        festival_id:
          type: string
          format: uuid
        name:
          type: string
        address:
          anyOf:
            - type: string
            - type: 'null'
        capacity:
          anyOf:
            - type: integer
            - type: 'null'
        venue_type:
          anyOf:
            - type: string
            - type: 'null'
        accessibility_info:
          anyOf:
            - type: string
            - type: 'null'
        technical_specs:
          anyOf:
            - type: object
            - type: 'null'
        contact_info:
          anyOf:
            - type: object
            - type: 'null'
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        venue_image_url:
          anyOf:
            - type: string
            - type: 'null'
        ticket_holds:
          anyOf:
            - type: integer
            - type: 'null'
          description: Seats held back from sale.
        website:
          anyOf:
            - type: string
            - type: 'null'
        notes:
          anyOf:
            - type: string
            - type: 'null'
        default_ticket_price_full:
          anyOf:
            - type: number
            - type: 'null'
        default_ticket_price_conc:
          anyOf:
            - type: number
            - type: 'null'
        default_ticket_price_kids:
          anyOf:
            - type: number
            - type: 'null'
        hearing_loop:
          anyOf:
            - type: boolean
            - type: 'null'
        setup_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          description: Minutes needed before an event to set up.
        breakdown_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          description: Minutes needed after an event to clear.
      additionalProperties: true
    People:
      type: object
      description: >-
        Everyone taking part in the edition: authors, chairs, staff, publicists…
        A person belongs to the festival and takes part in editions. Fields you
        may not see are left out. Custom fields appear as cf_<field_key>.
      properties:
        id:
          type: string
          format: uuid
        festival_id:
          type: string
          format: uuid
        name:
          type: string
        email:
          anyOf:
            - type: string
            - type: 'null'
        phone:
          anyOf:
            - type: string
            - type: 'null'
        role_type:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Their role at the festival: participant (authors, chairs and other
            speakers), publicist, operations, administrator…
        bio:
          anyOf:
            - type: string
            - type: 'null'
        photo_url:
          anyOf:
            - type: string
            - type: 'null'
        dietary_requirements:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Dietary needs. Personal: handle with care.'
        accessibility_needs:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Access needs. Personal: handle with care.'
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        first_name:
          anyOf:
            - type: string
            - type: 'null'
        last_name:
          anyOf:
            - type: string
            - type: 'null'
        pronoun:
          anyOf:
            - type: string
            - type: 'null'
        address:
          anyOf:
            - type: string
            - type: 'null'
        website:
          anyOf:
            - type: string
            - type: 'null'
        facebook:
          anyOf:
            - type: string
            - type: 'null'
        instagram:
          anyOf:
            - type: string
            - type: 'null'
        tiktok:
          anyOf:
            - type: string
            - type: 'null'
        x_bluesky:
          anyOf:
            - type: string
            - type: 'null'
        other_social_media:
          anyOf:
            - type: string
            - type: 'null'
        contact_name:
          anyOf:
            - type: string
            - type: 'null'
        contact_email:
          anyOf:
            - type: string
            - type: 'null'
        contact_phone:
          anyOf:
            - type: string
            - type: 'null'
        home_location:
          anyOf:
            - type: string
            - type: 'null'
        nationality:
          anyOf:
            - type: string
            - type: 'null'
        accommodation_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
        accomm_status:
          anyOf:
            - type: string
            - type: 'null'
        contact_person_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: Their contact, when someone else handles their arrangements.
        title:
          anyOf:
            - type: string
            - type: 'null'
        capabilities:
          type: array
          items:
            type: string
          description: Crew jobs they can also do (driver, foh, security, technician).
      additionalProperties: true
    Books:
      type: object
      description: >-
        The edition's books (assets). Fields you may not see are left out.
        Custom fields appear as cf_<field_key>.
      properties:
        id:
          type: string
          format: uuid
        festival_id:
          type: string
          format: uuid
        title:
          type: string
        asset_type:
          anyOf:
            - type: string
            - type: 'null'
        author_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: 'The main author (a person). All authors: ?include=authors.'
        book_ai_url:
          anyOf:
            - type: string
            - type: 'null'
        book_jacket_image_url:
          anyOf:
            - type: string
            - type: 'null'
        book_author_image_url:
          anyOf:
            - type: string
            - type: 'null'
        book_publisher:
          anyOf:
            - type: string
            - type: 'null'
        book_requested:
          anyOf:
            - type: boolean
            - type: 'null'
        book_received:
          anyOf:
            - type: boolean
            - type: 'null'
        other_information_notes:
          anyOf:
            - type: string
            - type: 'null'
        isbn_13:
          anyOf:
            - type: string
            - type: 'null'
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        book_publicist_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
        category:
          anyOf:
            - type: string
            - type: 'null'
        age:
          anyOf:
            - type: string
            - type: 'null'
        genre:
          anyOf:
            - type: string
            - type: 'null'
        sub_genre:
          anyOf:
            - type: string
            - type: 'null'
        additional_grouping:
          anyOf:
            - type: string
            - type: 'null'
        format:
          anyOf:
            - type: string
            - type: 'null'
        publication_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        illustrator_name:
          anyOf:
            - type: string
            - type: 'null'
        short_book_description:
          anyOf:
            - type: string
            - type: 'null'
        when_copies_available:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        debut_novel:
          anyOf:
            - type: boolean
            - type: 'null'
        book_ai_text:
          anyOf:
            - type: string
            - type: 'null'
          description: The author information sheet’s text.
        book_location:
          anyOf:
            - type: string
            - type: 'null'
        book_ai_urls:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
        sent_chair:
          anyOf:
            - type: boolean
            - type: 'null'
        authors:
          type: array
          items:
            $ref: '#/components/schemas/People'
          description: Authors. Only with ?include=authors.
        publicists:
          type: array
          items:
            $ref: '#/components/schemas/People'
          description: Publicists. Only with ?include=publicists.
      additionalProperties: true
  securitySchemes:
    agent:
      type: oauth2
      description: >-
        Sign in as a person: Planner shows them what the agent asks for
        (planner:read, planner:propose) and they agree. The agent then sees what
        they can see. Discovery: /.well-known/oauth-protected-resource.
      flows:
        authorizationCode:
          authorizationUrl: https://clerk.fesutibaru.com/oauth/authorize
          tokenUrl: https://clerk.fesutibaru.com/oauth/token
          refreshUrl: https://clerk.fesutibaru.com/oauth/token
          scopes:
            planner:read: Read the festival records you can see in Planner.
            planner:propose: >-
              Propose changes for you to review in your Planner inbox. Nothing
              changes until you accept it.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.