# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Live Direct Marketing Online Site Enrichment API
  version: 1.0.0
extends: openapi/live-direct-marketing-online-site-enrichment-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: 19
- target: $.paths['/api/site-enrichment/detect-forms'].post
  update:
    x-apievangelist-phrasing:
      intent: Detect contact forms in page HTML
      effect: read
      questions:
      - Can I check whether a web page has a contact-us form from its HTML?
      - Does form detection ignore search, login and newsletter forms?
      instructions:
      - text: 'Detect forms in this HTML: {html}.'
        slots:
          html: requestBody.html
      - text: Check whether page {url} has a contact form, using its HTML {html}.
        slots:
          url: requestBody.pageUrl
          html: requestBody.html
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List site-crawl tasks
      effect: read
      questions:
      - Which website crawl tasks have I run, and which are still going?
      - Can I list crawls that were launched without a scoring task?
      instructions:
      - text: List site-crawl tasks with status {status} for scoring task {scoring}, owned={owned}, page {page} of {size}.
        slots:
          status: query.status
          scoring: query.scoringTaskId
          owned: query.owned
          page: query.page
          size: query.pageSize
      - text: Show my {status} site-enrichment crawls, page {page}, {size} per page, scoring task {scoring}, owned {owned}.
        slots:
          status: query.status
          scoring: query.scoringTaskId
          owned: query.owned
          page: query.page
          size: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a website crawl to enrich companies
      effect: write
      questions:
      - How do I crawl my companies' websites to collect contact details?
      - Can I limit a site crawl to one company list and cap how many sites it visits?
      instructions:
      - text: Crawl the websites of companies in list {list}, up to {limit} sites.
        slots:
          list: requestBody.listId
          limit: requestBody.limit
      - text: Enqueue a site crawl for companies {companies} and save screenshots.
        slots:
          companies: requestBody.companyIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/preview'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview a list's crawl coverage
      effect: read
      questions:
      - Before crawling, how many companies in my list actually have a website filled in?
      - Can I see unique domain counts for a list without starting a crawl?
      instructions:
      - text: Preview crawl coverage of list {list} using domain field {field}.
        slots:
          list: query.listId
          field: query.domainField
      - text: Count unique domains in list {list} field {field} without starting a crawl.
        slots:
          list: query.listId
          field: query.domainField
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a site-crawl task's status
      effect: read
      questions:
      - Is my website crawl finished yet?
      - Where do I see the progress counters of one crawl task?
      instructions:
      - text: Show the status of site-crawl task {id}.
        slots:
          id: path.id
      - text: Report how far along crawl {id} is.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a crawl task's event log
      effect: read
      questions:
      - Can I follow the state transitions of a crawl task as they happen?
      - How do I fetch only the crawl journal events newer than the last one I saw?
      instructions:
      - text: Show the event log for crawl task {id} after sequence {cursor}.
        slots:
          id: path.id
          cursor: query.cursor
      - text: Get new journal entries of crawl {id} since cursor {cursor}.
        slots:
          id: path.id
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/events'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an agent note to a crawl journal
      effect: write
      questions:
      - Can an agent leave a note in a crawl task's journal?
      - Who is recorded as the author when I post a note to a crawl task?
      instructions:
      - text: Add the note {text} to crawl task {id}'s journal.
        slots:
          id: path.id
          text: requestBody.text
      - text: Log agent note {text} on site-crawl {id}.
        slots:
          id: path.id
          text: requestBody.text
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/reason-summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize why crawl sites failed
      effect: read
      questions:
      - Why did sites fail in my crawl task, grouped by reason?
      - What are the most common failure reasons in a website crawl?
      instructions:
      - text: Summarize failure reasons for crawl task {id}.
        slots:
          id: path.id
      - text: Group the failed sites in crawl {id} by reason.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a crawl task's funnel and results
      effect: read
      questions:
      - How many emails and phones did my website crawl collect?
      - Can I see a crawl's funnel with companies and domains counted separately?
      instructions:
      - text: Show the unified statistics for crawl task {id}.
        slots:
          id: path.id
      - text: Give me the funnel and collected-data counts of crawl {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List a crawl task's per-site results
      effect: read
      questions:
      - Which sites in my crawl were down, empty or behind a captcha?
      - Can I filter crawl results by outcome or reason code?
      instructions:
      - text: List items of crawl {id} with outcome {status} and reason {reason}, page {page} of {size}.
        slots:
          id: path.id
          status: query.status
          reason: query.reasonCode
          page: query.page
          size: query.pageSize
      - text: Show {status} sites in crawl task {id} for reason code {reason}, page {page}, {size} per page.
        slots:
          id: path.id
          status: query.status
          reason: query.reasonCode
          page: query.page
          size: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/raw'].get
  update:
    x-apievangelist-phrasing:
      intent: Get raw crawled page text for a company
      effect: read
      questions:
      - Can I see the raw page text a crawl captured for one company before extraction?
      - Why might the raw crawl snapshot for a company come back empty?
      instructions:
      - text: Show the raw visited page text for company {company} in crawl {id}.
        slots:
          id: path.id
          company: query.companyId
      - text: Get the diagnostic snapshot of company {company}'s homepage from crawl task {id}.
        slots:
          id: path.id
          company: query.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a site-crawl task
      effect: destructive
      questions:
      - How do I stop a website crawl for good?
      - Can a cancelled crawl be retried later?
      instructions:
      - text: Cancel site-crawl task {id}.
        slots:
          id: path.id
      - text: Stop crawl {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/pause'].post
  update:
    x-apievangelist-phrasing:
      intent: Pause a site-crawl task
      effect: write
      questions:
      - Can I pause a website crawl and pick it up later?
      - Does pausing a crawl end it?
      instructions:
      - text: Pause crawl task {id}.
        slots:
          id: path.id
      - text: Put site crawl {id} on hold.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/resume'].post
  update:
    x-apievangelist-phrasing:
      intent: Resume a paused site crawl
      effect: write
      questions:
      - How do I continue a crawl I paused earlier?
      - Will resuming a crawl pick up where it stopped?
      instructions:
      - text: Resume crawl task {id}.
        slots:
          id: path.id
      - text: Restart paused site crawl {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/tasks/{id}/retry'].post
  update:
    x-apievangelist-phrasing:
      intent: Retry failed companies in a finished crawl
      effect: write
      questions:
      - Can I re-crawl only the companies that failed in a finished task?
      - Which crawl statuses allow a retry of not-OK companies?
      instructions:
      - text: Retry the failed companies in crawl task {id}.
        slots:
          id: path.id
      - text: Re-run the not-OK sites of finished crawl {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/backlog/stale-http-status'].get
  update:
    x-apievangelist-phrasing:
      intent: Count cards missing a crawl HTTP code
      effect: read
      questions:
      - How many companies are marked site OK but have no real HTTP status recorded?
      - Can I list company cards whose site check needs backfilling?
      instructions:
      - text: Count cards marked site OK without an HTTP code, returning up to {limit} ids.
        slots:
          limit: query.limit
      - text: Show up to {limit} companies in the stale site-status backlog.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/backlog/stale-http-status/requeue'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-crawl the stale site-status backlog
      effect: write
      questions:
      - Can I re-crawl the companies that are missing a recorded HTTP status in batches?
      - What's the maximum batch size for re-crawling the stale OK backlog?
      instructions:
      - text: Re-crawl {size} cards from the stale HTTP-status backlog.
        slots:
          size: query.batchSize
      - text: Requeue a batch of {size} site-OK cards lacking an HTTP code.
        slots:
          size: query.batchSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/backlog/down-wait-timeout'].get
  update:
    x-apievangelist-phrasing:
      intent: Count sites down from our own timeouts
      effect: read
      questions:
      - How many companies were marked site down because of a crawler timeout rather than the site itself?
      - Can I list cards in the down wait-timeout backlog?
      instructions:
      - text: Count cards marked down from a wait timeout, up to {limit} ids.
        slots:
          limit: query.limit
      - text: Show up to {limit} companies in the down-wait-timeout backlog.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/site-enrichment/backlog/down-wait-timeout/requeue'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-crawl sites marked down by timeouts
      effect: write
      questions:
      - Can I re-crawl the sites that were wrongly marked down by a crawler timeout?
      - How many down-backlog cards can I requeue in one batch?
      instructions:
      - text: Re-crawl {size} cards from the down wait-timeout backlog.
        slots:
          size: query.batchSize
      - text: Requeue a batch of {size} timed-out down sites.
        slots:
          size: query.batchSize
      method: generated
      generated: '2026-10-01'