Julep Sessions API

openapi: 3.2.0
info:
  title: Julep Agents Sessions 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: Sessions
paths:
  /sessions:
    get:
      operationId: SessionsRoute_list
      description: List sessions (paginated)
      parameters:
      - $ref: '#/components/parameters/Common.PaginationOptions.limit'
      - $ref: '#/components/parameters/Common.PaginationOptions.offset'
      - $ref: '#/components/parameters/Common.PaginationOptions.sort_by'
      - $ref: '#/components/parameters/Common.PaginationOptions.direction'
      - $ref: '#/components/parameters/Common.PaginationOptions.metadata_filter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Sessions.Session'
                required:
                - items
      tags:
      - Sessions
    post:
      operationId: SessionsRoute_create
      description: Create a new session
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sessions.Session'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sessions.CreateSessionRequest'
      tags:
      - Sessions
  /sessions/{id}:
    post:
      operationId: SessionsRoute_createOrUpdate
      description: Create or update a session
      parameters:
      - $ref: '#/components/parameters/Sessions.CreateOrUpdateSessionRequest.id'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sessions.Session'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sessions.CreateSessionRequest'
      tags:
      - Sessions
    put:
      operationId: SessionsRoute_update
      description: Update an existing session by its id (overwrites all existing values)
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the resource
        schema:
          $ref: '#/components/schemas/Common.uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sessions.Session'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sessions.UpdateSessionRequest'
      tags:
      - Sessions
    patch:
      operationId: SessionsRoute_patch
      description: Update an existing session by its id (merges with existing values)
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the resource
        schema:
          $ref: '#/components/schemas/Common.uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sessions.Session'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sessions.PatchSessionRequest'
      tags:
      - Sessions
    delete:
      operationId: SessionsRoute_delete
      description: Delete a session by its id
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the resource
        schema:
          $ref: '#/components/schemas/Common.uuid'
      responses:
        '202':
          description: The request has been accepted for processing, but processing has not yet completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.ResourceDeletedResponse'
      tags:
      - Sessions
    get:
      operationId: SessionsRoute_get
      description: Get a session by id
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the resource
        schema:
          $ref: '#/components/schemas/Common.uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sessions.Session'
      tags:
      - Sessions
  /sessions/{id}/chat:
    post:
      operationId: ChatRoute_generate
      description: Generate a response from the model
      parameters:
      - name: id
        in: path
        required: true
        description: The session ID
        schema:
          $ref: '#/components/schemas/Common.uuid'
      - name: x-custom-api-key
        in: header
        required: false
        description: Custom API key
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/Chat.ChunkChatResponse'
                - $ref: '#/components/schemas/Chat.MessageChatResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/Chat.ChunkChatResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Chat.ChatInput'
        description: Request to generate a response from the model
      tags:
      - Sessions
  /sessions/{id}/history:
    delete:
      operationId: HistoryRoute_delete
      description: Clear the history of a Session (resets the Session)
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the resource
        schema:
          $ref: '#/components/schemas/Common.uuid'
      responses:
        '202':
          description: The request has been accepted for processing, but processing has not yet completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.ResourceDeletedResponse'
      tags:
      - Sessions
    get:
      operationId: HistoryRoute_history
      description: Get history of a Session
      parameters:
      - name: id
        in: path
        required: true
        description: ID of parent
        schema:
          $ref: '#/components/schemas/Common.uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entries.History'
      tags:
      - Sessions
  /sessions/{id}/render:
    post:
      operationId: RenderRoute_render
      description: Render system prompt for the session
      parameters:
      - name: id
        in: path
        required: true
        description: The session ID
        schema:
          $ref: '#/components/schemas/Common.uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chat.RenderResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Chat.ChatInput'
        description: Request to render the system prompt for the session
      tags:
      - Sessions
