# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenMercantil Datasets API
  version: 1.0.0
extends: openapi/openmercantil-datasets-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: 13
- target: $.paths['/api/v1/datasets/public'].get
  update:
    x-apievangelist-phrasing:
      intent: List the public company dataset downloads
      effect: read
      questions:
      - Which bulk company datasets can I download for free?
      - Where do I find the public company download files and their checksums?
      instructions:
      - text: List the public company dataset downloads.
      - text: Show me the downloadable company data files currently published.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ccaa/stats.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get company totals by autonomous community
      effect: read
      questions:
      - How many companies are registered in each Spanish autonomous community?
      - Can I get per-CCAA aggregates as JSON from the stats.json route?
      instructions:
      - text: Get the aggregates by autonomous community from ccaa stats.json.
      - text: Show company and award-procedure totals for every CCAA.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ccaa/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get CCAA aggregates via the legacy alias
      effect: read
      questions:
      - Does the old suffix-less /ccaa/stats route still work?
      - Which route replaced the deprecated CCAA stats alias?
      instructions:
      - text: Fetch CCAA aggregates through the legacy suffix-less stats alias.
      - text: Call the deprecated ccaa stats route without .json.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sectores/stats.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get company totals by CNAE sector as JSON
      effect: read
      questions:
      - How many companies are there in each CNAE sector section?
      - Can I get per-sector totals as JSON from sectores stats.json?
      instructions:
      - text: Get the CNAE sector aggregates from sectores stats.json.
      - text: Show company and procurement totals per CNAE section in JSON.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sectores/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get sector aggregates via the legacy alias
      effect: read
      questions:
      - Does the deprecated suffix-less /sectores/stats route still return data?
      - Which route should I use instead of the old sector stats alias?
      instructions:
      - text: Fetch sector aggregates through the legacy suffix-less sectores stats alias.
      - text: Call the deprecated sectores stats route without an extension.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sectores/stats.csv'].get
  update:
    x-apievangelist-phrasing:
      intent: Download CNAE sector aggregates as CSV
      effect: read
      questions:
      - Can I download the per-sector statistics as a CSV file?
      - Which columns are in the sector stats CSV?
      instructions:
      - text: Download the CNAE sector aggregates as CSV.
      - text: Export per-sector totals to a spreadsheet file.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/top-companies'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank corporate suppliers via top-companies route
      effect: read
      questions:
      - Which companies top the contracts top-companies ranking by award procedures?
      - Does the top-companies ranking include money totals or only award counts?
      instructions:
      - text: Get the top {limit} companies by PLACSP award procedures.
        slots:
          limit: query.limit
      - text: Show the top-companies contracts ranking.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/top-persons'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank persons by procurement-signing companies
      effect: read
      questions:
      - Is there a ranking of people linked to companies that win public contracts?
      - Why does the top-persons contracts ranking always return 503?
      instructions:
      - text: Get the top persons contracts ranking.
      - text: Show which people rank highest by PLACSP-signatory companies.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/top-companies.csv'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the top-companies ranking as CSV
      effect: read
      questions:
      - Can I download the ranking of top procurement suppliers as a CSV?
      - How many rows can the top-companies CSV contain?
      instructions:
      - text: Download the top {limit} companies by award procedures as CSV.
        slots:
          limit: query.limit
      - text: Export the top-companies contracts ranking to CSV.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/contracts/top-persons.csv'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the top-persons ranking as CSV
      effect: read
      questions:
      - Is there a CSV export of the top persons by public contracts?
      - Why does the top-persons CSV download fail with 503?
      instructions:
      - text: Download the top persons contracts ranking as CSV.
      - text: Export the persons-by-PLACSP-signatory ranking to a CSV file.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/export/events'].get
  update:
    x-apievangelist-phrasing:
      intent: Request the bulk BORME events export
      effect: read
      questions:
      - Can I bulk download every BORME event in one export?
      - Why is the bulk BORME export unavailable?
      instructions:
      - text: Request the bulk BORME events export.
      - text: Download all BORME events as a single export.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/export/companies'].get
  update:
    x-apievangelist-phrasing:
      intent: Request a bulk company export
      effect: read
      questions:
      - Can I export a filtered list of all companies in a province?
      - Which plan and scope do I need for the bulk company export?
      - Why does the bulk company export return offline_export_required?
      instructions:
      - text: Export all {tipo} companies in {provincia}.
        slots:
          tipo: query.tipo
          provincia: query.provincia
      - text: Request a bulk company export in {formato} format.
        slots:
          formato: query.formato
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a single company report as JSON
      effect: read
      questions:
      - Can I download one company's report as a JSON file?
      - Is there a size limit on a single company export?
      instructions:
      - text: Export the company report for {company} as JSON.
        slots:
          company: path.slug
      - text: Download {company}'s report to a file.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'