> ## 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.

# One edition



## OpenAPI

````yaml https://api-test.fesutibaru.com/api/v1/openapi.json get /editions/{id}
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:
  /editions/{id}:
    get:
      tags:
        - Editions
      summary: One edition
      operationId: get_edition
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Editions'
        '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:
    Editions:
      type: object
      description: >-
        The festival's editions (years). One is current; the others can be read
        with ?edition=. 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
        year:
          type: integer
        name:
          anyOf:
            - type: string
            - type: 'null'
        dates_start:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          description: First day of the festival.
        dates_end:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          description: Last day of the festival.
        status:
          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'
        is_current:
          anyOf:
            - type: boolean
            - type: 'null'
          description: The edition everything defaults to.
        date_buffer_days:
          type: integer
        event_gap_minutes:
          type: integer
        schedule_start_hour:
          type: integer
        schedule_end_hour:
          type: integer
        open_to_pitches:
          type: boolean
          description: Publicists can send pitches to it.
        travel_offered:
          type: boolean
          description: The festival arranges authors’ travel.
      additionalProperties: true
    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
  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.