# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Trello Custom Fields API
  version: 1.0.0
extends: openapi/trello-custom-fields-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/customFields'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom field on a board
      effect: write
      questions:
      - How do I add a new custom field, like a dropdown or number, to a board?
      - Can I show a custom field on the front of cards when I create it?
      instructions:
      - text: Create a {type} custom field called {name} on board {idModel} of model type {modelType} at position {pos}.
        slots:
          type: requestBody.type
          name: requestBody.name
          idModel: requestBody.idModel
          modelType: requestBody.modelType
          pos: requestBody.pos
      - text: Add a dropdown field {name} with options {options} to board {idModel}, model type {modelType}, type {type}, position {pos}.
        slots:
          name: requestBody.name
          options: requestBody.options
          idModel: requestBody.idModel
          modelType: requestBody.modelType
          type: requestBody.type
          pos: requestBody.pos
      method: generated
      generated: '2026-10-02'
- target: $.paths['/customFields/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom field definition
      effect: read
      questions:
      - How do I look up a custom field's type and name?
      - Can I fetch one custom field definition by id?
      instructions:
      - text: Get custom field {id}.
        slots:
          id: path.id
      - text: Show the definition of custom field {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/customFields/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or reposition a custom field
      effect: write
      questions:
      - Can I rename a custom field after it's been created?
      - How do I stop a custom field from showing on the card front?
      instructions:
      - text: Rename custom field {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Move custom field {id} to position {pos}.
        slots:
          id: path.id
          pos: requestBody.pos
      method: generated
      generated: '2026-10-02'
- target: $.paths['/customFields/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom field and its values
      effect: destructive
      questions:
      - What happens to card values when I delete a custom field?
      - How do I remove a custom field from a board entirely?
      instructions:
      - text: Delete custom field {id} and clear its values from all cards.
        slots:
          id: path.id
      - text: Remove custom field definition {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/cards/{id}/customFieldItems'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the custom field values on a card
      effect: read
      questions:
      - Which custom field values are filled in on a card?
      - How do I read all custom field data for one card?
      instructions:
      - text: Get the custom field values on card {id}.
        slots:
          id: path.id
      - text: List custom field items set on card {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/cards/{idCard}/customField/{idCustomField}/item'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a custom field value on a card
      effect: write
      questions:
      - How do I fill in a custom field value on a specific card?
      - Can I pick a dropdown option for a card's custom field by option id?
      instructions:
      - text: Set custom field {idCustomField} on card {idCard} to {value}.
        slots:
          idCustomField: path.idCustomField
          idCard: path.idCard
          value: requestBody.value
      - text: Choose dropdown option {idValue} for field {idCustomField} on card {idCard}.
        slots:
          idValue: requestBody.idValue
          idCustomField: path.idCustomField
          idCard: path.idCard
      method: generated
      generated: '2026-10-02'
- target: $.paths['/customFields/{id}/options'].get
  update:
    x-apievangelist-phrasing:
      intent: List the options of a dropdown custom field
      effect: read
      questions:
      - What choices are available in a dropdown custom field?
      - How do I list every option on a dropdown field?
      instructions:
      - text: List the options of dropdown custom field {id}.
        slots:
          id: path.id
      - text: Show all choices in dropdown field {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/customFields/{id}/options'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an option to a dropdown custom field
      effect: write
      questions:
      - How do I add a new choice to an existing dropdown field?
      - Can I extend a dropdown custom field with another option?
      instructions:
      - text: Add a new option to dropdown custom field {id}.
        slots:
          id: path.id
      - text: Create another choice on dropdown field {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/customFields/{id}/options/{idCustomFieldOption}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one option of a dropdown custom field
      effect: read
      questions:
      - How do I look up a single dropdown option by its id?
      - Can I see the text and color of one dropdown choice?
      instructions:
      - text: Get option {idCustomFieldOption} of dropdown field {id}.
        slots:
          idCustomFieldOption: path.idCustomFieldOption
          id: path.id
      - text: Show dropdown choice {idCustomFieldOption} on custom field {id}.
        slots:
          idCustomFieldOption: path.idCustomFieldOption
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/customFields/{id}/options/{idCustomFieldOption}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an option from a dropdown custom field
      effect: destructive
      questions:
      - How do I remove a choice from a dropdown custom field?
      - Can I delete a dropdown option nobody uses anymore?
      instructions:
      - text: Delete option {idCustomFieldOption} from dropdown field {id}.
        slots:
          idCustomFieldOption: path.idCustomFieldOption
          id: path.id
      - text: Remove dropdown choice {idCustomFieldOption} on custom field {id}.
        slots:
          idCustomFieldOption: path.idCustomFieldOption
          id: path.id
      method: generated
      generated: '2026-10-02'