# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Openmercantil Persons API
  version: 1.0.0
extends: openapi/openmercantil-persons-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: 5
- target: $.paths['/api/v1/company/{slug}/officers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's current and past officers
      effect: read
      questions:
      - Who are the directors and administrators of a Spanish company?
      - Can I see former officers of a company, not just the current board?
      - How many officer mentions can come back for one company?
      instructions:
      - text: List the officers of {company}.
        slots:
          company: path.slug
      - text: Show current and historical directors of {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/persona/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get documentary registry mentions of a person
      effect: read
      questions:
      - In which BORME publications is a person mentioned?
      - Is the person report an identity profile or just registry mentions?
      instructions:
      - text: Get the documentary mentions of person {person}.
        slots:
          person: path.slug
      - text: Show where {person} appears in company registry records.
        slots:
          person: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/person/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get person mentions via the legacy English route
      effect: read
      questions:
      - Does the deprecated English person route still return registry mentions?
      - Which route replaced the English person alias?
      instructions:
      - text: Get mentions of {person} through the legacy English person route.
        slots:
          person: path.slug
      - text: Call the deprecated person alias for {person}.
        slots:
          person: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/person/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search registry mentions of people by name
      effect: read
      questions:
      - How do I find a person by name in company registry records?
      - How many name matches can a person search return?
      instructions:
      - text: Search person mentions for {q}.
        slots:
          q: query.q
      - text: Find up to {limit} people named {q} in BORME.
        slots:
          limit: query.limit
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/persona/{slug}/contracts'].get
  update:
    x-apievangelist-phrasing:
      intent: Get procurement linked to a person
      effect: read
      questions:
      - Can I see public contracts connected to a specific person?
      - Why is the person-to-procurement route unavailable?
      instructions:
      - text: Get the procurement contracts linked to person {person}.
        slots:
          person: path.slug
      - text: Show public tenders connected to {person} through their companies.
        slots:
          person: path.slug
      method: generated
      generated: '2026-09-26'