# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenMercantil BORME API
  version: 1.0.0
extends: openapi/openmercantil-borme-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: 6
- 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 page through the BORME registry events published about one Spanish company?
      - Can I filter a company's registry events to a single calendar year?
      - How far back do the BORME events for a company go?
      instructions:
      - text: List the BORME events for company {slug}.
        slots:
          slug: path.slug
      - text: Show the BORME events for {slug} published in {year}.
        slots:
          slug: path.slug
          year: query.year
      - text: Get page {page} of {slug}'s registry events, {page_size} per page.
        slots:
          page: query.page
          slug: path.slug
          page_size: query.page_size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/timeline'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's multi-source timeline
      effect: read
      questions:
      - Can I see one chronological timeline for a company combining BORME acts and public procurement records?
      - Does the unified company timeline include public grants data?
      instructions:
      - text: Build the unified chronological timeline for {slug} from BORME and procurement records.
        slots:
          slug: path.slug
      - text: Show me the combined registry and PLACSP timeline for company {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/daily/{date}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the BORME daily summary grouped by province
      effect: read
      questions:
      - Which BORME acts were published on a given day, broken down by province and act type?
      - How do I get the official BORME bulletin summary for one publication date?
      instructions:
      - text: Get the BORME summary for {date} grouped by province and act type.
        slots:
          date: path.date
      - text: Show the acts in the official BORME bulletin of {date}.
        slots:
          date: path.date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/summary/date/{date}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a BORME daily summary via the legacy route
      effect: read
      questions:
      - Does the old summary/date route still return the BORME daily summary?
      - What does the deprecated daily-summary alias return for a publication date?
      instructions:
      - text: Fetch the BORME daily summary for {date} through the deprecated summary/date alias.
        slots:
          date: path.date
      - text: Call the legacy summary route for {date} so my older client keeps working.
        slots:
          date: path.date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/empresa/{slug}/facts'].get
  update:
    x-apievangelist-phrasing:
      intent: Get structured BORME facts for a company
      effect: read
      questions:
      - Which appointments, removals and capital changes has BORME published for a company?
      - Can I get a company's registry facts grouped by type instead of as raw events?
      instructions:
      - text: Get the extracted BORME facts for empresa {slug}, grouped by type.
        slots:
          slug: path.slug
      - text: Show up to {limit} facts about appointments and capital changes for {slug}.
        slots:
          limit: query.limit
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/company/{slug}/facts'].get
  update:
    x-apievangelist-phrasing:
      intent: Get company BORME facts via the legacy English route
      effect: read
      questions:
      - Is the old English company/facts route still available for extracted BORME facts?
      - What replaced the deprecated company facts alias?
      instructions:
      - text: Fetch BORME facts for {slug} through the deprecated English company/facts alias.
        slots:
          slug: path.slug
      - text: Use the legacy company facts route to return {limit} facts for {slug}.
        slots:
          limit: query.limit
          slug: path.slug
      method: generated
      generated: '2026-09-26'