Portkey Responses API

openapi: 3.0.0
info:
  title: Portkey Analytics > Graphs Responses API
  description: The Portkey REST API. Please see https://portkey.ai/docs/api-reference for more details.
  version: 2.0.0
  termsOfService: https://portkey.ai/terms
  contact:
    name: Portkey Developer Forum
    url: https://portkey.wiki/community
  license:
    name: MIT
    url: https://github.com/Portkey-AI/portkey-openapi/blob/master/LICENSE
servers:
- url: https://api.portkey.ai/v1
  description: Portkey API Public Endpoint
security:
- Portkey-Key: []
tags:
- name: Responses
paths:
  /responses:
    servers:
    - url: https://api.portkey.ai/v1
      description: Portkey API Public Endpoint
    - url: SELF_HOSTED_GATEWAY_URL
      description: Self-Hosted Gateway URL
    post:
      operationId: createResponse
      tags:
      - Responses
      summary: 'Creates a model response

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResponse'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ResponseStreamEvent'
  /responses/{response_id}:
    servers:
    - url: https://api.portkey.ai/v1
      description: Portkey API Public Endpoint
    - url: SELF_HOSTED_GATEWAY_URL
      description: Self-Hosted Gateway URL
    get:
      operationId: getResponse
      tags:
      - Responses
      summary: 'Retrieves a model response with the given ID.

        '
      parameters:
      - in: path
        name: response_id
        required: true
        schema:
          type: string
          example: resp_677efb5139a88190b512bc3fef8e535d
        description: The ID of the response to retrieve.
      - in: query
        name: include
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Includable'
        description: "Specify additional output data to include in the response. Currently\nsupported values are:\n- `file_search_call.results`: Include the search results of\n  the file search tool call.\n- `message.input_image.image_url`: Include image urls from the input message.\n- `computer_call_output.output.image_url`: Include image urls from the computer call output.\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
    delete:
      operationId: deleteResponse
      tags:
      - Responses
      summary: 'Deletes a model response with the given ID.

        '
      parameters:
      - in: path
        name: response_id
        required: true
        schema:
          type: string
          example: resp_677efb5139a88190b512bc3fef8e535d
        description: The ID of the response to delete.
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /responses/{response_id}/input_items:
    servers:
    - url: https://api.portkey.ai/v1
      description: Portkey API Public Endpoint
    - url: SELF_HOSTED_GATEWAY_URL
      description: Self-Hosted Gateway URL
    get:
      operationId: listInputItems
      tags:
      - Responses
      summary: Returns a list of input items for a given response.
      parameters:
      - in: path
        name: response_id
        required: true
        schema:
          type: string
        description: The ID of the response to retrieve input items for.
      - name: limit
        in: query
        description: 'A limit on the number of objects to be returned. Limit can range between

          1 and 100, and the default is 20.

          '
        required: false
        schema:
          type: integer
          default: 20
      - in: query
        name: order
        schema:
          type: string
          enum:
          - asc
          - desc
        description: 'The order to return the input items in. Default is `asc`.

          - `asc`: Return the input items in ascending order.

          - `desc`: Return the input items in descending order.

          '
      - in: query
        name: after
        schema:
          type: string
        description: 'An item ID to list items after, used in pagination.

          '
      - in: query
        name: before
        schema:
          type: string
        description: 'An item ID to list items before, used in pagination.

          '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseItemList'
