# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Reference Custom Fields API
  version: 1.0.0
extends: openapi/beehiiv-custom-fields-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/publications/{publicationId}/custom_fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List a publication's custom fields
      effect: read
      questions:
      - What custom subscriber fields exist on my newsletter?
      - Which extra profile fields can I store on subscribers?
      instructions:
      - text: List the custom fields on publication {publication}.
        slots:
          publication: path.publicationId
      - text: Show every extra subscriber field defined on {publication}.
        slots:
          publication: path.publicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/custom_fields'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom subscriber field
      effect: write
      questions:
      - How do I add a new custom field like birthday or company to my subscribers?
      - Can I choose the data type when creating a custom field?
      instructions:
      - text: Create a {kind} custom field called {display} on publication {publication}.
        slots:
          kind: requestBody.kind
          display: requestBody.display
          publication: path.publicationId
      - text: Add a custom subscriber field labeled {display} that stores {kind} values.
        slots:
          display: requestBody.display
          kind: requestBody.kind
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/custom_fields/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one custom field
      effect: read
      questions:
      - What type and label does a specific custom field have?
      - Can I view a single custom field by its ID?
      instructions:
      - text: Get custom field {field} on publication {publication}.
        slots:
          field: path.id
          publication: path.publicationId
      - text: Show the type and label of custom field {field}.
        slots:
          field: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/custom_fields/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a custom field (PUT)
      effect: write
      questions:
      - How do I change a custom field's display name with a PUT request?
      - Can I replace a custom field's label via PUT?
      instructions:
      - text: PUT a new display name {display} on custom field {field} in publication {publication}.
        slots:
          display: requestBody.display
          field: path.id
          publication: path.publicationId
      - text: Replace the label of custom field {field} with {display} using PUT.
        slots:
          field: path.id
          display: requestBody.display
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/custom_fields/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom field
      effect: destructive
      questions:
      - How do I remove a custom field I no longer use?
      - Can I delete a custom subscriber field from my publication?
      instructions:
      - text: Delete custom field {field} from publication {publication}.
        slots:
          field: path.id
          publication: path.publicationId
      - text: Remove the unused custom field {field}.
        slots:
          field: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/custom_fields/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a custom field (PATCH)
      effect: write
      questions:
      - Can I PATCH just the display label of a custom field?
      - What's the PATCH call for relabeling a custom field?
      instructions:
      - text: PATCH custom field {field} on {publication} so it displays as {display}.
        slots:
          field: path.id
          publication: path.publicationId
          display: requestBody.display
      - text: Relabel custom field {field} to {display} with a PATCH.
        slots:
          field: path.id
          display: requestBody.display
      method: generated
      generated: '2026-09-26'