Julep Sessions API

openapi: 3.0.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:
    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
    Common.uuid:
      type: string
      format: uuid
    Common.ResourceDeletedResponse:
      type: object
      required:
      - id
      - deleted_at
      - jobs
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/Common.uuid'
          description: ID of deleted resource
        deleted_at:
          type: string
          format: date-time
          description: When this resource was deleted as UTC date-time
          readOnly: true
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Common.uuid'
          description: IDs (if any) of jobs created as part of this request
          default: []
          readOnly: true
    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.GoogleSheetsBatchReadArguments:
      type: object
      required:
      - spreadsheet_id
      - ranges
      properties:
        spreadsheet_id:
          type: string
          description: The ID of the spreadsheet to read from
        ranges:
          type: array
          items:
            type: string
          description: The A1 notation of the ranges to read
        major_dimension:
          type: string
          enum:
          - ROWS
          - COLUMNS
          description: The major dimension that results should use
          default: ROWS
        value_render_option:
          type: string
          enum:
          - FORMATTED_VALUE
          - UNFORMATTED_VALUE
          - FORMULA
          description: How values should be represented in the output
          default: FORMATTED_VALUE
        date_time_render_option:
          type: string
          enum:
          - SERIAL_NUMBER
          - FORMATTED_STRING
          description: How dates, times, and durations should be represented
          default: FORMATTED_STRING
      description: Arguments for batch reading values from multiple ranges
    Tools.WikipediaIntegrationDef:
      type: object
      required:
      - provider
      properties:
        provider:
          type: string
          enum:
          - wikipedia
          description: The provider must be "wikipedia"
          default: wikipedia
        method:
          type: string
          description: The specific method of the integration to call
        setup:
          nullable: true
          description: The setup parameters for Wikipedia
          default: null
        arguments:
          allOf:
          - $ref: '#/components/schemas/Tools.WikipediaSearchArguments'
          description: The arguments for Wikipedia Search
      allOf:
      - $ref: '#/components/schemas/Tools.BaseIntegrationDef'
      description: Wikipedia integration definition
    Tools.WikipediaSearchArguments:
      type: object
      required:
      - query
      - load_max_docs
      properties:
        query:
          type: string
          description: The search query string
        load_max_docs:
          type: integer
          format: uint8
          minimum: 1
          maximum: 10
          description: Maximum number of documents to load
          default: 2
      description: Arguments for Wikipedia Search
    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: number
          format: float
          minimum: 0
          maximum: 2
          description: Number between 0 and 2.0. 1.0 is neutral and values larger than that penalize number of tokens generated.
        min_p:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Minimum probability compared to leading token to be considered
        frequency_penalty:
          type: number
          format: float
          minimum: -2
          maximum: 2
          description: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
        presence_penalty:
          type: number
          format: float
          minimum: -2
          maximum: 2
          description: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
        temperature:
          type: number
          format: float
          minimum: 0
          maximum: 5
          description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
        top_p:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Defaults to 1 An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.  We generally recommend altering this or temperature but not both.
        metadata:
          type: object
          additionalProperties: {}
        auto_run_tools:
          type: boolean
          description: Whether to automatically run tools and send the results back to the model (requires tools or agents with tools).
          default: false
        recall_tools:
          type: boolean
          description: Whether to include tool requests and responses when recalling messages.
          default: true
      allOf:
      - $ref: '#/components/schemas/Chat.ChatInputData'
    Tools.RemoteBrowserSetup:
      type: object
      properties:
        connect_url:
          type: string
          description: The connection URL for the remote browser
        width:
          type: integer
          format: uint16
          description: The width of the browser
        height:
          type: integer
          format: uint16
          description: The height of the browser
      description: The setup parameters for the remote browser
    Sessions.VectorDocSearch:
      type: object
      required:
      - mode
      - confidence
      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
          maximum: 1
          exclusiveMaximum: true
          description: MMR Strength (mmr_strength = 1 - mmr_lambda)
          default: 0.5
      allOf:
      - $ref: '#/components/schemas/Sessions.BaseDocSearch'
    Tools.TextEditor20241022Def:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - text_editor_20241022
          default: text_editor_20241022
        name:
          type: string
          default: str_replace_editor
    Tools.McpSetup:
      type: object
      required:
      - transport
      properties:
        transport:
          type: string
          enum:
          - sse
          - http
          description: Transport used to connect to the MCP server
        command:
          type: string
          description: (stdio) Executable or command to launch the server
        args:
          type: array
          items:
            type: string
          description: (stdio) Arguments for the server command
          default: []
        cwd:
          type: string
          description: (stdio) Working directory for the server process
        env:
          type: object
          additionalProperties:
            type: string
          description: (stdio) Environment variables for the server process
          default: {}
        http_url:
          type: string
          format: uri
          description: (http) Base URL for the MCP server (usually ends with /mcp)
        http_headers:
          type: object
          additionalProperties:
            type: string
          description: (http) Optional HTTP headers to include (e.g., Authorization)
          default: {}
      description: Setup parameters for MCP integration
    Tools.BrowserbaseCreateSessionArguments:
      type: object
      properties:
        projectId:
          type: string
          description: The Project ID. Can be found in Settings.
        extensionId:
          type: string
          description: The installed Extension ID. See Install Extension from GitHub.
        browserSettings:
          type: object
          additionalProperties: {}
          description: Browser settings
          default: {}
        timeout:
          type: integer
          format: uint16
          description: Duration in seconds after which the session will automatically end. Defaults to the Project's defaultTimeout.
          default: 3600
        keepAlive:
          type: boolean
          description: Set to true to keep the session alive even after disconnections. This is available on the Startup plan only.
          default: false
        proxies:
          anyOf:
          - type: boolean
          - type: array
            items:
              type: object
              additionalProperties: {}
          description: Proxy configuration. Can be true for default proxy, or an array of proxy configurations.
          default: false
    Tools.McpCallToolArguments:
      type: object
      required:
      - tool_name
      properties:
        tool_name:
          type: string
          description: The MCP tool name to invoke
        arguments:
          type: object
          additionalProperties: {}
          description: JSON-serializable arguments to pass to the MCP tool
          default: {}
        timeout_seconds:
          type: integer
          format: uint16
          description: Optional per-call timeout in seconds
          default: 60
      description: Arguments to call a named tool on the MCP server
    Tools.SecretRef:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the secret to reference
    Sessions.ContextOverflowType:
      type: string
      enum:
      - truncate
      - adaptive
    Tools.GoogleSheetsSetup:
      type: object
      required:
      - use_julep_service
      properties:
        use_julep_service:
          type: boolean
          description: 'Whether to use Julep''s built-in Google Sheets service account.

            If true, no credentials needed. If false, service_account_json is required.'
        service_account_json:
          type: string
          description: 'Base64 encoded service account JSON for authentication.

            Required when use_julep_service is false.

            Users can provide their own service account for better isolation and quota management.'
        default_retry_count:
          type: integer
          format: uint8
          minimum: 1
          maximum: 10
          description: Default number of retry attempts for API calls
          default: 3
      description: Setup parameters for Google Sheets integration
    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
    Entries.Entry:
      type: object
      required:
      - created_at
      - id
      properties:
        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/Entries.BaseEntry'
    Tools.ChosenTextEditor20241022:
      type: object
      required:
      - command
      - path
      properties:
        command:
          type: string
          enum:
          - str_replace
          - insert
          - view
          - undo_edit
          description: The command to run
        path:
          type: string
          description: The path to the file
        file_text:
          type: string
          description: The content of the file to be created
        insert_line:
          type: integer
          format: uint16
          description: The line to insert the new string after
        new_str:
          type: string
          description: The new string to insert
        old_str:
          type: string
          description: The string in the file to replace
        view_range:
          type: array
          items:
            type: integer
            format: uint16
          description: The line range to view
    Docs.Snippet:
      type: object
      required:
      - index
      - content
      properties:
        index:
          type: integer
          format: uint16
        content:
          type: string
        embedding:
          type: array
          items:
            type: number
    Tools.AlgoliaSearchArguments:
      type: object
      required:
      - index_name
      - query
      properties:
        index_name:
          type: string
          description: The index name to search
        query:
          type: string
          description: The query to search for
        attributes_to_retrieve:
          type: array
          items:
            type: string
          description: Optional attributes to retrieve
        hits_per_page:
          type: integer
          format: int32
          minimum: 1
          maximum: 1000
          description: Maximum number of hits to return
          default: 10
      description: Arguments for Algolia Search
    Chat.ChunkChatResponse:
      type: object
      required:
      - choices
      properties:
        choices:
          type: array
          items:
            $ref: '#/components/schemas/Chat.ChatOutputChunk'
          description: The deltas generated by the model
      allOf:
      - $ref: '#/components/schemas/Chat.BaseChatResponse'
    Chat.LogProbResponse:
      type: object
      required:
      - content
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Chat.TokenLogProb'
          nullable: true
          description: The log probabilities of the tokens
    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
    Tools.CloudinaryUploadIntegrationDef:
      type: object
      required:
      - method
      properties:
        method:
          type: string
          enum:
          - media_upload
          default: media_upload
        arguments:
          $ref: '#/components/schemas/Tools.CloudinaryUploadArguments'
      allOf:
      - $ref: '#/components/schemas/Tools.BaseCloudinaryIntegrationDef'
      description: Cloudinary upload integration definition
    Tools.BrowserbaseGetSessionIntegrationDef:
      type: object
      required:
      - method
      properties:
        method:
          type: string
          enum:
          - get_session
          default: get_session
        arguments:
          $ref: '#/components/schemas/Tools.BrowserbaseGetSessionArguments'
      allOf:
      - $ref: '#/components/schemas/Tools.BaseBrowserbaseIntegrationDef'
      description: browserbase get session integration definition
    Chat.ChatOutputChunk:
      type: object
      required:
      - delta
      properties:
        delta:
          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: stri

# --- 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