API Evangelist conversational phrasing for OpenMercantil Public Procurement API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenMercantil Public Procurement API
  version: 1.0.0
extends: openapi/openmercantil-public-procurement-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/company/{slug}/contracts'].get
  update:
    x-apievangelist-phrasing:
      intent: List procurement notices linked to a company
      effect: read
      questions:
      - Which public procurement notices is a Spanish company linked to?
      - Does a company's PLACSP contract list prove it was actually paid?
      - Can I cap how many procurement notices come back for a company?
      instructions:
      - text: List the PLACSP procurement notices for {company}.
        slots:
          company: path.slug
      - text: Show the first {limit} public tenders linked to {company}.
        slots:
          limit: query.limit
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/procurement'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's procurement via the alias route
      effect: read
      questions:
      - Is there a /procurement alias that returns the same payload as a company's contracts route?
      - Which canonical route does the company procurement alias point to?
      instructions:
      - text: Fetch {company}'s procurement notices through the /procurement alias.
        slots:
          company: path.slug
      - text: Call the procurement alias route for {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/grants'].get
  update:
    x-apievangelist-phrasing:
      intent: List public grants awarded to a company
      effect: read
      questions:
      - Which BDNS public subsidies has a Spanish company been awarded?
      - Are grant amounts reported as payments or as awarded amounts?
      - Does an empty grant list mean the company never got a subsidy?
      instructions:
      - text: List the public grants awarded to {company}.
        slots:
          company: path.slug
      - text: Show up to {limit} BDNS subsidies for {company}.
        slots:
          limit: query.limit
          company: path.slug
      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'
- target: $.paths['/api/v1/company/{slug}/ted'].get
  update:
    x-apievangelist-phrasing:
      intent: List EU TED notices linked to a company
      effect: read
      questions:
      - Which EU Tenders Electronic Daily notices mention a Spanish company's NIF?
      - Do TED notice links prove the company won or was paid for the contract?
      instructions:
      - text: List the TED notices linked to {company}.
        slots:
          company: path.slug
      - text: Show {limit} European tender notices for {company}.
        slots:
          limit: query.limit
          company: path.slug
      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/tenders'].get
  update:
    x-apievangelist-phrasing:
      intent: Search public procurement notices
      effect: read
      questions:
      - How do I search Spanish public tenders by keyword or CPV code?
      - Can I only see tenders that are still open for bids?
      - What do I need to set to filter tenders by an amount range?
      - Which tenders did a particular supplier CIF win?
      instructions:
      - text: Search public tenders for {q}.
        slots:
          q: query.q
      - text: Find open tenders with CPV code {cpv} in {province}.
        slots:
          cpv: query.cpv
          province: query.province
      - text: Search tenders published between {published_from} and {published_to} by buyer {buyer_nif}.
        slots:
          published_from: query.published_from
          published_to: query.published_to
          buyer_nif: query.buyer_nif
      - text: Find tenders awarded to supplier {supplier_cif}.
        slots:
          supplier_cif: query.supplier_cif
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tenders/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one procurement notice
      effect: read
      questions:
      - What are the lots, CPV codes and results of a specific tender?
      - Can I fetch a single procurement notice by its key?
      instructions:
      - text: Get tender {key}.
        slots:
          key: path.key
      - text: Show the lots and award results of procurement notice {key}.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tenders/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get procurement coverage metrics
      effect: read
      questions:
      - How many procurement notices does the tender dataset cover and how fresh is it?
      - What share of tenders have geography or CODICE v3 data?
      instructions:
      - text: Get the procurement coverage stats.
      - text: Show how fresh and complete the tender data is.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/tenders/suppliers'].get
  update:
    x-apievangelist-phrasing:
      intent: List tender suppliers ranked by award count
      effect: read
      questions:
      - Which corporate suppliers appear most often in awarded tenders?
      - Are individual people included in the tender suppliers list?
      instructions:
      - text: List the tender suppliers ranked by award count.
      - text: Show the top {limit} corporate tender suppliers.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'