# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for NERD Service Annotations Async API
  version: 1.0.0
extends: openapi/sp-global-annotations-async-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: 4
- target: $.paths['/api/v1/annotations-async'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch results of an entity annotation job
      effect: read
      questions:
      - Where can I pick up the entity annotations once my NERD job finishes?
      - Can I check whether an asynchronous annotation job is still running or done?
      instructions:
      - text: Get the annotation results for NERD job {job_id}.
        slots:
          job_id: query.job_id
      - text: Check the status and entities found for annotation job {job_id}.
        slots:
          job_id: query.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/annotations-async'].put
  update:
    x-apievangelist-phrasing:
      intent: Start annotating an uploaded text file
      effect: write
      questions:
      - I uploaded a text file through an upload URL - how do I tell NERD to start annotating it?
      - Can I kick off annotation for a file I already uploaded using its job ID?
      instructions:
      - text: Start the annotation job for uploaded file job {job_id} against the {knowledge_bases} knowledge bases.
        slots:
          job_id: query.job_id
          knowledge_bases: requestBody.knowledge_bases
      - text: Begin annotating uploaded job {job_id} with people tagging set to {tag_people}.
        slots:
          job_id: query.job_id
          tag_people: requestBody.tag_people
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/annotations-async'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit text for asynchronous entity annotation
      effect: write
      questions:
      - How do I send a document's text to NERD and have entities linked to Capital IQ or Wikimedia?
      - Can I submit raw text for named entity recognition and get the results later?
      - Which knowledge bases can annotations be disambiguated against?
      instructions:
      - text: 'Submit this text for annotation against Capital IQ: {text}'
        slots:
          text: requestBody.text
      - text: Start an async annotation job on {text} using knowledge bases {knowledge_bases}.
        slots:
          text: requestBody.text
          knowledge_bases: requestBody.knowledge_bases
      - text: Annotate {text} as a document issued by company {originating_entity_id}.
        slots:
          text: requestBody.text
          originating_entity_id: requestBody.originating_entity_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/annotations-async'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete the results of an annotation job
      effect: destructive
      questions:
      - Can I remove stored annotation results after I've downloaded them?
      - How do I clean up a finished NERD annotation job?
      instructions:
      - text: Delete the annotation results for job {job_id}.
        slots:
          job_id: query.job_id
      - text: Purge everything stored for NERD job {job_id}.
        slots:
          job_id: query.job_id
      method: generated
      generated: '2026-10-01'