Phonic conversationItems API

openapi: 3.1.0
info:
  title: API Reference agents conversationItems API
  version: 1.0.0
servers:
- url: https://api.phonic.ai/v1
  description: https://api.phonic.ai/v1
tags:
- name: conversationItems
paths:
  /conversation_items/{id}/replay:
    post:
      operationId: replay
      summary: Replay
      description: 'Returns the alternative response(s) the assistant would have

        produced for this conversation turn given changes to the agent system prompt.


        Only assistant items from ended conversations can be replayed. The

        conversation must have an associated agent.

        '
      tags:
      - conversationItems
      parameters:
      - name: id
        in: path
        description: The ID of the conversation item to replay.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplayConversationItemResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Conversation item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '409':
          description: Conversation is still live
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '422':
          description: Conversation item cannot be replayed (no associated agent, or not an assistant item)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplayConversationItemRequest'
components:
  schemas:
    ReplayToolCallTool:
      type: object
      properties:
        id:
          type: string
          description: The tool ID.
        name:
          type: string
          description: The tool name.
      required:
      - id
      - name
      title: ReplayToolCallTool
    ReplayToolCallEndpointMethod:
      type: string
      enum:
      - GET
      - POST
      description: HTTP method for webhook tool calls.
      title: ReplayToolCallEndpointMethod
    ReplayConversationItemResponseResponsesItems:
      type: object
      properties:
        text:
          type: string
          description: The text the LLM produced for this replay response.
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ReplayToolCall'
          description: Tool calls the LLM would invoke for this replay response - note that the tools will not actually be called during replay.
      required:
      - text
      - tool_calls
      title: ReplayConversationItemResponseResponsesItems
    ReplayConversationItemRequest:
      type: object
      properties:
        system_prompt:
          type: string
          description: The system prompt to use when generating replay responses. Use this to test prompt changes against this conversation turn.
        num_responses:
          type: integer
          default: 1
          description: Number of alternative responses to generate.
      required:
      - system_prompt
      title: ReplayConversationItemRequest
    ValidationError:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ValidationErrorError'
        param_errors:
          type: object
          additionalProperties:
            type: string
          description: Parameter-specific validation errors
      required:
      - error
      - param_errors
      title: ValidationError
    ValidationErrorError:
      type: object
      properties:
        message:
          type: string
          description: Error message
      required:
      - message
      title: ValidationErrorError
    ReplayToolCall:
      type: object
      properties:
        tool:
          $ref: '#/components/schemas/ReplayToolCallTool'
        endpoint_method:
          $ref: '#/components/schemas/ReplayToolCallEndpointMethod'
          description: HTTP method for webhook tool calls.
        endpoint_url:
          type: string
          description: URL for webhook tool calls.
        endpoint_headers:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: Headers for webhook tool calls.
        query_params:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: Query parameters the LLM produced for webhook tool calls.
        context:
          type: string
          description: Context returned from custom-context tool calls.
        request_body:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
          description: Request body the LLM produced for the tool call.
      required:
      - tool
      - request_body
      title: ReplayToolCall
    BasicError:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/BasicErrorError'
      title: BasicError
    ReplayConversationItemResponse:
      type: object
      properties:
        responses:
          type: array
          items:
            $ref: '#/components/schemas/ReplayConversationItemResponseResponsesItems'
          description: Alternative responses generated for the conversation item.
      required:
      - responses
      title: ReplayConversationItemResponse
    BasicErrorError:
      type: object
      properties:
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
      required:
      - message
      title: BasicErrorError
    Error:
      oneOf:
      - $ref: '#/components/schemas/BasicError'
      - $ref: '#/components/schemas/ValidationError'
      title: Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).