Julep Responses API

openapi: 3.0.0
info:
  title: Julep Agents Responses API
  termsOfService: https://julep.ai/terms
  contact:
    name: Julep AI
    url: https://julep.ai
    email: developers@julep.ai
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  description: Julep is a backend for creating stateful AI apps with background tasks and long-term memory easily.
  version: 1.0.0
servers:
- url: https://{serverEnv}.julep.ai/api
  description: The julep cloud service endpoint
  variables:
    serverEnv:
      default: api
      description: The environment to use
      enum:
      - api
      - dev
security:
- ApiKeyAuth: []
- ApiKeyAuth_: []
tags:
- name: Responses
paths:
  /responses:
    post:
      operationId: ResponsesRoute_createResponse
      description: Creates a model response. Provide text or image inputs to generate text or JSON outputs.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Responses.Response'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Responses.CreateResponse'
      tags:
      - Responses
  /responses/{id}:
    get:
      operationId: ResponsesRoute_getResponse
      description: Get a response by id
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the response
        schema:
          type: string
      - name: include
        in: query
        required: false
        description: Specify additional output data to include in the model response
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Responses.Includable'
        explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Responses.Response'
      tags:
      - Responses
components:
  schemas:
    Responses.ReasoningEffort:
      type: string
      enum:
      - low
      - medium
      - high
      description: Constraint effort on reasoning models.
    Responses.ComputerTool:
      type: object
      required:
      - type
      - display_width
      - display_height
      - environment
      properties:
        type:
          type: string
          enum:
          - computer_use_preview
          description: The type of the computer use tool. Always `computer_use_preview`.
        display_width:
          type: number
          format: float
          description: The width of the computer display.
        display_height:
          type: number
          format: float
          description: The height of the computer display.
        environment:
          type: string
          enum:
          - mac
          - windows
          - ubuntu
          - browser
          description: The type of computer environment to control.
      allOf:
      - $ref: '#/components/schemas/Responses.BaseTool'
    Responses.ReasoningItem:
      type: object
      required:
      - type
      - id
      - content
      properties:
        type:
          type: string
          enum:
          - reasoning
          description: The type of the object. Always `reasoning`.
        id:
          type: string
          description: The unique identifier of the reasoning content.
        content:
          type: array
          items:
            $ref: '#/components/schemas/Responses.ReasoningContent'
          description: Reasoning text contents.
        status:
          type: string
          enum:
          - in_progress
          - completed
          - incomplete
          description: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.
    Responses.FilePath:
      type: object
      required:
      - type
      - file_id
      - index
      properties:
        type:
          type: string
          enum:
          - file_path
          description: The type of the file path. Always `file_path`.
        file_id:
          type: string
          description: The ID of the file.
        index:
          type: integer
          format: int32
          description: The index of the file in the list of files.
    Responses.InputImage:
      type: object
      required:
      - type
      - detail
      properties:
        type:
          type: string
          enum:
          - input_image
          description: The type of the input item. Always `input_image`.
        image_url:
          type: string
          description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.
        file_id:
          type: string
          description: The ID of the file to be sent to the model.
        detail:
          type: string
          enum:
          - high
          - low
          - auto
          description: The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
          default: auto
    Responses.FunctionToolCallOutput:
      type: object
      required:
      - type
      - call_id
      - output
      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`.
        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
          enum:
          - in_progress
          - completed
          - incomplete
          description: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.
    Responses.ResponseStatus:
      type: string
      enum:
      - completed
      - failed
      - in_progress
      - incomplete
    Responses.ToolChoiceFunction:
      type: object
      required:
      - type
      - name
      properties:
        type:
          type: string
          enum:
          - function
          description: For function calling, the type is always `function`.
        name:
          type: string
          description: The name of the function to call.
      description: Use this option to force the model to call a specific function.
    Responses.FunctionTool:
      type: object
      required:
      - type
      - name
      - parameters
      properties:
        type:
          type: string
          enum:
          - function
        name:
          type: string
        description:
          type: string
        parameters:
          type: object
          additionalProperties: {}
        strict:
          type: boolean
      allOf:
      - $ref: '#/components/schemas/Responses.BaseTool'
    Responses.WebSearchToolCall:
      type: object
      required:
      - id
      - type
      - status
      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`.
        status:
          allOf:
          - $ref: '#/components/schemas/Responses.WebSearchStatus'
          description: The status of the web search tool call.
    Responses.Screenshot:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - screenshot
          description: Specifies the event type. For a screenshot action, this property is always set to `screenshot`.
          default: screenshot
    Responses.BaseTool:
      type: object
      required:
      - type
      properties:
        type:
          type: string
    Responses.MessageStatus:
      type: string
      enum:
      - in_progress
      - completed
      - incomplete
    Responses.UrlCitation:
      type: object
      required:
      - url
      - title
      - type
      - start_index
      - end_index
      properties:
        url:
          type: string
          description: The URL of the web resource.
        title:
          type: string
          description: The title of the web resource.
        type:
          type: string
          enum:
          - url_citation
          description: The type of the URL citation. Always `url_citation`.
        start_index:
          type: integer
          format: int32
          description: The index of the first character of the URL citation in the message.
        end_index:
          type: integer
          format: int32
          description: The index of the last character of the URL citation in the message.
    Responses.ResponseFormatJsonObject:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - json_object
          description: The type of response format being defined. Always `json_object`.
      description: 'JSON object response format. An older method of generating JSON responses.


        Using `json_schema` is recommended for models that support it. Note that the

        model will not generate JSON without a system or user message instructing it

        to do so.'
    Responses.InputItem:
      anyOf:
      - $ref: '#/components/schemas/Responses.EasyInputMessage'
      - $ref: '#/components/schemas/Responses.Item'
      - $ref: '#/components/schemas/Responses.ItemReference'
    Responses.ItemReference:
      anyOf:
      - $ref: '#/components/schemas/Responses.InputMessageResource'
      - $ref: '#/components/schemas/Responses.OutputMessage'
      - $ref: '#/components/schemas/Responses.FileSearchToolCall'
      - $ref: '#/components/schemas/Responses.ComputerToolCall'
      - $ref: '#/components/schemas/Responses.ComputerToolCallOutputResource'
      - $ref: '#/components/schemas/Responses.WebSearchToolCall'
      - $ref: '#/components/schemas/Responses.FunctionToolCall'
      - $ref: '#/components/schemas/Responses.FunctionToolCallOutputResource'
      description: Content item used to generate a response.
    Responses.Wait:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - wait
          description: Specifies the event type. For a wait action, this property is always set to `wait`.
          default: wait
    Responses.Type:
      type: object
      required:
      - type
      - text
      properties:
        type:
          type: string
          enum:
          - type
          description: Specifies the event type. For a type action, this property is always set to `type`.
          default: type
        text:
          type: string
          description: The text to type.
    Responses.Scroll:
      type: object
      required:
      - type
      - x
      - y
      - scroll_x
      - scroll_y
      properties:
        type:
          type: string
          enum:
          - scroll
          description: Specifies the event type. For a scroll action, this property is always set to `scroll`.
          default: scroll
        x:
          type: integer
          format: int32
          description: The x-coordinate where the scroll occurred.
        y:
          type: integer
          format: int32
          description: The y-coordinate where the scroll occurred.
        scroll_x:
          type: integer
          format: int32
          description: The horizontal scroll distance.
        scroll_y:
          type: integer
          format: int32
          description: The vertical scroll distance.
    Responses.FunctionToolCall:
      type: object
      required:
      - id
      - type
      - call_id
      - name
      - arguments
      properties:
        id:
          type: string
          description: The unique ID of the function tool call.
        type:
          type: string
          enum:
          - function_call
          description: The type of the function tool call. Always `function_call`.
        call_id:
          type: string
          description: The unique ID of the function tool call generated by the model.
        name:
          type: string
          description: The name of the function to run.
        arguments:
          type: string
          description: A JSON string of the arguments to pass to the function.
        status:
          type: string
          enum:
          - in_progress
          - completed
          - incomplete
          description: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.
    Responses.OutputMessage:
      type: object
      required:
      - id
      - type
      - role
      - status
      - content
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - message
        role:
          $ref: '#/components/schemas/Responses.MessageRole'
        status:
          $ref: '#/components/schemas/Responses.MessageStatus'
        content:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/Responses.OutputText'
            - $ref: '#/components/schemas/Responses.Refusal'
    Responses.OutputText:
      type: object
      required:
      - type
      - text
      - annotations
      properties:
        type:
          type: string
          enum:
          - output_text
          description: The type of the output text. Always `output_text`.
        text:
          type: string
          description: The text output from the model.
        annotations:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/Responses.FileCitation'
            - $ref: '#/components/schemas/Responses.UrlCitation'
            - $ref: '#/components/schemas/Responses.FilePath'
          description: The annotations of the text output.
    Responses.ResponseError:
      type: object
      required:
      - message
      - type
      properties:
        message:
          type: string
        type:
          type: string
        param:
          type: string
        code:
          type: string
    Responses.FunctionToolCallOutputResource:
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the function call tool output.
      allOf:
      - $ref: '#/components/schemas/Responses.FunctionToolCallOutput'
    Responses.Refusal:
      type: object
      required:
      - type
      - refusal
      properties:
        type:
          type: string
          enum:
          - refusal
          description: The type of the refusal. Always `refusal`.
        refusal:
          type: string
          description: The refusal explanation from the model.
    Responses.Includable:
      type: string
      enum:
      - file_search_call.results
      - message.input_image.image_url
      - computer_call_output.output.image_url
    Responses.ResponseFormatText:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - text
          description: The type of response format being defined. Always `text`.
      description: Default response format. Used to generate text responses.
    Responses.MessageRole:
      type: string
      enum:
      - user
      - assistant
      - system
      - developer
    Responses.InputFile:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - input_file
          description: The type of the input item. Always `input_file`.
        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.
      description: A file input to the model.
    InputMessageContentList:
      type: array
      items:
        anyOf:
        - $ref: '#/components/schemas/Responses.InputText'
        - $ref: '#/components/schemas/Responses.InputImage'
        - $ref: '#/components/schemas/Responses.InputFile'
    Responses.ComputerToolCallOutputResource:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: The unique ID of the computer call tool output.
      allOf:
      - $ref: '#/components/schemas/Responses.ComputerToolCallOutput'
    Responses.CreateResponse:
      type: object
      required:
      - model
      - input
      properties:
        model:
          type: string
        input:
          anyOf:
          - type: string
          - type: array
            items:
              $ref: '#/components/schemas/Responses.InputItem'
        include:
          type: array
          items:
            $ref: '#/components/schemas/Responses.Includable'
        parallel_tool_calls:
          type: boolean
          default: true
        store:
          type: boolean
          default: true
        stream:
          type: boolean
          default: false
        max_tokens:
          type: integer
          format: int32
        temperature:
          type: number
          default: 1
        top_p:
          type: number
          default: 1
        n:
          type: integer
          format: int32
        stop:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        presence_penalty:
          type: number
        frequency_penalty:
          type: number
        logit_bias:
          type: object
          additionalProperties: {}
        user:
          type: string
        instructions:
          type: string
        previous_response_id:
          type: string
        reasoning:
          $ref: '#/components/schemas/Responses.Reasoning'
        text:
          type: object
          properties:
            format:
              anyOf:
              - $ref: '#/components/schemas/Responses.ResponseFormatText'
              - $ref: '#/components/schemas/Responses.TextResponseFormatJsonSchema'
              - $ref: '#/components/schemas/Responses.ResponseFormatJsonObject'
          required:
          - format
        tool_choice:
          anyOf:
          - type: string
            enum:
            - auto
            - none
          - type: object
            properties:
              type:
                type: string
                enum:
                - function
              function:
                type: object
                properties:
                  name:
                    type: string
                required:
                - name
            required:
            - type
            - function
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Responses.Tool'
        truncation:
          type: string
          enum:
          - disabled
          - auto
        metadata:
          type: object
          additionalProperties: {}
    Responses.TextResponseFormatJsonSchema:
      type: object
      required:
      - type
      - schema
      properties:
        type:
          type: string
          enum:
          - json_schema
          description: The type of response format being defined. Always `json_schema`.
        description:
          type: string
          description: A description of what the response format is for, used by the model to determine how to respond in the format.
        name:
          type: string
          description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
        schema:
          type: object
          additionalProperties: {}
          description: The JSON schema that defines the structure of the response.
        strict:
          type: boolean
          description: Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs guide](/docs/guides/structured-outputs).
          default: false
      description: JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](/docs/guides/structured-outputs).
    Responses.Item:
      type: object
      required:
      - type
      properties:
        type:
          type: string
      description: An item representing part of the context for the response to be generated by the model. Can contain text, images, and audio inputs, as well as previous assistant responses and tool call outputs.
    Responses.ComputerToolCallSafetyCheck:
      type: object
      required:
      - id
      - code
      - message
      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.
    Responses.FileSearchToolCall:
      type: object
      required:
      - id
      - type
      - status
      - queries
      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`.
        status:
          type: string
          enum:
          - in_progress
          - searching
          - completed
          - incomplete
          - failed
          description: The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`
        queries:
          type: array
          items:
            type: string
          description: The queries used to search for files.
        results:
          type: array
          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:
                allOf:
                - $ref: '#/components/schemas/Responses.VectorStoreFileAttributes'
                description: The attributes of the file.
              score:
                type: number
                format: float
                description: The relevance score of the file - a value between 0 and 1.
            required:
            - file_id
            - text
            - filename
            - attributes
            - score
          description: The results of the file search tool call.
    Responses.ComputerScreenshotImage:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - computer_screenshot
          description: Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`.
        image_url:
          type: string
          description: The URL of the screenshot image.
        file_id:
          type: string
          description: The identifier of an uploaded file that contains the screenshot.
    Responses.InputMessageResource:
      type: object
      required:
      - id
      properties:
        id:
          type: string
      allOf:
      - $ref: '#/components/schemas/Responses.InputMessage'
    Responses.FileCitation:
      type: object
      required:
      - type
      - index
      - file_id
      properties:
        type:
          type: string
          enum:
          - file_citation
          description: The type of the file citation. Always `file_citation`.
        index:
          type: integer
          format: int32
          description: The index of the file in the list of files.
        file_id:
          type: string
          description: The ID of the file.
    Responses.ComputerToolCall:
      type: object
      required:
      - type
      - id
      - call_id
      - action
      - pending_safety_checks
      - status
      properties:
        type:
          type: string
          enum:
          - computer_call
          description: The type of the computer call. Always `computer_call`.
        id:
          type: string
          description: The unique ID of the computer call.
        call_id:
          type: string
          description: An identifier used when responding to the tool call with output.
        action:
          anyOf:
          - $ref: '#/components/schemas/Responses.Click'
          - $ref: '#/components/schemas/Responses.DoubleClick'
          - $ref: '#/components/schemas/Responses.Drag'
          - $ref: '#/components/schemas/Responses.KeyPress'
          - $ref: '#/components/schemas/Responses.Move'
          - $ref: '#/components/schemas/Responses.Screenshot'
          - $ref: '#/components/schemas/Responses.Scroll'
          - $ref: '#/components/schemas/Responses.Type'
          - $ref: '#/components/schemas/Responses.Wait'
          description: The action to perform.
        pending_safety_checks:
          type: array
          items:
            $ref: '#/components/schemas/Responses.ComputerToolCallSafetyCheck'
          description: The pending safety checks for the computer call.
        status:
          type: string
          enum:
          - in_progress
          - completed
          - incomplete
          description: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.
    Responses.VectorStoreFileAttributesString:
      type: string
      maxLength: 512
    Responses.OutputItem:
      anyOf:
      - $ref: '#/components/schemas/Responses.OutputMessage'
      - $ref: '#/components/schemas/Responses.FileSearchToolCall'
      - $ref: '#/components/schemas/Responses.FunctionToolCall'
      - $ref: '#/components/schemas/Responses.WebSearchToolCall'
      - $ref: '#/components/schemas/Responses.ComputerToolCall'
      - $ref: '#/components/schemas/Responses.ReasoningItem'
    Responses.ToolChoiceTypes:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - file_search
          - web_search_preview
          - computer_use_preview
          - web_search_preview_2025_03_11
          description: "The type of hosted tool the model should to use. Learn more about\n[built-in tools](/docs/guides/tools).\n\nAllowed values are:\n- `file_search`\n- `web_search_preview` \n- `computer_use_preview`"
      description: 'Indicates that the model should use a built-in tool to generate a response.


        [Learn more about built-in tools](/docs/guides/tools).'
    Responses.Coordinate:
      type: object
      required:
      - x
      - y
      properties:
        x:
          type: integer
          format: int32
          description: The x-coordinate.
        y:
          type: integer
          format: int32
          description: The y-coordinate.
    Responses.ToolChoiceOptions:
      type: string
      enum:
      - auto
      - none
      - required
    Responses.EasyInputMessage:
      type: object
      required:
      - role
      - content
      - type
      properties:
        role:
          allOf:
          - $ref: '#/components/schemas/Responses.MessageRole'
          description: The role of the message input. One of `user`, `assistant`, `system`, or `developer`.
        content:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/InputMessageContentList'
          description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.
        type:
          type: string
          enum:
          - message
          description: The type of the message input. Always `message`.
    Responses.Move:
      type: object
      required:
      - type
      - x
      - y
      properties:
        type:
          type: string
          enum:
          - move
          description: Specifies the event type. For a move action, this property is always set to `move`.
          default: move
        x:
          type: integer
          format: int32
          description: The x-coordinate to move to.
        y:
          type: integer
          format: int32
          description: The y-coordinate to move to.
    Responses.DoubleClick:
      type: object
      required:
      - type
      - x
      - y
      properties:
        type:
          type: string
          enum:
          - double_click
          description: Specifies the event type. For a double click action, this property is always set to `double_click`.
          default: double_click
        x:
          type: integer
          format: int32
          description: The x-coordinate where the double click occurred.
        y:
          type: integer
          format: int32
          description: The y-coordinate where the double click occurred.
    Responses.InputMessage:
      type: object
      required:
      - type
      - role
      - status
      - content
      properties:
        type:
          type: string
          enum:
          - message
        role:
          $ref: '#/components/schemas/Responses.MessageRole'
        status:
          $ref: '#/components/schemas/Responses.MessageStatus'
        content:
          $ref: '#/components/schemas/InputMessageContentList'
    Responses.Drag:
      type: object
      required:
      - type
      - path
      properties:
        type:
          type: string
          enum:
          - drag
          description: Specifies the event type. For a drag action, this property is always set to `drag`.
          default: drag
        path:
          type: array
          items:
            $ref: '#/components/schemas/Responses.Coordinate'
          description: An array of coordinates representing the path of the drag action.
    Responses.Tool:
      anyOf:
      - $ref: '#/components/schemas/Responses.FunctionTool'
      - $ref: '#/components/schemas/Responses.WebSearchTool'
      - $ref: '#/components/schemas/Responses.FileSearchTool'
      - $ref: '#/components/schemas/Responses.ComputerTool'
    Responses.VectorStoreFileAttributes:
      type: object
      required:
      - properties
      properties:
        properties:
          type: object
          additionalProperties:
            anyOf:
            - $ref: '#/components/schemas/Responses.VectorStoreFileAttributesString'
            - type: boolean
            - type: number
          description: Key-value pairs where keys are strings with max length 64 and values are strings with max length 512, booleans, or numbers.
      description: Set of key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers.
    Responses.Click:
      type: object
      required:
      - type
      - button
      - x
      - y
      properties:
        type:
          type: string
          enum:
          - click
          description: Specifies the event type. For a click action, this property is always set to `click`.
          default: click
        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:
      

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