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

# Propose changes

> Propose changes for the person you act for. Nothing changes until they accept it in their Planner inbox, change by change or all at once. Group one task into one proposal, with a clear title and a short note.

Every change is checked as if the person made it: the record is this festival’s (and edition’s), the fields can be proposed and they may change them. If any change is refused, nothing is proposed and `problems` lists each refusal by position: correct them and propose again.

Changes: update {op, table, id, data}; create {op, table, data, ref?}; delete {op, table, id} (to the Recycle Bin); link/unlink {op, table: junction, data: {parent_id, related_id}}. A ref ($new_event) lets a later change point at a record this proposal creates.

Fields never proposed: id, festival_id, edition_id, user_id, role_type, capabilities, metadata, timestamps, printed and deleted marks. Custom fields are cf_<field_key>.

Send an Idempotency-Key header: the same key again returns the first proposal instead of making a second.



## OpenAPI

````yaml https://api-test.fesutibaru.com/api/v1/openapi.json post /proposals
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:
  /proposals:
    post:
      tags:
        - Proposals
      summary: Propose changes
      description: >-
        Propose changes for the person you act for. Nothing changes until they
        accept it in their Planner inbox, change by change or all at once. Group
        one task into one proposal, with a clear title and a short note.


        Every change is checked as if the person made it: the record is this
        festival’s (and edition’s), the fields can be proposed and they may
        change them. If any change is refused, nothing is proposed and
        `problems` lists each refusal by position: correct them and propose
        again.


        Changes: update {op, table, id, data}; create {op, table, data, ref?};
        delete {op, table, id} (to the Recycle Bin); link/unlink {op, table:
        junction, data: {parent_id, related_id}}. A ref ($new_event) lets a
        later change point at a record this proposal creates.


        Fields never proposed: id, festival_id, edition_id, user_id, role_type,
        capabilities, metadata, timestamps, printed and deleted marks. Custom
        fields are cf_<field_key>.


        Send an Idempotency-Key header: the same key again returns the first
        proposal instead of making a second.
      operationId: propose_changes
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProposalRequest'
      responses:
        '200':
          description: 'The same Idempotency-Key again: the first proposal.'
          content:
            application/json:
              schema:
                type: object
        '201':
          description: 'Proposed: waiting in the person’s inbox.'
          content:
            application/json:
              schema:
                type: object
        '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'
        '422':
          description: >-
            Some changes were refused; nothing was proposed. problems lists each
            by position.
          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'
      security:
        - agent:
            - planner:propose
components:
  schemas:
    ProposalRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: 'One line: what this proposal does.'
        note:
          description: >-
            Why, briefly: what you were asked, and anything the person should
            check.
          type: string
          maxLength: 4000
        edition:
          description: >-
            The edition the changes are for, by year. Default: the current
            edition.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        changes:
          minItems: 1
          maxItems: 500
          type: array
          items:
            type: object
            properties:
              op:
                type: string
                enum:
                  - create
                  - update
                  - delete
                  - link
                  - unlink
                description: What to do.
              table:
                type: string
                description: >-
                  The table: event, person, venue, assets, travel,
                  accommodation, accommodation_assignment, pickup; or for
                  link/unlink a junction such as event_author.
              id:
                description: The record, for update and delete.
                type: string
              ref:
                description: >-
                  For create: a name such as $new_event, so later changes in the
                  same proposal can point at the new record.
                type: string
              data:
                description: >-
                  update/create: the fields and their new values. link/unlink: {
                  parent_id, related_id }.
                type: object
                additionalProperties: {}
            required:
              - op
              - table
            additionalProperties: false
      required:
        - title
        - changes
      additionalProperties: false
    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.