components:
  schemas:
    ComputerToolCallSafetyCheck:
      type: object
      description: 'A pending safety check for the computer call.

        '
      properties:
        id:
          type: string
          description: The ID of the pending safety check.
        code:
          type: string
          description: The type of the pending safety check.
        message:
          type: string
          description: Details about the pending safety check.
      required:
      - id
      - code
      - message
    ResponseTextDoneEvent:
      type: object
      description: Emitted when text content is finalized.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.output_text.done`.

            '
          enum:
          - response.output_text.done
          x-stainless-const: true
        item_id:
          type: string
          description: 'The ID of the output item that the text content is finalized.

            '
        output_index:
          type: integer
          description: 'The index of the output item that the text content is finalized.

            '
        content_index:
          type: integer
          description: 'The index of the content part that the text content is finalized.

            '
        text:
          type: string
          description: 'The text content that is finalized.

            '
      required:
      - type
      - item_id
      - output_index
      - content_index
      - text
    Click:
      type: object
      title: Click
      description: 'A click action.

        '
      properties:
        type:
          type: string
          enum:
          - click
          default: click
          description: "Specifies the event type. For a click action, this property is \nalways set to `click`.\n"
          x-stainless-const: true
        button:
          type: string
          enum:
          - left
          - right
          - wheel
          - back
          - forward
          description: 'Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.

            '
        x:
          type: integer
          description: 'The x-coordinate where the click occurred.

            '
        y:
          type: integer
          description: 'The y-coordinate where the click occurred.

            '
      required:
      - type
      - button
      - x
      - y
    FilePath:
      type: object
      title: File path
      description: 'A path to a file.

        '
      properties:
        type:
          type: string
          description: 'The type of the file path. Always `file_path`.

            '
          enum:
          - file_path
          x-stainless-const: true
        file_id:
          type: string
          description: 'The ID of the file.

            '
        index:
          type: integer
          description: 'The index of the file in the list of files.

            '
      required:
      - type
      - file_id
      - index
    ResponseItemList:
      type: object
      description: A list of Response items.
      properties:
        object:
          type: string
          description: The type of object returned, must be `list`.
          enum:
          - list
          x-stainless-const: true
        data:
          type: array
          description: A list of items used to generate this response.
          items:
            $ref: '#/components/schemas/ItemResource'
        has_more:
          type: boolean
          description: Whether there are more items available.
        first_id:
          type: string
          description: The ID of the first item in the list.
        last_id:
          type: string
          description: The ID of the last item in the list.
      required:
      - object
      - data
      - has_more
      - first_id
      - last_id
      x-oaiExpandable: true
    CreateModelResponseProperties:
      allOf:
      - $ref: '#/components/schemas/ModelResponseProperties'
    Error:
      type: object
      properties:
        code:
          type: string
          nullable: true
        message:
          type: string
          nullable: false
        param:
          type: string
          nullable: true
        type:
          type: string
          nullable: false
      required:
      - type
      - message
      - param
      - code
    FileSearchToolCall:
      type: object
      title: File search tool call
      description: "The results of a file search tool call. See the \n[file search guide](/docs/guides/tools-file-search) for more information.\n"
      properties:
        id:
          type: string
          description: 'The unique ID of the file search tool call.

            '
        type:
          type: string
          enum:
          - file_search_call
          description: 'The type of the file search tool call. Always `file_search_call`.

            '
          x-stainless-const: true
        status:
          type: string
          description: "The status of the file search tool call. One of `in_progress`, \n`searching`, `incomplete` or `failed`,\n"
          enum:
          - in_progress
          - searching
          - completed
          - incomplete
          - failed
        queries:
          type: array
          items:
            type: string
          description: 'The queries used to search for files.

            '
        results:
          type: array
          description: 'The results of the file search tool call.

            '
          items:
            type: object
            properties:
              file_id:
                type: string
                description: 'The unique ID of the file.

                  '
              text:
                type: string
                description: 'The text that was retrieved from the file.

                  '
              filename:
                type: string
                description: 'The name of the file.

                  '
              attributes:
                $ref: '#/components/schemas/VectorStoreFileAttributes'
              score:
                type: number
                format: float
                description: 'The relevance score of the file - a value between 0 and 1.

                  '
          nullable: true
      required:
      - id
      - type
      - status
      - queries
    CodeInterpreterTextOutput:
      type: object
      title: Code interpreter text output
      description: 'The output of a code interpreter tool call that is text.

        '
      properties:
        type:
          type: string
          enum:
          - logs
          description: 'The type of the code interpreter text output. Always `logs`.

            '
          x-stainless-const: true
        logs:
          type: string
          description: 'The logs of the code interpreter tool call.

            '
      required:
      - type
      - logs
    FileCitation:
      type: object
      title: File citation
      description: 'A citation to a file.

        '
      properties:
        type:
          type: string
          description: 'The type of the file citation. Always `file_citation`.

            '
          enum:
          - file_citation
          x-stainless-const: true
        index:
          type: integer
          description: 'The index of the file in the list of files.

            '
        file_id:
          type: string
          description: 'The ID of the file.

            '
      required:
      - type
      - index
      - file_id
    ItemResource:
      description: 'Content item used to generate a response.

        '
      oneOf:
      - $ref: '#/components/schemas/InputMessageResource'
      - $ref: '#/components/schemas/OutputMessage'
      - $ref: '#/components/schemas/FileSearchToolCall'
      - $ref: '#/components/schemas/ComputerToolCall'
      - $ref: '#/components/schemas/ComputerToolCallOutputResource'
      - $ref: '#/components/schemas/WebSearchToolCall'
      - $ref: '#/components/schemas/FunctionToolCallResource'
      - $ref: '#/components/schemas/FunctionToolCallOutputResource'
      x-oaiExpandable: true
      discriminator:
        propertyName: type
    ResponseCodeInterpreterCallInterpretingEvent:
      type: object
      description: Emitted when the code interpreter is actively interpreting the code snippet.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.code_interpreter_call.interpreting`.

            '
          enum:
          - response.code_interpreter_call.interpreting
          x-stainless-const: true
        output_index:
          type: integer
          description: 'The index of the output item that the code interpreter call is in progress.

            '
        code_interpreter_call:
          $ref: '#/components/schemas/CodeInterpreterToolCall'
      required:
      - type
      - response_id
      - output_index
      - code_interpreter_call
    ResponseErrorCode:
      type: string
      description: 'The error code for the response.

        '
      enum:
      - server_error
      - rate_limit_exceeded
      - invalid_prompt
      - vector_store_timeout
      - invalid_image
      - invalid_image_format
      - invalid_base64_image
      - invalid_image_url
      - image_too_large
      - image_too_small
      - image_parse_error
      - image_content_policy_violation
      - invalid_image_mode
      - image_file_too_large
      - unsupported_image_media_type
      - empty_image_file
      - failed_to_download_image
      - image_file_not_found
    ResponseFormatText:
      type: object
      title: Text
      description: 'Default response format. Used to generate text responses.

        '
      properties:
        type:
          type: string
          description: The type of response format being defined. Always `text`.
          enum:
          - text
          x-stainless-const: true
      required:
      - type
    ResponseFormatJsonSchemaSchema:
      type: object
      title: JSON schema
      description: 'The schema for the response format, described as a JSON Schema object.

        Learn how to build JSON schemas [here](https://json-schema.org/).

        '
      additionalProperties: true
    ResponseCodeInterpreterCallCodeDeltaEvent:
      type: object
      description: Emitted when a partial code snippet is added by the code interpreter.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.code_interpreter_call.code.delta`.

            '
          enum:
          - response.code_interpreter_call.code.delta
          x-stainless-const: true
        output_index:
          type: integer
          description: 'The index of the output item that the code interpreter call is in progress.

            '
        delta:
          type: string
          description: 'The partial code snippet added by the code interpreter.

            '
      required:
      - type
      - response_id
      - output_index
      - delta
    WebSearchToolCall:
      type: object
      title: Web search tool call
      description: "The results of a web search tool call. See the \n[web search guide](/docs/guides/tools-web-search) for more information.\n"
      properties:
        id:
          type: string
          description: 'The unique ID of the web search tool call.

            '
        type:
          type: string
          enum:
          - web_search_call
          description: 'The type of the web search tool call. Always `web_search_call`.

            '
          x-stainless-const: true
        status:
          type: string
          description: 'The status of the web search tool call.

            '
          enum:
          - in_progress
          - searching
          - completed
          - failed
      required:
      - id
      - type
      - status
    Drag:
      type: object
      title: Drag
      description: 'A drag action.

        '
      properties:
        type:
          type: string
          enum:
          - drag
          default: drag
          description: "Specifies the event type. For a drag action, this property is \nalways set to `drag`.\n"
          x-stainless-const: true
        path:
          type: array
          description: "An array of coordinates representing the path of the drag action. Coordinates will appear as an array\nof objects, eg\n```\n[\n  { x: 100, y: 200 },\n  { x: 200, y: 300 }\n]\n```\n"
          x-oaiExpandable: true
          items:
            title: Drag path coordinates
            x-oaiExpandable: true
            description: 'A series of x/y coordinate pairs in the drag path.

              '
            $ref: '#/components/schemas/Coordinate'
      required:
      - type
      - path
    ResponseContentPartAddedEvent:
      type: object
      description: Emitted when a new content part is added.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.content_part.added`.

            '
          enum:
          - response.content_part.added
          x-stainless-const: true
        item_id:
          type: string
          description: 'The ID of the output item that the content part was added to.

            '
        output_index:
          type: integer
          description: 'The index of the output item that the content part was added to.

            '
        content_index:
          type: integer
          description: 'The index of the content part that was added.

            '
        part:
          x-oaiExpandable: true
          $ref: '#/components/schemas/OutputContent'
          description: 'The content part that was added.

            '
      required:
      - type
      - item_id
      - output_index
      - content_index
      - part
    ItemReference:
      type: object
      title: Item reference
      description: 'An internal identifier for an item to reference.

        '
      properties:
        id:
          type: string
          description: 'The ID of the item to reference.

            '
        type:
          type: string
          description: 'The type of item to reference. Always `item_reference`.

            '
          enum:
          - item_reference
          x-stainless-const: true
      required:
      - id
      - type
    ResponseContentPartDoneEvent:
      type: object
      description: Emitted when a content part is done.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.content_part.done`.

            '
          enum:
          - response.content_part.done
          x-stainless-const: true
        item_id:
          type: string
          description: 'The ID of the output item that the content part was added to.

            '
        output_index:
          type: integer
          description: 'The index of the output item that the content part was added to.

            '
        content_index:
          type: integer
          description: 'The index of the content part that is done.

            '
        part:
          x-oaiExpandable: true
          $ref: '#/components/schemas/OutputContent'
          description: 'The content part that is done.

            '
      required:
      - type
      - item_id
      - output_index
      - content_index
      - part
    FunctionToolCallOutput:
      type: object
      title: Function tool call output
      description: 'The output of a function tool call.

        '
      properties:
        id:
          type: string
          description: 'The unique ID of the function tool call output. Populated when this item

            is returned via API.

            '
        type:
          type: string
          enum:
          - function_call_output
          description: 'The type of the function tool call output. Always `function_call_output`.

            '
          x-stainless-const: true
        call_id:
          type: string
          description: 'The unique ID of the function tool call generated by the model.

            '
        output:
          type: string
          description: 'A JSON string of the output of the function tool call.

            '
        status:
          type: string
          description: 'The status of the item. One of `in_progress`, `completed`, or

            `incomplete`. Populated when items are returned via API.

            '
          enum:
          - in_progress
          - completed
          - incomplete
      required:
      - type
      - call_id
      - output
    ToolChoiceFunction:
      type: object
      title: Function tool
      description: 'Use this option to force the model to call a specific function.

        '
      properties:
        type:
          type: string
          enum:
          - function
          description: For function calling, the type is always `function`.
          x-stainless-const: true
        name:
          type: string
          description: The name of the function to call.
      required:
      - type
      - name
    ResponseCodeInterpreterCallCompletedEvent:
      type: object
      description: Emitted when the code interpreter call is completed.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.code_interpreter_call.completed`.

            '
          enum:
          - response.code_interpreter_call.completed
          x-stainless-const: true
        output_index:
          type: integer
          description: 'The index of the output item that the code interpreter call is in progress.

            '
        code_interpreter_call:
          $ref: '#/components/schemas/CodeInterpreterToolCall'
      required:
      - type
      - response_id
      - output_index
      - code_interpreter_call
    Type:
      type: object
      title: Type
      description: 'An action to type in text.

        '
      properties:
        type:
          type: string
          enum:
          - type
          default: type
          description: "Specifies the event type. For a type action, this property is \nalways set to `type`.\n"
          x-stainless-const: true
        text:
          type: string
          description: 'The text to type.

            '
      required:
      - type
      - text
    Item:
      type: object
      description: 'Content item used to generate a response.

        '
      oneOf:
      - $ref: '#/components/schemas/InputMessage'
      - $ref: '#/components/schemas/OutputMessage'
      - $ref: '#/components/schemas/FileSearchToolCall'
      - $ref: '#/components/schemas/ComputerToolCall'
      - $ref: '#/components/schemas/ComputerToolCallOutput'
      - $ref: '#/components/schemas/WebSearchToolCall'
      - $ref: '#/components/schemas/FunctionToolCall'
      - $ref: '#/components/schemas/FunctionToolCallOutput'
      - $ref: '#/components/schemas/ReasoningItem'
      x-oaiExpandable: true
      discriminator:
        propertyName: type
    VectorStoreFileAttributes:
      type: object
      description: "Set of 16 key-value pairs that can be attached to an object. This can be \nuseful for storing additional information about the object in a structured \nformat, and querying for objects via API or the dashboard. Keys are strings \nwith a maximum length of 64 characters. Values are strings with a maximum \nlength of 512 characters, booleans, or numbers.\n"
      maxProperties: 16
      additionalProperties:
        oneOf:
        - type: string
          maxLength: 512
        - type: number
        - type: boolean
      x-oaiTypeLabel: map
      nullable: true
    ResponseOutputItemDoneEvent:
      type: object
      description: Emitted when an output item is marked done.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.output_item.done`.

            '
          enum:
          - response.output_item.done
          x-stainless-const: true
        output_index:
          type: integer
          description: 'The index of the output item that was marked done.

            '
        item:
          $ref: '#/components/schemas/OutputItem'
          x-oaiExpandable: true
          description: 'The output item that was marked done.

            '
      required:
      - type
      - output_index
      - item
    ComputerToolCallOutput:
      type: object
      title: Computer tool call output
      description: 'The output of a computer tool call.

        '
      properties:
        type:
          type: string
          description: 'The type of the computer tool call output. Always `computer_call_output`.

            '
          enum:
          - computer_call_output
          default: computer_call_output
          x-stainless-const: true
        id:
          type: string
          description: 'The ID of the computer tool call output.

            '
        call_id:
          type: string
          description: 'The ID of the computer tool call that produced the output.

            '
        acknowledged_safety_checks:
          type: array
          x-oaiExpandable: true
          description: "The safety checks reported by the API that have been acknowledged by the \ndeveloper.\n"
          items:
            $ref: '#/components/schemas/ComputerToolCallSafetyCheck'
        output:
          $ref: '#/components/schemas/ComputerScreenshotImage'
        status:
          type: string
          description: 'The status of the message input. One of `in_progress`, `completed`, or

            `incomplete`. Populated when input items are returned via API.

            '
          enum:
          - in_progress
          - completed
          - incomplete
      required:
      - type
      - call_id
      - output
    ResponseFileSearchCallInProgressEvent:
      type: object
      description: Emitted when a file search call is initiated.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.file_search_call.in_progress`.

            '
          enum:
          - response.file_search_call.in_progress
          x-stainless-const: true
        output_index:
          type: integer
          description: 'The index of the output item that the file search call is initiated.

            '
        item_id:
          type: string
          description: 'The ID of the output item that the file search call is initiated.

            '
      required:
      - type
      - output_index
      - item_id
    InputItem:
      oneOf:
      - $ref: '#/components/schemas/EasyInputMessage'
      - type: object
        title: Item
        description: "An item representing part of the context for the response to be \ngenerated by the model. Can contain text, images, and audio inputs,\nas well as previous assistant responses and tool call outputs.\n"
        $ref: '#/components/schemas/Item'
      - $ref: '#/components/schemas/ItemReference'
      discriminator:
        propertyName: type
    InputFile:
      type: object
      title: File input
      description: 'A file input to the model.

        '
      properties:
        type:
          type: string
          description: 'The type of the input item. Always `input_file`.

            '
          enum:
          - input_file
          x-stainless-const: true
        file_id:
          type: string
          description: 'The ID of the file to be sent to the model.

            '
        filename:
          type: string
          description: 'The name of the file to be sent to the model.

            '
        file_data:
          type: string
          description: 'The content of the file to be sent to the model.

            '
      required:
      - type
    Refusal:
      type: object
      title: Refusal
      description: 'A refusal from the model.

        '
      properties:
        type:
          type: string
          description: 'The type of the refusal. Always `refusal`.

            '
          enum:
          - refusal
          x-stainless-const: true
        refusal:
          type: string
          description: 'The refusal explanationfrom the model.

            '
      required:
      - type
      - refusal
    ResponseWebSearchCallCompletedEvent:
      type: object
      description: Emitted when a web search call is completed.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.web_search_call.completed`.

            '
          enum:
          - response.web_search_call.completed
          x-stainless-const: true
        output_index:
          type: integer
          description: 'The index of the output item that the web search call is associated with.

            '
        item_id:
          type: string
          description: 'Unique ID for the output item associated with the web search call.

            '
      required:
      - type
      - output_index
      - item_id
    Coordinate:
      type: object
      title: Coordinate
      description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.

        '
      properties:
        x:
          type: integer
          description: 'The x-coordinate.

            '
        y:
          type: integer
          description: 'The y-coordinate.

            '
      required:
      - x
      - y
    ResponseUsage:
      type: object
      description: 'Represents token usage details including input tokens, output tokens,

        a breakdown of output tokens, and the total tokens used.

        '
      properties:
        input_tokens:
          type: integer
          description: The number of input tokens.
        input_tokens_details:
          type: object
          description: A detailed breakdown of the input tokens.
          properties:
            cached_tokens:
              type: integer
              description: "The number of tokens that were retrieved from the cache. \n[More on prompt caching](/docs/guides/prompt-caching).\n"
          required:
          - cached_tokens
        output_tokens:
          type: integer
          description: The number of output tokens.
        output_tokens_details:
          type: object
          description: A detailed breakdown of the output tokens.
          properties:
            reasoning_tokens:
              type: integer
              description: The number of reasoning tokens.
          required:
          - reasoning_tokens
        total_tokens:
          type: integer
          description: The total number of tokens used.
      required:
      - input_tokens
      - input_tokens_details
      - output_tokens
      - output_tokens_details
      - total_tokens
    ReasoningItem:
      type: object
      description: 'A description of the chain of thought used by a reasoning model while generating

        a response.

        '
      title: Reasoning
      x-oaiExpandable: true
      properties:
        type:
          type: string
          description: 'The type of the object. Always `reasoning`.

            '
          enum:
          - reasoning
          x-stainless-const: true
        id:
          type: string
          description: 'The unique identifier of the reasoning content.

            '
        summary:
          type: array
          description: 'Reasoning text contents.

            '
          items:
            type: object
            properties:
              type:
                type: string
                description: 'The type of the object. Always `summary_text`.

      

# --- truncated at 32 KB (110 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/portkey/refs/heads/main/openapi/portkey-responses-api-openapi.yml