Julep Tasks API

openapi: 3.0.0
info:
  title: Julep Agents Tasks 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: Tasks
paths:
  /tasks/{id}:
    get:
      operationId: TasksGetRoute_get
      description: Get a task 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/Tasks.Task'
      tags:
      - Tasks
  /tasks/{id}/executions:
    post:
      operationId: TaskExecutionsRoute_create
      description: Create an execution for the given task
      parameters:
      - name: id
        in: path
        required: true
        description: ID of parent resource
        schema:
          $ref: '#/components/schemas/Common.uuid'
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Executions.Execution'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Executions.CreateExecutionRequest'
      tags:
      - Tasks
    get:
      operationId: TaskExecutionsRoute_list
      description: List executions of the given task
      parameters:
      - name: id
        in: path
        required: true
        description: ID of parent
        schema:
          $ref: '#/components/schemas/Common.uuid'
      - $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/Executions.Execution'
                required:
                - items
      tags:
      - Tasks
components:
  schemas:
    Executions.Execution:
      type: object
      required:
      - task_id
      - status
      - input
      - created_at
      - updated_at
      - id
      properties:
        task_id:
          allOf:
          - $ref: '#/components/schemas/Common.uuid'
          readOnly: true
          description: The ID of the task that the execution is running
        status:
          type: string
          enum:
          - queued
          - starting
          - running
          - awaiting_input
          - succeeded
          - failed
          - cancelled
          description: The status of the execution
          readOnly: true
        input:
          type: object
          additionalProperties: {}
          description: The input to the execution
        output:
          description: The output of the execution if it succeeded
        error:
          type: string
          description: The error of the execution if it failed
        transition_count:
          type: integer
          format: uint8
          description: The number of transitions in this execution
        created_at:
          type: string
          format: date-time
          description: When this resource was created as UTC date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: When this resource was updated as UTC date-time
          readOnly: true
        metadata:
          type: object
          additionalProperties: {}
        id:
          allOf:
          - $ref: '#/components/schemas/Common.uuid'
          readOnly: true
    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
    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
    Tasks.ReturnStep:
      type: object
      required:
      - kind_
      - return
      properties:
        kind_:
          type: string
          enum:
          - return
          default: return
          readOnly: true
        return:
          type: object
          additionalProperties:
            anyOf:
            - $ref: '#/components/schemas/Common.PyExpression'
            - type: array
              items:
                $ref: '#/components/schemas/Common.PyExpression'
            - type: object
              additionalProperties:
                $ref: '#/components/schemas/Common.PyExpression'
            - type: array
              items:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Common.PyExpression'
          description: The value to return
      allOf:
      - type: object
        required:
        - kind_
        properties:
          kind_:
            type: string
            enum:
            - return
            description: The kind of step
            readOnly: true
          label:
            allOf:
            - $ref: '#/components/schemas/Common.stepLabel'
            description: The label of this step for referencing it from other steps
        discriminator:
          propertyName: kind_
          mapping: {}
    Common.stepLabel:
      type: string
      maxLength: 120
      pattern: ^[^0-9]|^[0-9]+[^0-9].*$
      description: A valid step label
    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
    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
    Tasks.CaseThen:
      type: object
      required:
      - case
      - then
      properties:
        case:
          anyOf:
          - $ref: '#/components/schemas/Common.PyExpression'
          - type: string
            enum:
            - _
          description: The condition to evaluate
        then:
          anyOf:
          - $ref: '#/components/schemas/Tasks.EvaluateStep'
          - $ref: '#/components/schemas/Tasks.ToolCallStep'
          - $ref: '#/components/schemas/Tasks.PromptStep'
          - $ref: '#/components/schemas/Tasks.GetStep'
          - $ref: '#/components/schemas/Tasks.SetStep'
          - $ref: '#/components/schemas/Tasks.LogStep'
          - $ref: '#/components/schemas/Tasks.YieldStep'
          - $ref: '#/components/schemas/Tasks.ReturnStep'
          - $ref: '#/components/schemas/Tasks.SleepStep'
          - $ref: '#/components/schemas/Tasks.ErrorWorkflowStep'
          - $ref: '#/components/schemas/Tasks.WaitForInputStep'
          description: The steps to run if the condition is true
    Common.PyExpression:
      type: string
      description: A simple python expression compatible with SimpleEval.
    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
    Tasks.TaskTool:
      type: object
      properties:
        inherited:
          type: boolean
          description: 'Read-only: Whether the tool was inherited or not. Only applies within tasks.'
          default: false
          readOnly: true
      allOf:
      - $ref: '#/components/schemas/Tools.CreateToolRequest'
    Tasks.LogStep:
      type: object
      required:
      - kind_
      - log
      properties:
        kind_:
          type: string
          enum:
          - log
          default: log
          readOnly: true
        log:
          allOf:
          - $ref: '#/components/schemas/Common.JinjaTemplate'
          description: The value to log
      allOf:
      - type: object
        required:
        - kind_
        properties:
          kind_:
            type: string
            enum:
            - log
            description: The kind of step
            readOnly: true
          label:
            allOf:
            - $ref: '#/components/schemas/Common.stepLabel'
            description: The label of this step for referencing it from other steps
        discriminator:
          propertyName: kind_
          mapping: {}
    Tools.SecretRef:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the secret to reference
    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
    Tasks.ToolCallStep:
      type: object
      required:
      - kind_
      - tool
      - arguments
      properties:
        kind_:
          type: string
          enum:
          - tool_call
          default: tool_call
          readOnly: true
        tool:
          allOf:
          - $ref: '#/components/schemas/Common.validPythonIdentifier'
          description: The tool to run
        arguments:
          anyOf:
          - type: object
            additionalProperties: {}
          - type: string
            enum:
            - _
          description: The input parameters for the tool (defaults to last step output)
          default: _
      allOf:
      - type: object
        required:
        - kind_
        properties:
          kind_:
            type: string
            enum:
            - tool_call
            description: The kind of step
            readOnly: true
          label:
            allOf:
            - $ref: '#/components/schemas/Common.stepLabel'
            description: The label of this step for referencing it from other steps
        discriminator:
          propertyName: kind_
          mapping: {}
    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
    Tasks.PromptStep:
      type: object
      required:
      - kind_
      - prompt
      - tools
      - auto_run_tools
      - disable_cache
      properties:
        kind_:
          type: string
          enum:
          - prompt
          default: prompt
          readOnly: true
        prompt:
          anyOf:
          - $ref: '#/components/schemas/Common.JinjaTemplate'
          - type: array
            items:
              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:
                  - $ref: '#/components/schemas/Common.JinjaTemplate'
                  - type: array
                    items:
                      $ref: '#/components/schemas/Common.JinjaTemplate'
                  - type: array
                    items:
                      anyOf:
                      - type: object
                        required:
                        - text
                        - type
                        properties:
                          text:
                            $ref: '#/components/schemas/Common.JinjaTemplate'
                          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:
                                    $ref: '#/components/schemas/Common.JinjaTemplate'
                                  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:
                                        $ref: '#/components/schemas/Common.JinjaTemplate'
                        description: Anthropic image content part
                  nullable: true
                  description: The content parts of the message
                name:
                  type: string
                  description: Name
                tool_calls:
                  type: array
                  items:
                    anyOf:
                    - $ref: '#/components/schemas/Tools.ChosenFunctionCall'
                    - $ref: '#/components/schemas/Tools.ChosenComputer20241022'
                    - $ref: '#/components/schemas/Tools.ChosenTextEditor20241022'
                    - $ref: '#/components/schemas/Tools.ChosenBash20241022'
                  nullable: true
                  description: Tool calls generated by the model.
                  default: []
          description: The prompt to run
        tools:
          anyOf:
          - type: string
            enum:
            - all
          - type: array
            items:
              anyOf:
              - $ref: '#/components/schemas/Tasks.ToolRef'
              - $ref: '#/components/schemas/Tools.CreateToolRequest'
          description: The tools to use for the prompt
          default: all
        tool_choice:
          anyOf:
          - type: string
            enum:
            - auto
            - none
          - $ref: '#/components/schemas/Tools.NamedToolChoice'
          description: The tool choice for the prompt
        settings:
          type: object
          additionalProperties: {}
          description: Settings for the prompt
        unwrap:
          type: boolean
          description: Whether to unwrap the output of the prompt step, equivalent to `response.choices[0].message.content`
          default: false
        auto_run_tools:
          type: boolean
          description: 'Whether to auto-run the tool and send the tool results to the model when available.

            (default: false)


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

            If a tool call is not made, the model''s output will be used as the next step''s input.'
          default: false
        disable_cache:
          type: boolean
          description: Whether to disable caching for the prompt step
          default: false
      allOf:
      - type: object
        required:
        - kind_
        properties:
          kind_:
            type: string
            enum:
            - prompt
            description: The kind of step
            readOnly: true
          label:
            allOf:
            - $ref: '#/components/schemas/Common.stepLabel'
            description: The label of this step for referencing it from other steps
        discriminator:
          propertyName: kind_
          mapping: {}
    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
    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
    Tools.RemoteBrowserIntegrationDef:
      type: object
      required:
      - provider
      - setup
      - method
      properties:
        provider:
          type: string
          enum:
          - remote_browser
          default: remote_browser
        setup:
          $ref: '#/components/schemas/Tools.RemoteBrowserSetup'
        method:
          type: string
          enum:
          - perform_action
          default: perform_action
        arguments:
          $ref: '#/components/schemas/Tools.RemoteBrowserArguments'
      allOf:
      - $ref: '#/components/schemas/Tools.BaseIntegrationDef'
      description: The integration definition for the remote browser
    Tools.ChosenBash20241022:
      type: object
      properties:
        command:
          type: string
          description: The bash command to run
        restart:
          type: boolean
          description: Whether to restart the tool
          default: false
    Tools.AlgoliaSetup:
      type: object
      required:
      - algolia_application_id
      - algolia_api_key
      properties:
        algolia_application_id:
          type: string
          description: The Algolia Application ID
        algolia_api_key:
          type: string
          description: The Algolia API Key
      description: Integration definition for Algolia
    Tools.BrowserbaseCompleteSessionIntegrationDef:
      type: object
      required:
      - method
      properties:
        method:
          type: string
          enum:
          - complete_session
          default: complete_session
        arguments:
          $ref: '#/components/schemas/Tools.BrowserbaseCompleteSessionArguments'
      allOf:
      - $ref: '#/components/schemas/Tools.BaseBrowserbaseIntegrationDef'
      description: browserbase complete session integration definition
    Tasks.WaitForInputInfo:
      type: object
      required:
      - info
      properties:
        info:
          type: object
          additionalProperties:
            anyOf:
            - $ref: '#/components/schemas/Common.PyExpression'
            - type: array
              items:
                $ref: '#/components/schemas/Common.PyExpression'
            - type: object
              additionalProperties:
                $ref: '#/components/schemas/Common.PyExpression'
            - type: array
              items:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Common.PyExpression'
          description: Any additional info or data
    Tools.McpIntegrationDef:
      type: object
      required:
      - provider
      properties:
        provider:
          type: string
          enum:
          - mcp
          description: The provider must be "mcp"
          default: mcp
        method:
          type: string
          description: The specific method of the integration to call
        setup:
          allOf:
          - $ref: '#/components/schemas/Tools.McpSetup'
          description: The setup parameters for MCP
        arguments:
          anyOf:
          - $ref: '#/components/schemas/Tools.McpCallToolArguments'
          - $ref: '#/components/schemas/Tools.McpListToolsArguments'
          description: The arguments for MCP methods
      allOf:
      - $ref: '#/components/schemas/Tools.BaseIntegrationDef'
      description: MCP integration definition
    Executions.CreateExecutionRequest:
      type: object
      required:
      - input
      properties:
        input:
          type: object
          additionalProperties: {}
          description: 

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