API Evangelist conversational phrasing for Snowflake Task API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Snowflake Task API
  version: 1.0.0
extends: openapi/snowflake-task-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: 16
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tasks in a schema
      effect: read
      questions:
      - Which scheduled tasks are defined in this schema?
      - Can I see every task in a schema along with its state?
      instructions:
      - text: List all tasks in schema {schema} of database {database}.
        slots:
          database: path.database
          schema: path.schema
      - text: Show me the scheduled tasks defined here.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a scheduled task
      effect: write
      questions:
      - How do I schedule a SQL statement to run on a cron schedule?
      - Can a new task run after another task finishes instead of on a timer?
      - What must I provide when creating a task besides its name?
      instructions:
      - text: Create task {name} that runs {definition} on schedule {schedule}.
        slots:
          name: requestBody.name
          definition: requestBody.definition
          schedule: requestBody.schedule
      - text: Create task {name} running {definition} on warehouse {warehouse}.
        slots:
          name: requestBody.name
          definition: requestBody.definition
          warehouse: requestBody.warehouse
      - text: Create task {name} executing {definition} after predecessors {predecessors} complete.
        slots:
          name: requestBody.name
          definition: requestBody.definition
          predecessors: requestBody.predecessors
      - text: In {database}.{schema}, create task {name} that runs {definition}.
        slots:
          database: path.database
          schema: path.schema
          name: requestBody.name
          definition: requestBody.definition
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe a single task
      effect: read
      questions:
      - What schedule, warehouse and SQL does this task use?
      - Can I see the full definition of one task?
      instructions:
      - text: Describe task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Fetch this task's definition and state.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or alter a task with a full definition
      effect: write
      questions:
      - Can I change an existing task's schedule by resending its whole definition?
      - Do I need to pass every task property even for a small alter?
      instructions:
      - text: Create or update task {name} so it runs {definition} on {schedule}.
        slots:
          name: requestBody.name
          definition: requestBody.definition
          schedule: requestBody.schedule
      - text: Alter task {name} to retry {task_auto_retry_attempts} times, keeping its SQL {definition}.
        slots:
          name: requestBody.name
          task_auto_retry_attempts: requestBody.task_auto_retry_attempts
          definition: requestBody.definition
      - text: Create or replace task {task} in {database}.{schema} with the SQL {definition}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
          definition: requestBody.definition
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Drop a task
      effect: destructive
      questions:
      - How do I drop a task I no longer want scheduled?
      - Will deleting a task fail if it doesn't exist?
      instructions:
      - text: Drop task {task} from {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Delete the task I named from its schema.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}:execute'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a task immediately
      effect: write
      questions:
      - Can I trigger a task right now without waiting for its schedule?
      - Is there a way to rerun only the failed part of the last task graph run?
      instructions:
      - text: Execute task {task} in {database}.{schema} immediately.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Rerun this task, retrying the last failed run ({retryLast}).
        slots:
          retryLast: query.retryLast
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}:resume'].post
  update:
    x-apievangelist-phrasing:
      intent: Resume a suspended task
      effect: write
      questions:
      - How do I restart a task that is currently suspended?
      - Does a new task need to be resumed before it starts running on schedule?
      instructions:
      - text: Resume suspended task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Turn the task I named back on so it follows its schedule.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}:suspend'].post
  update:
    x-apievangelist-phrasing:
      intent: Suspend a running task
      effect: write
      questions:
      - Can I pause a task so it stops firing on its schedule?
      - What's the way to temporarily stop a task without dropping it?
      instructions:
      - text: Suspend task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Pause the task I named until I resume it.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}/dependents'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tasks that depend on a task
      effect: read
      questions:
      - Which child tasks run after this task in the graph?
      - Can I get every downstream task recursively, not just direct children?
      instructions:
      - text: List the dependent tasks of {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Show all downstream tasks of this task, recursively ({recursive}).
        slots:
          recursive: query.recursive
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}/current_graphs'].get
  update:
    x-apievangelist-phrasing:
      intent: Get running or upcoming graph runs (legacy)
      effect: read
      questions:
      - Is there an older current_graphs endpoint with an underscore path?
      - What does the legacy call for scheduled graph runs return?
      instructions:
      - text: Use the legacy current_graphs endpoint for task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Call the deprecated current_graphs route, capped at {resultLimit} runs.
        slots:
          resultLimit: query.resultLimit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}/current-graphs'].get
  update:
    x-apievangelist-phrasing:
      intent: Get running and upcoming task graph runs
      effect: read
      questions:
      - Which runs of this task graph are executing now or scheduled over the next 8 days?
      - Can I limit how many upcoming graph runs come back?
      instructions:
      - text: Show graph runs executing or scheduled soon for task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: List up to {resultLimit} current and upcoming graph runs for this task.
        slots:
          resultLimit: query.resultLimit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}/complete_graphs'].get
  update:
    x-apievangelist-phrasing:
      intent: Get completed graph runs (legacy)
      effect: read
      questions:
      - Is there an older complete_graphs endpoint with an underscore path?
      - Does the legacy completed-runs call still filter to errors only?
      instructions:
      - text: Use the legacy complete_graphs endpoint for task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Call the deprecated complete_graphs route with errorOnly set to {errorOnly}.
        slots:
          errorOnly: query.errorOnly
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}/complete-graphs'].get
  update:
    x-apievangelist-phrasing:
      intent: Get completed task graph runs
      effect: read
      questions:
      - Did the recent runs of this task graph succeed or fail?
      - Can I see only the completed graph runs that ended in an error?
      instructions:
      - text: Show the completed graph runs of task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: 'List the last {resultLimit} finished graph runs for this task, errors only: {errorOnly}.'
        slots:
          resultLimit: query.resultLimit
          errorOnly: query.errorOnly
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}:set-tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Set tags on a task
      effect: write
      questions:
      - How do I attach tags to a scheduled task?
      - Can I label a task with an owner or cost-center tag?
      instructions:
      - text: Set tags on task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Apply my tag assignments to the task I named.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}:unset-tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove tags from a task
      effect: write
      questions:
      - Can I remove tags from a task?
      - What's the way to clear a tag off a scheduled task?
      instructions:
      - text: Unset the tags on task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: Remove the tag assignments from the task I named.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/databases/{database}/schemas/{schema}/tasks/{name}:get-tags'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the tags assigned to a task
      effect: read
      questions:
      - Which tags are assigned to this task?
      - Do I need a running warehouse to read a task's tags?
      instructions:
      - text: Show every tag assigned to task {task} in {database}.{schema}.
        slots:
          database: path.database
          schema: path.schema
          task: path.name
      - text: List the tag assignments on the task I named.
      method: generated
      generated: '2026-10-01'