# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Reference Contacts API
  version: 1.0.0
extends: openapi/lightfield-contacts-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/v1/contacts/definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the field schema for contacts
      effect: read
      questions:
      - What fields and custom fields are available on a contact record in Lightfield?
      - Which contact fields are custom versus built-in before I add people?
      instructions:
      - text: Show me the field and relationship definitions for contacts.
      - text: Fetch the contact schema including custom fields.
      - text: Get contact field definitions using API version {version}.
        slots:
          version: header.Lightfield-Version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List contacts
      effect: read
      questions:
      - How can I page through every person stored as a contact?
      - Can I filter contacts by a field to check whether someone already exists?
      instructions:
      - text: List my contacts.
      - text: List {limit} contacts starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a contact
      effect: write
      questions:
      - How do I add a new person as a contact, and will it be enriched automatically?
      - Can I safely retry creating a contact without making a duplicate?
      instructions:
      - text: 'Create a contact with these fields: {fields}.'
        slots:
          fields: requestBody.fields
      - text: Add a new contact using {fields} and attach them via {relationships}.
        slots:
          fields: requestBody.fields
          relationships: requestBody.relationships
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one contact by ID
      effect: read
      questions:
      - How do I fetch a single contact when I have their ID?
      - Can I see the full record for one specific person?
      instructions:
      - text: Get contact {id}.
        slots:
          id: path.id
      - text: Show me the details of contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/contacts/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an existing contact
      effect: write
      questions:
      - How do I edit a person's details on a contact I already have?
      - Can I change just one field on an existing contact?
      instructions:
      - text: Update contact {id} with {fields}.
        slots:
          id: path.id
          fields: requestBody.fields
      - text: Change the relationships on existing contact {id} to {relationships}.
        slots:
          id: path.id
          relationships: requestBody.relationships
      method: generated
      generated: '2026-10-01'