API Evangelist conversational phrasing for Crawler API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Crawler API
  version: 1.0.0
extends: openapi/algolia-crawler-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: 20
- target: $.paths['/1/crawlers'].get
  update:
    x-apievangelist-phrasing:
      intent: List crawlers
      effect: read
      questions:
      - Which website crawlers do I have set up?
      - Can I find a crawler by its name?
      instructions:
      - text: List all my crawlers.
      - text: Find crawlers named {name}.
        slots:
          name: query.name
      - text: List the crawlers belonging to application {appID}.
        slots:
          appID: query.appID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a website crawler
      effect: write
      questions:
      - How do I set up a new crawler to index my website?
      - What configuration does a new crawler need?
      instructions:
      - text: Create a crawler called {name} with configuration {config}.
        slots:
          name: requestBody.name
          config: requestBody.config
      - text: 'Set up a new site crawler {name} using this config: {config}.'
        slots:
          name: requestBody.name
          config: requestBody.config
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a crawler's details
      effect: read
      questions:
      - How can I check the state of one crawler, such as whether it's running or blocked?
      - Can I get a crawler's details along with its full configuration?
      instructions:
      - text: Get the details of crawler {id}.
        slots:
          id: path.id
      - text: Show crawler {id} including its configuration.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a crawler
      effect: destructive
      questions:
      - How do I permanently remove a crawler I no longer use?
      - Can I delete a website crawler entirely?
      instructions:
      - text: Delete crawler {id}.
        slots:
          id: path.id
      - text: Permanently remove the crawler {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a crawler or replace its configuration
      effect: write
      questions:
      - How do I rename a crawler?
      - Is there a way to overwrite a crawler's whole configuration without creating a new version?
      instructions:
      - text: Rename crawler {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Replace crawler {id}'s entire configuration with {config}, unversioned.
        slots:
          id: path.id
          config: requestBody.config
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/run'].post
  update:
    x-apievangelist-phrasing:
      intent: Unpause a crawler
      effect: write
      questions:
      - How do I resume a crawler I paused?
      - Will unpausing a crawler continue the crawl that was in progress?
      instructions:
      - text: Unpause crawler {id}.
        slots:
          id: path.id
      - text: Resume the paused crawler {id} so it runs on schedule again.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/pause'].post
  update:
    x-apievangelist-phrasing:
      intent: Pause a crawler
      effect: write
      questions:
      - How can I temporarily stop a crawler from running?
      - Can I put a crawler on hold while I fix my site?
      instructions:
      - text: Pause crawler {id}.
        slots:
          id: path.id
      - text: Put crawler {id} on hold.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/reindex'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a full crawl
      effect: write
      questions:
      - How do I trigger a full recrawl of my website right now?
      - Can I kick off a crawl without waiting for the schedule?
      instructions:
      - text: Start a crawl with crawler {id}.
        slots:
          id: path.id
      - text: Reindex the whole site now using crawler {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/test'].post
  update:
    x-apievangelist-phrasing:
      intent: Test crawl a single URL
      effect: read
      questions:
      - How can I preview which records a crawler would extract from a page?
      - Can I try a configuration change on one URL before saving it?
      instructions:
      - text: Test crawl {url} with crawler {id}.
        slots:
          url: requestBody.url
          id: path.id
      - text: Preview records extracted from {url} by crawler {id} using override config {config}.
        slots:
          url: requestBody.url
          id: path.id
          config: requestBody.config
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/urls/crawl'].post
  update:
    x-apievangelist-phrasing:
      intent: Crawl specific URLs and index them
      effect: write
      questions:
      - How do I recrawl just a handful of pages that changed?
      - What's the rate limit on crawling individual URLs?
      instructions:
      - text: 'Crawl these URLs with crawler {id}: {urls}.'
        slots:
          id: path.id
          urls: requestBody.urls
      - text: Recrawl {urls} using crawler {id} and add them to its extra URLs.
        slots:
          urls: requestBody.urls
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/stats/urls'].get
  update:
    x-apievangelist-phrasing:
      intent: Get crawled, skipped and failed URL counts
      effect: read
      questions:
      - How many URLs did my crawler fail on or skip?
      - What are the URL statistics for a crawler?
      instructions:
      - text: Get URL stats for crawler {id}.
        slots:
          id: path.id
      - text: Show how many pages crawler {id} crawled, skipped and failed.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/crawl_runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List a crawler's past runs
      effect: read
      questions:
      - Where can I see the history of crawl runs for troubleshooting?
      - Can I list only the failed crawl runs in a date range?
      instructions:
      - text: List crawl runs for crawler {id}.
        slots:
          id: path.id
      - text: Show crawler {id}'s runs with status {status} between {from} and {until}.
        slots:
          id: path.id
          status: query.status
          from: query.from
          until: query.until
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/{logId}/download'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the log file for a crawl run
      effect: read
      questions:
      - How do I download the detailed log of a particular crawl run?
      - Can I get the log file to debug why pages were missed in one run?
      instructions:
      - text: Download log {logId} for crawler {id}.
        slots:
          logId: path.logId
          id: path.id
      - text: Fetch the crawl run file {logId} from crawler {id}.
        slots:
          logId: path.logId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/delete_runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a crawler's run log records
      effect: destructive
      questions:
      - How can I clear the crawl run logs without deleting the crawler?
      - Can I remove old crawl run records?
      instructions:
      - text: Delete the crawl run records for crawler {id}.
        slots:
          id: path.id
      - text: Clear the run logs of crawler {id} but keep the crawler.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/config'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a crawler's configuration (versioned)
      effect: write
      questions:
      - How do I change a crawler's start URLs or schedule and keep a version history?
      - Can I update the rate limit or exclusion patterns on my crawler?
      instructions:
      - text: Update crawler {id}'s config with actions {actions}, app {appId} and rate limit {rateLimit}.
        slots:
          id: path.id
          actions: requestBody.actions
          appId: requestBody.appId
          rateLimit: requestBody.rateLimit
      - text: Set crawler {id} to start from {startUrls} on schedule {schedule}.
        slots:
          id: path.id
          startUrls: requestBody.startUrls
          schedule: requestBody.schedule
      - text: Add exclusion patterns {exclusionPatterns} to crawler {id}'s configuration.
        slots:
          exclusionPatterns: requestBody.exclusionPatterns
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/config/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a crawler's configuration versions
      effect: read
      questions:
      - Who changed my crawler's configuration and when?
      - Can I see previous versions of a crawler's config?
      instructions:
      - text: List configuration versions for crawler {id}.
        slots:
          id: path.id
      - text: Show the config change history of crawler {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/config/versions/{version}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a specific crawler configuration version
      effect: read
      questions:
      - How do I look at an older crawler configuration so I can restore it?
      - What did version 3 of my crawler config contain?
      instructions:
      - text: Get configuration version {version} of crawler {id}.
        slots:
          version: path.version
          id: path.id
      - text: Show me crawler {id}'s config as of version {version}.
        slots:
          id: path.id
          version: path.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/tasks/{taskID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a crawler task's status
      effect: read
      questions:
      - Is my crawler task still pending or completed?
      - How do I check on a task a crawler action created?
      instructions:
      - text: Check the status of task {taskID} on crawler {id}.
        slots:
          taskID: path.taskID
          id: path.id
      - text: Tell me whether crawler {id}'s task {taskID} has finished.
        slots:
          id: path.id
          taskID: path.taskID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/crawlers/{id}/tasks/{taskID}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a task that is blocking a crawler
      effect: destructive
      questions:
      - My crawler is blocked by an errored task. How do I unblock it?
      - Can I cancel a failing task so the crawler's schedule resumes?
      instructions:
      - text: Cancel blocking task {taskID} on crawler {id}.
        slots:
          taskID: path.taskID
          id: path.id
      - text: Unblock crawler {id} by cancelling its errored task {taskID}.
        slots:
          id: path.id
          taskID: path.taskID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/domains'].get
  update:
    x-apievangelist-phrasing:
      intent: List registered crawler domains
      effect: read
      questions:
      - Which domains are registered so my crawlers are allowed to run on them?
      - Why won't my crawler run on a URL, and is its domain registered?
      instructions:
      - text: List my registered crawler domains.
      - text: Show the registered domains for application {appID}.
        slots:
          appID: query.appID
      method: generated
      generated: '2026-09-26'