API Evangelist conversational phrasing for OpenSanctions Data access API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenSanctions Data access API
  version: 1.0.0
extends: openapi/opensanctions-data-access-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/entities/{entity_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a sanctioned person or company by ID
      effect: read
      questions:
      - How do I pull the full OpenSanctions record for one entity when I already have its ID?
      - Does a single entity record include its passports, sanctions and associates nested inside?
      - What happens if the entity ID I stored was merged into another canonical entity?
      instructions:
      - text: Fetch the full entity record for {entity_id}, with data from every dataset.
        slots:
          entity_id: path.entity_id
      - text: Get entity {entity_id} without nested adjacent entities by setting nested to {nested}.
        slots:
          entity_id: path.entity_id
          nested: query.nested
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/{entity_id}/adjacent'].get
  update:
    x-apievangelist-phrasing:
      intent: Page through everything linked to an entity
      effect: read
      questions:
      - Can I page through all the passports, sanctions and associates linked to an entity when there are too many to load at once?
      - Which records are connected to a given sanctions entity across every relationship type?
      instructions:
      - text: List all adjacent entities connected to {entity_id}, across every property.
        slots:
          entity_id: path.entity_id
      - text: Show the next {limit} linked entities for {entity_id} starting at offset {offset}.
        slots:
          entity_id: path.entity_id
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/{entity_id}/adjacent/{property_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: List an entity's links for one property
      effect: read
      questions:
      - Is there a way to get only the sanctions attached to an entity, rather than every linked record?
      - Can I paginate the related entities for one specific property, like associates or ownership?
      instructions:
      - text: Get the entities linked to {entity_id} through the {property_name} property only.
        slots:
          entity_id: path.entity_id
          property_name: path.property_name
      - text: Page through {limit} of the {property_name} links for {entity_id}, sorted by {sort}.
        slots:
          limit: query.limit
          property_name: path.property_name
          entity_id: path.entity_id
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/catalog'].get
  update:
    x-apievangelist-phrasing:
      intent: List the datasets the service indexes
      effect: read
      questions:
      - Which sanctions and PEP datasets are loaded into this yente instance?
      - How often is each data source configured to reload in the service manifest?
      instructions:
      - text: Show me the data catalog with every indexed dataset.
      - text: Pull the service manifest so I can see which data sources are included.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/statements'].get
  update:
    x-apievangelist-phrasing:
      intent: Query raw statement-level entity data
      effect: read
      questions:
      - Where can I see the raw statements behind an entity, including which dataset asserted each property value?
      - Can I search the statement records for a specific property value, like a particular birth date?
      - Does reading raw statements cost anything beyond needing a valid API key?
      instructions:
      - text: List the raw statements for canonical entity {canonical_id}.
        slots:
          canonical_id: query.canonical_id
      - text: Find statements in dataset {dataset} where property {prop} equals {value}.
        slots:
          dataset: query.dataset
          prop: query.prop
          value: query.value
      - text: Show the source statements recorded for entity {entity_id}, {limit} at a time.
        slots:
          entity_id: query.entity_id
          limit: query.limit
      method: generated
      generated: '2026-10-01'