# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for TextQL v2 Chat API
  version: 1.0.0
extends: openapi/textql-chat-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: 8
- target: $.paths['/v2/chats'].get
  update:
    x-apievangelist-phrasing:
      intent: List my API chats
      effect: read
      questions:
      - Which chats has my API key created?
      - Can I search my chats by summary or first message?
      instructions:
      - text: List my chats.
      - text: Find chats mentioning {search_term}, {limit} at a time.
        slots:
          search_term: query.search_term
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/chats'].post
  update:
    x-apievangelist-phrasing:
      intent: Ask a data question and wait for the answer
      effect: write
      questions:
      - How do I ask TextQL a question about my data and get the full answer back in one response?
      - Can I attach a file when I ask a question?
      - Can I limit which connectors a question is answered from?
      instructions:
      - text: Ask {question} and wait for the complete answer.
        slots:
          question: requestBody.question
      - text: Ask {question} using only connectors {connectors}, returning the answer synchronously.
        slots:
          question: requestBody.question
          connectors: requestBody.connector_ids
      - text: Continue chat {chat} with the follow-up {question} and return the whole reply at once.
        slots:
          chat: requestBody.chat_id
          question: requestBody.question
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/chats/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Ask a data question and stream the answer
      effect: write
      questions:
      - Can I get the answer to a data question streamed back as it's generated?
      - How do I receive Server-Sent Events with text deltas and execution cells for a question?
      instructions:
      - text: Stream the answer to {question} as server-sent events.
        slots:
          question: requestBody.question
      - text: Stream a reply to {question} in chat {chat} using model {model}.
        slots:
          question: requestBody.question
          chat: requestBody.chat_id
          model: requestBody.model
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/chats/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a chat with its messages
      effect: read
      questions:
      - How do I retrieve a chat along with its messages and generated assets?
      - What did the agent answer in a previous REST chat?
      instructions:
      - text: Get chat {id} with its messages.
        slots:
          id: path.id
      - text: Show the conversation and assets for chat {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/chats/{id}/cells'].get
  update:
    x-apievangelist-phrasing:
      intent: List the execution cells of a chat
      effect: read
      questions:
      - Can I see the SQL and Python the agent ran to produce an answer?
      - How do I page through every step behind a chat's answers?
      instructions:
      - text: List the cells of chat {id}.
        slots:
          id: path.id
      - text: Show {limit} execution steps from chat {id} starting at offset {offset}.
        slots:
          limit: query.limit
          id: path.id
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/chats/{id}/cells/{cellId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one execution cell from a chat
      effect: read
      questions:
      - How do I fetch a single step from a chat by its cell ID?
      - Can I look at just one generated query and its output?
      instructions:
      - text: Get cell {cell} from chat {id}.
        slots:
          cell: path.cellId
          id: path.id
      - text: Show the output of step {cell} in chat {id}.
        slots:
          cell: path.cellId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/chats/{id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a streaming chat response
      effect: destructive
      questions:
      - How do I stop a REST chat stream that's taking too long?
      - Can I cancel an in-flight streamed answer?
      instructions:
      - text: Cancel the running stream for chat {id}.
        slots:
          id: path.id
      - text: Abort the streamed answer currently generating in chat {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/models'].get
  update:
    x-apievangelist-phrasing:
      intent: List models I can run chats on
      effect: read
      questions:
      - Which models is my organization allowed to use for chats?
      - What model IDs can I pass when asking a question?
      instructions:
      - text: List the models available to me for chats.
      - text: Show which chat models my role is allowed to pick.
      method: generated
      generated: '2026-10-01'