# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Openmercantil Sectors API
  version: 1.0.0
extends: openapi/openmercantil-sectors-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: 8
- target: $.paths['/api/v1/sector/{cnae}/companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List companies in a CNAE sector with filters
      effect: read
      questions:
      - Which Spanish companies operate in a given CNAE activity code?
      - Can I narrow a sector's company list to one province and sort by newest or oldest?
      instructions:
      - text: List companies in CNAE sector {cnae}.
        slots:
          cnae: path.cnae
      - text: List companies in CNAE {cnae} in {province}, sorted {sort}.
        slots:
          cnae: path.cnae
          province: query.province
          sort: query.sort
      - text: 'Page CNAE {cnae} companies: {limit} results from offset {offset}.'
        slots:
          cnae: path.cnae
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sector/{cnae}/ratios'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Banco de España ratios for a CNAE division
      effect: read
      questions:
      - What are the Banco de España Central de Balances ratios by year for a two-digit CNAE division?
      - Are sector ratios aggregate only, or do they include individual companies?
      instructions:
      - text: Get the Central de Balances ratios by year for CNAE division {cnae}.
        slots:
          cnae: path.cnae
      - text: Show yearly aggregate Banco de España metrics for division {cnae}.
        slots:
          cnae: path.cnae
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/cnae/tree'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the CNAE activity code hierarchy
      effect: read
      questions:
      - What does the full CNAE-2009 activity classification hierarchy look like?
      - How many companies sit under each branch of the CNAE tree?
      instructions:
      - text: Show the CNAE-2009 tree with company counts.
      - text: Get the hierarchical list of CNAE activity codes.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/cnae/{code}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a CNAE code
      effect: read
      questions:
      - What activity does a given CNAE code stand for?
      - How many companies are registered under one CNAE code?
      instructions:
      - text: Look up CNAE code {code}.
        slots:
          code: path.code
      - text: Tell me what CNAE {code} means and its company count.
        slots:
          code: path.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sector/{code}/companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List companies in a sector (v1.1 route)
      effect: read
      questions:
      - Is there a simpler v1.1 route that just lists companies under a sector code with a limit?
      - Does the v1.1 sector company list take anything besides a limit?
      instructions:
      - text: Use the v1.1 sector route to list companies in {code}.
        slots:
          code: path.code
      - text: Return {limit} companies from sector {code} via the v1.1 listing.
        slots:
          limit: query.limit
          code: path.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sector/{code}/ratios'].get
  update:
    x-apievangelist-phrasing:
      intent: Get sector financial ratios (v1.1 route)
      effect: read
      questions:
      - Where is the v1.1 endpoint for a sector's aggregated financial ratios?
      - Does the v1.1 sector ratios route use Banco de España data too?
      instructions:
      - text: Get the v1.1 aggregated financial ratios for sector {code}.
        slots:
          code: path.code
      - text: Pull BdE ratios for sector {code} through the v1.1 route.
        slots:
          code: path.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sectores/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get company counts and growth across sectors
      effect: read
      questions:
      - Which CNAE sectors have the most companies and the fastest growth?
      - Can I compare aggregate statistics across all sectors in JSON?
      instructions:
      - text: Get aggregate company counts and growth for every sector.
      - text: Compare sectors by company count and growth.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sectores/stats.csv'].get
  update:
    x-apievangelist-phrasing:
      intent: Download sector statistics as CSV
      effect: read
      questions:
      - Can I download the sector aggregate statistics as a CSV file?
      - Is there a spreadsheet version of the per-sector counts?
      instructions:
      - text: Download the sector stats as CSV.
      - text: Export the per-sector aggregate statistics to a CSV file.
      method: generated
      generated: '2026-09-26'