# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bindbee Custom Fields API
  version: 1.0.0
extends: openapi/bindbee-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: 12
- target: $.paths['/api/v1/custom-fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom field definitions
      effect: read
      questions:
      - Which custom fields has my organization defined?
      - Can I filter custom field definitions by category and model?
      instructions:
      - text: List custom fields for category {category} and model {model}.
        slots:
          category: query.category
          model: query.model
      - text: Show custom field definitions from source {source}.
        slots:
          source: query.source
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields'].post
  update:
    x-apievangelist-phrasing:
      intent: Define a new custom field
      effect: write
      questions:
      - How do I define a new custom field on a unified model?
      - Can I add an extra field to the employee model for my organization?
      instructions:
      - text: Create custom field {name} on model {model} in category {category}.
        slots:
          name: requestBody.name
          model: requestBody.model
          category: requestBody.category
      - text: Define custom field {name} for {category} {model} described as {description}.
        slots:
          name: requestBody.name
          category: requestBody.category
          model: requestBody.model
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/mapping'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom field mappings
      effect: read
      questions:
      - Which JMESPath mappings are set up for an integration?
      - Can I see the field mappings that apply to one connector?
      instructions:
      - text: List custom field mappings for integration {integration_slug}.
        slots:
          integration_slug: query.integration_slug
      - text: Show mappings scoped to connector token {connector_token}.
        slots:
          connector_token: query.connector_token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/mapping'].post
  update:
    x-apievangelist-phrasing:
      intent: Map a custom field to source data
      effect: write
      questions:
      - How do I tell a custom field where to read its value from in the source system?
      - Can I scope a mapping to just one connector instead of the whole integration?
      instructions:
      - text: Map custom field {custom_field_id} to path {json_path} for integration {integration_slug}.
        slots:
          custom_field_id: requestBody.custom_field_id
          json_path: requestBody.json_path
          integration_slug: requestBody.integration_slug
      - text: Create a connector-level mapping of field {custom_field_id} to {json_path} for connector {connector_token}.
        slots:
          custom_field_id: requestBody.custom_field_id
          json_path: requestBody.json_path
          connector_token: requestBody.connector_token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/mapping/{custom_field_mapping_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom field mapping
      effect: destructive
      questions:
      - How do I remove a mapping without deleting the custom field itself?
      - Can I drop one connector's override mapping?
      instructions:
      - text: Delete custom field mapping {custom_field_mapping_id}.
        slots:
          custom_field_mapping_id: path.custom_field_mapping_id
      - text: Remove mapping {custom_field_mapping_id} from its custom field.
        slots:
          custom_field_mapping_id: path.custom_field_mapping_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/mapping/{custom_field_mapping_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a mapping's JMESPath
      effect: write
      questions:
      - How do I fix the JMESPath expression on an existing mapping?
      - What can I change on a mapping after it is created?
      instructions:
      - text: Change mapping {custom_field_mapping_id} to use path {json_path}.
        slots:
          custom_field_mapping_id: path.custom_field_mapping_id
          json_path: requestBody.json_path
      - text: Update the JMESPath of mapping {custom_field_mapping_id} to {json_path}.
        slots:
          custom_field_mapping_id: path.custom_field_mapping_id
          json_path: requestBody.json_path
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/raw-data'].get
  update:
    x-apievangelist-phrasing:
      intent: Inspect raw upstream data for a model
      effect: read
      questions:
      - What does the raw payload from the source system look like before I write a JMESPath?
      - Can I inspect upstream employee data to discover which fields exist?
      instructions:
      - text: Show raw upstream data for {category} {model} on connector {connector_token}.
        slots:
          category: query.category
          model: query.model
          connector_token: query.connector_token
      - text: Inspect the source payload for model {model} in category {category}.
        slots:
          model: query.model
          category: query.category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a JMESPath before saving a mapping
      effect: read
      questions:
      - Can I dry-run a JMESPath expression against real connector data first?
      - How do I check what value a mapping would extract without saving it?
      instructions:
      - text: Preview what {json_path} returns for {category} {model} on connector {connector_token}.
        slots:
          json_path: requestBody.json_path
          category: requestBody.category
          model: requestBody.model
          connector_token: requestBody.connector_token
      - text: Dry-run expression {json_path} against model {model} in {category} for connector {connector_token}.
        slots:
          json_path: requestBody.json_path
          model: requestBody.model
          category: requestBody.category
          connector_token: requestBody.connector_token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get effective custom field setup for a connector
      effect: read
      questions:
      - Which mapping actually applies to each custom field on a given connector?
      - Can I see whether a field uses a connector override or the organization default?
      instructions:
      - text: Show the effective custom field configuration for {category} {model} on connector {connector_token}.
        slots:
          category: query.category
          model: query.model
          connector_token: query.connector_token
      - text: Get every custom field and its resolved mapping for connector {connector_token}, model {model}, category {category}.
        slots:
          connector_token: query.connector_token
          model: query.model
          category: query.category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/{custom_field_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one custom field with its mappings
      effect: read
      questions:
      - What mappings are attached to one custom field?
      - Can I view a single custom field definition by id?
      instructions:
      - text: Get custom field {custom_field_id}.
        slots:
          custom_field_id: path.custom_field_id
      - text: Show custom field {custom_field_id} and all of its mappings.
        slots:
          custom_field_id: path.custom_field_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/{custom_field_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom field
      effect: destructive
      questions:
      - How do I delete a custom field definition I no longer use?
      - Can I remove a custom field entirely from my organization?
      instructions:
      - text: Delete custom field {custom_field_id}.
        slots:
          custom_field_id: path.custom_field_id
      - text: Remove the custom field definition {custom_field_id}.
        slots:
          custom_field_id: path.custom_field_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/custom-fields/{custom_field_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or edit a custom field
      effect: write
      questions:
      - Can I change a custom field's category or model after creating it?
      - How do I rename a custom field or update its description?
      instructions:
      - text: Rename custom field {custom_field_id} to {name}.
        slots:
          custom_field_id: path.custom_field_id
          name: requestBody.name
      - text: Update the description of custom field {custom_field_id} to {description}.
        slots:
          custom_field_id: path.custom_field_id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'