# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Openmercantil Companies API
  version: 1.0.0
extends: openapi/openmercantil-companies-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: 34
- target: $.paths['/api/v1/company/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Spanish company's registry report
      effect: read
      questions:
      - What does OpenMercantil's structured report on a Spanish company include?
      - Can I pull the full registry profile of a company using its slug?
      - What happens if I ask for a company under an old historical slug?
      instructions:
      - text: Get the company report for {company}.
        slots:
          company: path.slug
      - text: Show me the full registry profile of {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/companies/compare'].get
  update:
    x-apievangelist-phrasing:
      intent: Compare two companies side by side
      effect: read
      questions:
      - Can I compare two Spanish companies side by side in one request?
      - Which fields come back when I compare exactly two companies?
      - Is it possible to compare more than two companies at once?
      instructions:
      - text: Compare the two companies {slugs}.
        slots:
          slugs: query.slugs
      - text: Put {slugs} side by side and show how they differ.
        slots:
          slugs: query.slugs
      method: generated
      generated: '2026-09-26'
- 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/company/{slug}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's BORME events by year
      effect: read
      questions:
      - How do I see every BORME registry event published for a company?
      - Can I filter a company's registry events to a single calendar year?
      - What page size can I use when paging through a company's BORME events?
      instructions:
      - text: List the BORME events for {company} in {year}.
        slots:
          company: path.slug
          year: query.year
      - text: Show page {page} of the registry events for {company}.
        slots:
          company: path.slug
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/timeline'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's combined multi-source timeline
      effect: read
      questions:
      - Can I get one chronological timeline mixing a company's BORME acts and procurement notices?
      - Which sources feed the unified company timeline?
      instructions:
      - text: Build the unified timeline for {company}.
        slots:
          company: path.slug
      - text: Show BORME and procurement history for {company} in chronological order.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- 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/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/company/{slug}/ip'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's trademarks and patents
      effect: read
      questions:
      - Can I look up the trademarks and patents a Spanish company holds?
      - Why does the company intellectual property route return a 503?
      instructions:
      - text: Get the trademarks and patents registered to {company}.
        slots:
          company: path.slug
      - text: Check the OEPM, EUIPO and EPO filings for {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/sources'].get
  update:
    x-apievangelist-phrasing:
      intent: Show which data sources cover a company
      effect: read
      questions:
      - Which integrated sources have data about a given company?
      - Does empty coverage for a source prove the company is absent there?
      instructions:
      - text: Show the data source coverage for {company}.
        slots:
          company: path.slug
      - text: Check which of BDNS, CNMV, TED and Wikidata have records on {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/sanctions'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a company against sanctions data
      effect: read
      questions:
      - Is a Spanish company on any sanctions list?
      - Why is the company sanctions dataset unavailable right now?
      instructions:
      - text: Check whether {company} appears in sanctions data.
        slots:
          company: path.slug
      - text: Screen {company} against the sanctions dataset.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/empresa/{slug}/facts'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's extracted BORME facts
      effect: read
      questions:
      - What appointments, removals and capital changes has a company published in BORME?
      - Can I get BORME facts for a company grouped by type through the Spanish empresa route?
      instructions:
      - text: Get the extracted BORME facts for empresa {company}.
        slots:
          company: path.slug
      - text: Show up to {limit} BORME facts for {company} grouped by type.
        slots:
          limit: query.limit
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/facts'].get
  update:
    x-apievangelist-phrasing:
      intent: Get BORME facts via the legacy English route
      effect: read
      questions:
      - Does the deprecated English company facts route still return BORME facts?
      - Which route replaced the English company facts alias?
      instructions:
      - text: Get BORME facts for {company} through the legacy English facts route.
        slots:
          company: path.slug
      - text: Call the deprecated company facts alias for {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sector/{cnae}/companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List companies in a CNAE sector
      effect: read
      questions:
      - Which companies belong to a given CNAE activity code?
      - Can I narrow a sector's companies to one province?
      - What sort orders are allowed when listing companies by sector?
      instructions:
      - text: List companies in CNAE sector {cnae}.
        slots:
          cnae: path.cnae
      - text: Show the companies in sector {cnae} located in {province}.
        slots:
          cnae: path.cnae
          province: query.province
      - text: List the oldest {limit} companies with CNAE code {cnae}.
        slots:
          limit: query.limit
          cnae: path.cnae
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/relationships'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's documentary relationships
      effect: read
      questions:
      - Which people, companies, contracts and grants are documented as connected to a company?
      - Can I filter a company's relationships by type or confidence level?
      - Do documented relationships imply control or ownership?
      instructions:
      - text: List the documented relationships of {company}.
        slots:
          company: path.slug
      - text: Show {type} relationships for {company}.
        slots:
          type: query.type
          company: path.slug
      - text: List relationships of {company} with {confidence} confidence.
        slots:
          confidence: query.confidence
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/risk-signals'].get
  update:
    x-apievangelist-phrasing:
      intent: Get documentary risk signals for a company
      effect: read
      questions:
      - What risk signals are published for a Spanish company?
      - Does a missing risk signal mean the underlying fact doesn't exist?
      instructions:
      - text: Get the documentary risk signals for {company}.
        slots:
          company: path.slug
      - text: Show authorized risk flags on {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/lei'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's LEI record
      effect: read
      questions:
      - Can I find the Legal Entity Identifier for a Spanish company?
      - Why is the GLEIF LEI lookup for a company returning 503?
      instructions:
      - text: Get the LEI record for {company}.
        slots:
          company: path.slug
      - text: Look up the GLEIF legal entity identifier of {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/bde'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Banco de España sector ratios for a company
      effect: read
      questions:
      - How does a company's sector compare on Banco de España Central de Balances ratios?
      - Are the Banco de España ratios specific to the company or to its sector?
      instructions:
      - text: Get the Banco de España sector ratios for {company}.
        slots:
          company: path.slug
      - text: Benchmark the CNAE sector of {company} using Central de Balances ratios.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/cnmv'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's CNMV listing and events
      effect: read
      questions:
      - Is a Spanish company listed on the stock market according to CNMV?
      - What recent CNMV events have been published for a listed company?
      instructions:
      - text: Get the CNMV listing data for {company}.
        slots:
          company: path.slug
      - text: Show the last {limit} CNMV events for {company}.
        slots:
          limit: query.limit
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/aeat-moroso'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a company is on the AEAT debtor list
      effect: read
      questions:
      - Does a Spanish company appear on the tax agency's list of debtors?
      - Would an AEAT debtor-list mention mean the company still owes tax?
      instructions:
      - text: Check whether {company} is on the AEAT moroso list.
        slots:
          company: path.slug
      - text: Look up {company} in the Hacienda debtor list.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/wikidata'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's Wikidata metadata
      effect: read
      questions:
      - Can I get a company's Wikidata Q-id, ticker and founding date?
      - Which Wikidata fields are excluded from the company projection?
      instructions:
      - text: Get the Wikidata metadata for {company}.
        slots:
          company: path.slug
      - text: Find the Wikidata Q-id and ticker of {company}.
        slots:
          company: 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/company/{slug}/accounts'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's filed annual accounts metadata
      effect: read
      questions:
      - Can I see metadata about the annual accounts a company has filed?
      - Why is filed accounts metadata for a company currently unavailable?
      instructions:
      - text: Get the filed accounts metadata for {company}.
        slots:
          company: path.slug
      - text: Show the annual accounts filings of {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/geocode'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's geocoded location
      effect: read
      questions:
      - Can I get map coordinates for a company from its company record?
      - Why does the company geocode projection always return 503?
      instructions:
      - text: Get the geocode projection for {company}.
        slots:
          company: path.slug
      - text: Show where {company} is located on a map.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/activity'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's monthly registry activity
      effect: read
      questions:
      - How active has a company been in the registry month by month?
      - Can I get a monthly activity series for a sparkline chart?
      instructions:
      - text: Get the monthly registry activity for {company}.
        slots:
          company: path.slug
      - text: Build a sparkline of BORME activity counts for {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/score'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's documentary completeness score
      effect: read
      questions:
      - Is there a documentary completeness score for a company's public record?
      - Is the completeness score a credit or risk rating?
      instructions:
      - text: Get the documentary completeness score for {company}.
        slots:
          company: path.slug
      - text: Show how complete the public record of {company} is.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/similar'].get
  update:
    x-apievangelist-phrasing:
      intent: Find companies similar to a company
      effect: read
      questions:
      - Which companies are similar to a given company in the same province and sector?
      - How are similar companies ranked?
      instructions:
      - text: Find companies similar to {company}.
        slots:
          company: path.slug
      - text: Show {limit} peers of {company} in the same province and CNAE division.
        slots:
          limit: query.limit
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/embargoes'].get
  update:
    x-apievangelist-phrasing:
      intent: List embargo mentions for a company
      effect: read
      questions:
      - Has a Spanish company had assets seized or embargoed according to public registries?
      - Do embargo mentions certify that an embargo is still in force?
      instructions:
      - text: List the embargo and garnishment mentions for {company}.
        slots:
          company: path.slug
      - text: Check {company} for published embargoes de bienes.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/network'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's documentary network graph
      effect: read
      questions:
      - Can I get the documentary network graph around a company?
      - Why is the company network projection temporarily unavailable?
      instructions:
      - text: Get the documentary network for {company}.
        slots:
          company: path.slug
      - text: Map the network projection around {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/enrichment'].get
  update:
    x-apievangelist-phrasing:
      intent: Get authorized enrichment data for a company
      effect: read
      questions:
      - What enrichment data is available for a company from authorized public sources?
      - Does the enrichment payload include license and attribution for each source?
      instructions:
      - text: Get the enrichment payload for {company}.
        slots:
          company: path.slug
      - text: Show all licensed public-source enrichment for {company}.
        slots:
          company: path.slug
      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'
- target: $.paths['/api/v1/empresa/{slug}/informe-legal'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a redacted legal report on a company
      effect: write
      questions:
      - How do I order a legal report on a Spanish company with my credits?
      - Is personal data removed from the corporate legal report?
      - Will I be charged twice if I request the same company's legal report again the same day?
      instructions:
      - text: Generate the informe legal for {company} using CSRF token {csrf_token}.
        slots:
          company: path.slug
          csrf_token: header.X-CSRF-Token
      - text: Create a redacted corporate legal report on {company}.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/trust-score'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's trust score
      effect: read
      questions:
      - What is OpenMercantil's trust score for a company?
      - Which signals are combined into a company's trust score?
      instructions:
      - text: Get the trust score for {company}.
        slots:
          company: path.slug
      - text: Show how trustworthy {company} rates on the combined signals.
        slots:
          company: path.slug
      method: generated
      generated: '2026-09-26'