# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drip Runs API
  version: 1.0.0
extends: openapi/drippay-runs-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: 8
- target: $.paths['/v1/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List agent runs with filters
      effect: read
      questions:
      - Which agent runs has a given customer had this week?
      - Can I filter my agent runs by workflow and status?
      - How do I see all failed runs between two dates in Drip?
      instructions:
      - text: List agent runs for customer {customerId}.
        slots:
          customerId: query.customerId
      - text: Show the last {limit} runs of workflow {workflowId} with status {status}.
        slots:
          limit: query.limit
          workflowId: query.workflowId
          status: query.status
      - text: List runs started between {from} and {to}.
        slots:
          from: query.from
          to: query.to
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Start tracking a new agent run
      effect: write
      questions:
      - How do I begin tracking an agent run for a customer's workflow?
      - What status does a new run start in before any events arrive?
      - Can I link a new run to a parent run or my own run ID?
      instructions:
      - text: Start a new run of workflow {workflowId} for customer {customerId}.
        slots:
          workflowId: requestBody.workflowId
          customerId: requestBody.customerId
      - text: Open a run for customer {customerId} on workflow {workflowId} as a child of run {parentRunId}.
        slots:
          customerId: requestBody.customerId
          workflowId: requestBody.workflowId
          parentRunId: requestBody.parentRunId
      - text: Start run {externalRunId} from my system for customer {customerId} on workflow {workflowId}.
        slots:
          externalRunId: requestBody.externalRunId
          customerId: requestBody.customerId
          workflowId: requestBody.workflowId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/runs/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a run's metadata and summary totals
      effect: read
      questions:
      - What are the summary totals for one specific agent run?
      - Can I look up a single run's status and metadata by its ID?
      instructions:
      - text: Get the details and totals for run {id}.
        slots:
          id: path.id
      - text: Show me the status of run {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/runs/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a run's status or end it
      effect: write
      questions:
      - How do I mark an agent run as completed or failed?
      - Is the duration computed automatically when a run ends?
      - Can I cancel a run that timed out on my side?
      instructions:
      - text: End run {id} as completed.
        slots:
          id: path.id
      - text: Mark run {id} as failed.
        slots:
          id: path.id
      - text: Change the status of run {id} to cancelled.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/runs/{id}/timeline'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a run's full event timeline for debugging
      effect: read
      questions:
      - What exactly happened step by step during an agent run?
      - Can I see retry chains and anomalies detected in a run's events?
      - Is there a way to collapse retries when paging through a long run history?
      instructions:
      - text: Show the event timeline for run {id} with includeAnomalies set to {includeAnomalies}.
        slots:
          id: path.id
          includeAnomalies: query.includeAnomalies
      - text: Page through run {id}'s timeline from cursor {cursor}, {limit} events at a time.
        slots:
          id: path.id
          cursor: query.cursor
          limit: query.limit
      - text: Debug run {id} with retries collapsed set to {collapseRetries}.
        slots:
          id: path.id
          collapseRetries: query.collapseRetries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/run-events'].post
  update:
    x-apievangelist-phrasing:
      intent: Emit a single event to a run (legacy)
      effect: write
      questions:
      - How do I send one usage event to a run through the legacy run-events endpoint?
      - Does the older single run-event call create a charge or only record it for debugging?
      instructions:
      - text: Emit one event to a run using the legacy single run-event endpoint.
      - text: Record a single idempotent step event on my agent run for debugging.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/run-events/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Emit a batch of events to runs (legacy)
      effect: write
      questions:
      - Can I send many run events in one request with the legacy batch endpoint?
      - What happens to a batched event that has no run ID attached?
      instructions:
      - text: Send this batch of events to their runs in one legacy batch call.
      - text: Batch-emit these events, each with its own run, customer and workflow.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/runs/record'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a complete run in one call
      effect: write
      questions:
      - Is there a single call that starts a run, adds its events and ends it?
      - Will a workflow be auto-created if I record a run with a new slug?
      - Can I record a finished run with its failure code and error message at once?
      instructions:
      - text: Record a finished run of workflow {workflow} for customer {customerId} with status {status}.
        slots:
          workflow: requestBody.workflow
          customerId: requestBody.customerId
          status: requestBody.status
      - text: Record a failed run of {workflow} for customer {customerId} with status {status} and error {errorMessage}.
        slots:
          workflow: requestBody.workflow
          customerId: requestBody.customerId
          status: requestBody.status
          errorMessage: requestBody.errorMessage
      - text: Log a complete run for customer {customerId} on {workflow}, status {status}, with events {events}.
        slots:
          customerId: requestBody.customerId
          workflow: requestBody.workflow
          status: requestBody.status
          events: requestBody.events
      method: generated
      generated: '2026-09-26'