components:
  schemas:
    Chat.SingleChatOutput:
      type: object
      required:
      - message
      properties:
        message:
          type: object
          required:
          - role
          - content
          properties:
            role:
              allOf:
              - $ref: '#/components/schemas/Entries.ChatMLRole'
              description: The role of the message
            tool_call_id:
              type: string
            content:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
              - type: array
                items:
                  anyOf:
                  - type: object
                    required:
                    - text
                    - type
                    properties:
                      text:
                        type: string
                      type:
                        type: string
                        enum:
                        - text
                        description: The type (fixed to 'text')
                        default: text
                  - type: object
                    required:
                    - image_url
                    - type
                    properties:
                      image_url:
                        type: object
                        required:
                        - url
                        - detail
                        properties:
                          url:
                            type: string
                            description: Image URL or base64 data url (e.g. `data:image/jpeg;base64,<the base64 encoded image>`)
                          detail:
                            allOf:
                            - $ref: '#/components/schemas/Entries.ImageDetail'
                            description: The detail level of the image
                            default: auto
                        description: The image URL
                      type:
                        type: string
                        enum:
                        - image_url
                        description: The type (fixed to 'image_url')
                        default: image_url
                  - type: object
                    required:
                    - tool_use_id
                    - type
                    - content
                    properties:
                      tool_use_id:
                        type: string
                      type:
                        type: string
                        enum:
                        - tool_result
                        default: tool_result
                      content:
                        anyOf:
                        - type: array
                          items:
                            type: object
                            required:
                            - text
                            - type
                            properties:
                              text:
                                type: string
                              type:
                                type: string
                                enum:
                                - text
                                description: The type (fixed to 'text')
                                default: text
                        - type: array
                          items:
                            type: object
                            required:
                            - type
                            - source
                            properties:
                              type:
                                type: string
                                enum:
                                - image
                                default: image
                              source:
                                type: object
                                required:
                                - type
                                - media_type
                                - data
                                properties:
                                  type:
                                    type: string
                                    enum:
                                    - base64
                                    default: base64
                                  media_type:
                                    type: string
                                  data:
                                    type: string
                    description: Anthropic image content part
              description: The content parts of the message
            name:
              type: string
              description: Name
            tool_calls:
              type:
              - array
              - 'null'
              items:
                anyOf:
                - $ref: '#/components/schemas/Tools.ChosenFunctionCall'
                - $ref: '#/components/schemas/Tools.ChosenComputer20241022'
                - $ref: '#/components/schemas/Tools.ChosenTextEditor20241022'
                - $ref: '#/components/schemas/Tools.ChosenBash20241022'
              description: Tool calls generated by the model.
              default: []
            created_at:
              type: string
              format: date-time
              description: When this resource was created as UTC date-time
              readOnly: true
            id:
              allOf:
              - $ref: '#/components/schemas/Common.uuid'
              readOnly: true
      allOf:
      - $ref: '#/components/schemas/Chat.BaseChatOutput'
      description: The output returned by the model. Note that, depending on the model provider, they might return more than one message.
    Tools.UnstructuredSetup:
      type: object
      required:
      - unstructured_api_key
      properties:
        unstructured_api_key:
          type: string
          description: The API key for Unstructured.io
        server_url:
          type: string
          description: Optional server endpoint URL
        server:
          type: string
          description: The server by name to use for all methods
        url_params:
          type: object
          additionalProperties: {}
          description: Parameters to optionally template the server URL with
        retry_config:
          type: object
          additionalProperties: {}
          description: The retry configuration to use for all supported methods
        timeout_ms:
          type: integer
          format: int16
          description: Optional request timeout applied to each operation in milliseconds
      description: Setup parameters for Unstructured integration
    Tools.BraveIntegrationDef:
      type: object
      required:
      - provider
      properties:
        provider:
          type: string
          enum:
          - brave
          description: The provider must be "brave"
          default: brave
        method:
          type: string
          description: The specific method of the integration to call
        setup:
          allOf:
          - $ref: '#/components/schemas/Tools.BraveSearchSetup'
          description: The setup parameters for Brave
        arguments:
          allOf:
          - $ref: '#/components/schemas/Tools.BraveSearchArguments'
          description: The arguments for Brave Search
      allOf:
      - $ref: '#/components/schemas/Tools.BaseIntegrationDef'
      description: Brave integration definition
    Sessions.CreateSessionRequest:
      type: object
      required:
      - situation
      - render_templates
      - token_budget
      - context_overflow
      - auto_run_tools
      - forward_tool_calls
      properties:
        user:
          allOf:
          - $ref: '#/components/schemas/Common.uuid'
          description: User ID of user associated with this session
        users:
          type: array
          items:
            $ref: '#/components/schemas/Common.uuid'
        agent:
          allOf:
          - $ref: '#/components/schemas/Common.uuid'
          description: Agent ID of agent associated with this session
        agents:
          type: array
          items:
            $ref: '#/components/schemas/Common.uuid'
        situation:
          type:
          - string
          - 'null'
          description: Session situation
          default: null
        system_template:
          type: string
          description: A specific system prompt template that sets the background for this session
        render_templates:
          type: boolean
          description: Render system and assistant message content as jinja templates
          default: true
        token_budget:
          type:
          - integer
          - 'null'
          format: uint16
          description: Threshold value for the adaptive context functionality
          default: null
        context_overflow:
          oneOf:
          - $ref: '#/components/schemas/Sessions.ContextOverflowType'
          description: Action to start on context window overflow
          default: null
        auto_run_tools:
          type: boolean
          description: 'Whether to auto-run the tool and send the tool results to the model when available.

            (default: false for sessions, true for tasks)


            If a tool call is made, the tool''s output will be sent back to the model as the model''s input.

            If a tool call is not made, the model''s output will be returned as is.'
          default: false
        forward_tool_calls:
          type: boolean
          description: Whether to forward tool calls to the model
          default: false
        recall_options:
          anyOf:
          - $ref: '#/components/schemas/Sessions.VectorDocSearch'
          - $ref: '#/components/schemas/Sessions.TextOnlyDocSearch'
          - $ref: '#/components/schemas/Sessions.HybridDocSearch'
          description: Recall options for the session
          default: null
        metadata:
          type: object
          additionalProperties: {}
      description: Payload for creating a session
    Tools.Bash20241022Def:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - bash_20241022
          default: bash_20241022
        name:
          type: string
          default: bash
    Tools.BrowserbaseCompleteSessionArguments:
      type: object
      required:
      - id
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - REQUEST_RELEASE
          default: REQUEST_RELEASE
    Tools.BrowserbaseSetup:
      type: object
      required:
      - api_key
      - project_id
      properties:
        api_key:
          type: string
          description: API key for the browserbase integration
        project_id:
          type: string
          description: The project ID. Can be found in Settings.
        api_url:
          type: string
          description: The API URL. Defaults to https://www.browserbase.com
        connect_url:
          type: string
          description: The connect URL. Defaults to wss://connect.browserbase.com
      description: The setup parameters for the browserbase integration
    Tools.LlamaParseIntegrationDef:
      type: object
      required:
      - provider
      properties:
        provider:
          type: string
          enum:
          - llama_parse
          description: The provider must be "LlamaParseSetup"
          default: llama_parse
        method:
          type: string
          description: The specific method of the integration to call
        setup:
          allOf:
          - $ref: '#/components/schemas/Tools.LlamaParseSetup'
          description: The setup parameters for LlamaParse
        arguments:
          allOf:
          - $ref: '#/components/schemas/Tools.LlamaParseFetchArguments'
          description: The arguments for LlamaParse
      allOf:
      - $ref: '#/components/schemas/Tools.BaseIntegrationDef'
      description: LlamaParse integration definition
    Tools.Computer20241022Action:
      type: string
      enum:
      - key
      - type
      - cursor_position
      - mouse_move
      - left_click
      - right_click
      - middle_click
      - double_click
      - screenshot
    Tools.EmailSetup:
      type: object
      required:
      - host
      - port
      - user
      - password
      properties:
        host:
          type: string
          description: The host of the email server
        port:
          type: integer
          format: int32
          description: The port of the email server
        user:
          type: string
          description: The username of the email server
        password:
          type: string
          description: The password of the email server
      description: Setup parameters for Email integration
    Tools.FunctionCallOption:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the function
        arguments:
          type: string
          description: The parameters to pass to the function
    Tools.Computer20241022Def:
      type: object
      required:
      - type
      - display_width_px
      - display_height_px
      properties:
        type:
          type: string
          enum:
          - computer_20241022
          default: computer_20241022
        name:
          type: string
          default: computer
        display_width_px:
          type: integer
          format: uint16
          minimum: 600
          description: The display width in pixels
          default: 1024
        display_height_px:
          type: integer
          format: uint16
          minimum: 400
          description: The display height in pixels
          default: 768
        display_number:
          type: integer
          format: uint16
          minimum: 1
          maximum: 10
          description: The display number to use
          default: 1
      description: Anthropic new tools
    Tools.BraveSearchSetup:
      type: object
      required:
      - brave_api_key
      properties:
        brave_api_key:
          type: string
          description: The api key for Brave Search
      description: Integration definition for Brave Search
    Common.limit:
      type: integer
      format: uint16
      minimum: 1
      description: Limit the number of results
      exclusiveMaximum: 1000
    Sessions.VectorDocSearchUpdate:
      type: object
      properties:
        mode:
          type: string
          enum:
          - vector
          description: The mode to use for the search.
          default: vector
        confidence:
          type: number
          minimum: -1
          maximum: 1
          description: The confidence cutoff level
          default: 0.5
        mmr_strength:
          type: number
          minimum: 0
          description: MMR Strength (mmr_strength = 1 - mmr_lambda)
          default: 0.5
          exclusiveMaximum: 1
      allOf:
      - $ref: '#/components/schemas/Sessions.BaseDocSearchUpdate'
    Tools.EmailArguments:
      type: object
      required:
      - to
      - from
      - subject
      - body
      properties:
        to:
          type: string
          description: The email address to send the email to
        from:
          type: string
          description: The email address to send the email from
        subject:
          type: string
          description: The subject of the email
        body:
          type: string
          description: The body of the email
      description: Arguments for Email sending
    Entries.ImageDetail:
      type: string
      enum:
      - low
      - high
      - auto
      description: Image detail level
    Chat.SchemaCompletionResponseFormat:
      type: object
      required:
      - type
      - json_schema
      properties:
        type:
          type: string
          enum:
          - json_schema
          description: The format of the response
          default: json_schema
        json_schema:
          type: object
          additionalProperties: {}
          description: The schema of the response
    Tools.DummyIntegrationDef:
      type: object
      required:
      - provider
      properties:
        provider:
          type: string
          enum:
          - dummy
          default: dummy
      allOf:
      - $ref: '#/components/schemas/Tools.BaseIntegrationDef'
    Chat.CompletionUsage:
      type: object
      properties:
        completion_tokens:
          type: integer
          format: uint32
          description: Number of tokens in the generated completion
          readOnly: true
        prompt_tokens:
          type: integer
          format: uint32
          description: Number of tokens in the prompt
          readOnly: true
        total_tokens:
          type: integer
          format: uint32
          description: Total number of tokens used in the request (prompt + completion)
          readOnly: true
      description: Usage statistics for the completion request
    Tools.PropertyDefinition:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          description: Type of the property
        description:
          type: string
          description: Description of the property
        enum:
          type: array
          items:
            type: string
          description: Enum values if applicable
        items:
          allOf:
          - $ref: '#/components/schemas/Tools.PropertyDefinition'
          description: Items definition for array types
      description: Property definition for parameter schema
    Entries.ChatMLRole:
      type: string
      enum:
      - user
      - assistant
      - system
      - tool
      description: ChatML role (system|assistant|user|tool)
    Sessions.HybridDocSearchUpdate:
      type: object
      properties:
        mode:
          type: string
          enum:
          - hybrid
          description: The mode to use for the search.
          default: hybrid
        confidence:
          type: number
          minimum: -1
          maximum: 1
          description: The confidence cutoff level
          default: 0.5
        alpha:
          type: number
          minimum: 0
          maximum: 1
          description: The weight to apply to BM25 vs Vector search results. 0 => pure BM25; 1 => pure vector;
          default: 0.5
        mmr_strength:
          type: number
          minimum: 0
          description: MMR Strength (mmr_strength = 1 - mmr_lambda)
          default: 0.5
          exclusiveMaximum: 1
        trigram_similarity_threshold:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
          description: The trigram_similarity_threshold cutoff level
          default: null
        k_multiplier:
          type: integer
          format: int8
          minimum: 0
          description: The k_multiplier cutoff level to control how many intermediate results to fetch before final scoring
          default: 7
      allOf:
      - $ref: '#/components/schemas/Sessions.BaseDocSearchUpdate'
    Tools.BaseIntegrationDef:
      type: object
      required:
      - provider
      properties:
        provider:
          type: string
          enum:
          - dummy
          - weather
          - wikipedia
          - spider
          - brave
          - browserbase
          - email
          - mailgun
          - remote_browser
          - llama_parse
          - ffmpeg
          - cloudinary
          - arxiv
          - unstructured
          - algolia
          - mcp
          - google_sheets
          description: The provider of the integration
        method:
          type: string
          description: The specific method of the integration to call
        setup:
          description: The setup parameters the integration accepts
        arguments:
          description: The arguments to pre-apply to the integration call
      discriminator:
        propertyName: provider
        mapping:
          brave: '#/components/schemas/Tools.BraveIntegrationDef'
          email: '#/components/schemas/Tools.EmailIntegrationDef'
          spider: '#/components/schemas/Tools.SpiderIntegrationDef'
          wikipedia: '#/components/schemas/Tools.WikipediaIntegrationDef'
          weather: '#/components/schemas/Tools.WeatherIntegrationDef'
          mailgun: '#/components/schemas/Tools.MailgunIntegrationDef'
          browserbase: '#/components/schemas/Tools.BaseBrowserbaseIntegrationDef'
          remote_browser: '#/components/schemas/Tools.RemoteBrowserIntegrationDef'
          llama_parse: '#/components/schemas/Tools.LlamaParseIntegrationDef'
          ffmpeg: '#/components/schemas/Tools.FfmpegIntegrationDef'
          cloudinary: '#/components/schemas/Tools.BaseCloudinaryIntegrationDef'
          arxiv: '#/components/schemas/Tools.ArxivIntegrationDef'
          unstructured: '#/components/schemas/Tools.UnstructuredIntegrationDef'
          algolia: '#/components/schemas/Tools.AlgoliaIntegrationDef'
          mcp: '#/components/schemas/Tools.McpIntegrationDef'
          google_sheets: '#/components/schemas/Tools.GoogleSheetsIntegrationDef'
      description: Integration definition
    Chat.ChatInput:
      type: object
      required:
      - remember
      - recall
      - save
      - stream
      - stop
      - auto_run_tools
      - recall_tools
      properties:
        remember:
          type: boolean
          description: 'DISABLED: Whether this interaction should form new memories or not (will be enabled in a future release)'
          default: false
          readOnly: true
        recall:
          type: boolean
          description: Whether previous memories and docs should be recalled or not
          default: true
        save:
          type: boolean
          description: Whether this interaction should be stored in the session history or not
          default: true
        model:
          allOf:
          - $ref: '#/components/schemas/Common.identifierSafeUnicode'
          description: Identifier of the model to be used
        stream:
          type: boolean
          description: Indicates if the server should stream the response as it's generated
          default: false
        stop:
          type: array
          items:
            type: string
          maxItems: 4
          description: Up to 4 sequences where the API will stop generating further tokens.
          default: []
        seed:
          type: integer
          format: int16
          minimum: -1
          maximum: 1000
          description: If specified, the system will make a best effort to sample deterministically for that particular seed value
        max_tokens:
          type: integer
          format: uint32
          minimum: 1
          description: The maximum number of tokens to generate in the chat completion
        logit_bias:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Common.logit_bias'
          description: Modify the likelihood of specified tokens appearing in the completion
        response_format:
          anyOf:
          - $ref: '#/components/schemas/Chat.SimpleCompletionResponseFormat'
          - $ref: '#/components/schemas/Chat.SchemaCompletionResponseFormat'
          description: Response format (set to `json_object` to restrict output to JSON)
        agent:
          allOf:
          - $ref: '#/components/schemas/Common.uuid'
          description: Agent ID of the agent to use for this interaction. (Only applicable for multi-agent sessions)
        repetition_penalty:
          type: number
          format: float
          minimum: 0
          maximum: 2
          description: Number between 0 and 2.0. 1.0 is neutral and values larger than that penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
        length_penalty:
          type: 

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