# 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'