# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenAI Responses API
  version: 1.0.0
extends: openapi/openai-responses-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: 7
- target: $.paths['/responses'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a model response
      effect: write
      questions:
      - How do I send a prompt to a model and get text or JSON back?
      - Can the model call tools like web search or my own functions while answering?
      - Can I continue a previous answer by pointing at its response ID?
      instructions:
      - text: Ask {model} to respond to {input}.
        slots:
          model: requestBody.model
          input: requestBody.input
      - text: Generate a response to {input} that follows up on response {previous_response_id}.
        slots:
          input: requestBody.input
          previous_response_id: requestBody.previous_response_id
      - text: Run {input} through {model} in the background with instructions {instructions}.
        slots:
          input: requestBody.input
          model: requestBody.model
          instructions: requestBody.instructions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/responses/{response_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a model response
      effect: read
      questions:
      - Can I fetch the output of a response I generated earlier by its ID?
      - Is my background response finished yet?
      instructions:
      - text: Get response {response_id}.
        slots:
          response_id: path.response_id
      - text: Check whether background response {response_id} has completed and show its output.
        slots:
          response_id: path.response_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/responses/{response_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a stored model response
      effect: destructive
      questions:
      - How do I delete a stored response so it's no longer kept?
      - Can I remove a model response by its ID?
      instructions:
      - text: Delete response {response_id}.
        slots:
          response_id: path.response_id
      - text: Remove the stored model response {response_id}.
        slots:
          response_id: path.response_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/responses/{response_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a background response
      effect: destructive
      questions:
      - Can I stop a background response that is still generating?
      - Which responses are eligible to be cancelled?
      instructions:
      - text: Cancel background response {response_id}.
        slots:
          response_id: path.response_id
      - text: Stop the still-running response {response_id}.
        slots:
          response_id: path.response_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/responses/{response_id}/input_items'].get
  update:
    x-apievangelist-phrasing:
      intent: List the input items of a response
      effect: read
      questions:
      - What inputs were sent to the model to produce a given response?
      - Can I page through the input items behind a response?
      instructions:
      - text: List the input items for response {response_id}.
        slots:
          response_id: path.response_id
      - text: Show the first {limit} inputs that went into response {response_id}.
        slots:
          limit: query.limit
          response_id: path.response_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/responses/input_tokens'].post
  update:
    x-apievangelist-phrasing:
      intent: Count input tokens before sending a request
      effect: read
      questions:
      - How many input tokens will my prompt use before I actually run it?
      - Can I estimate token usage including my tools and instructions?
      instructions:
      - text: Count the input tokens of {input} for model {model}.
        slots:
          input: requestBody.input
          model: requestBody.model
      - text: Tell me how many tokens {input} plus instructions {instructions} would use.
        slots:
          input: requestBody.input
          instructions: requestBody.instructions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/responses/compact'].post
  update:
    x-apievangelist-phrasing:
      intent: Compact a long conversation
      effect: write
      questions:
      - My conversation is getting too long for the context window — how can I shrink it?
      - Can I compact the history that follows a previous response?
      instructions:
      - text: Compact the conversation after response {previous_response_id} using {model}.
        slots:
          previous_response_id: requestBody.previous_response_id
          model: requestBody.model
      - text: Condense this long input {input} into a compacted response with {model}.
        slots:
          input: requestBody.input
          model: requestBody.model
      method: generated
      generated: '2026-09-26'