v0.4 (preview)
GitHub ⭐

Sessions

API for creating and modifying Sessions

List sessions

List sessions

List sessions created (use limit/offset pagination to get large number of sessions; sorted by descending order of created_at by default)

GEThttps://api-alpha.julep.ai/api/sessions
Authorization
Query parameters
Response

List of sessions (sorted created_at descending order) with limit+offset pagination

Body
items*array of Session (object)
Request
const response = await fetch('https://api-alpha.julep.ai/api/sessions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();
Response
{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "agent_id": "123e4567-e89b-12d3-a456-426614174000",
      "situation": "text",
      "summary": "text",
      "created_at": "2024-09-08T02:45:05.707Z",
      "updated_at": "2024-09-08T02:45:05.707Z",
      "metadata": {},
      "render_templates": false
    }
  ]
}

Create a new session

Create a new session

Create a session between an agent and a user

POSThttps://api-alpha.julep.ai/api/sessions
Authorization
Body

Session initialization options

user_idstring (uuid)

(Optional) User ID of user to associate with this session

agent_id*string (uuid)

Agent ID of agent to associate with this session

situationstring

A specific situation that sets the background for this session

metadataobject

Optional metadata

render_templatesboolean

Render system and assistant message content as jinja templates

Response

Session successfully created

Body
id*string (uuid)
created_at*string (date-time)
jobsarray of string (uuid)

IDs (if any) of jobs created as part of this request

Request
const response = await fetch('https://api-alpha.julep.ai/api/sessions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "agent_id": "123e4567-e89b-12d3-a456-426614174000"
    }),
});
const data = await response.json();
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-09-08T02:45:05.707Z",
  "jobs": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Get a specific session by id

Get details of the session

GEThttps://api-alpha.julep.ai/api/sessions/{session_id}
Authorization
Path parameters
session_id*string (uuid)
Response
Body
id*string (uuid)

Session id (UUID)

user_id*string (uuid)

User ID of user associated with this session

agent_id*string (uuid)

Agent ID of agent associated with this session

situationstring

A specific situation that sets the background for this session

summarystring

(null at the beginning) - generated automatically after every interaction

created_atstring (date-time)

Session created at (RFC-3339 format)

updated_atstring (date-time)

Session updated at (RFC-3339 format)

metadataobject

Optional metadata

render_templatesboolean

Render system and assistant message content as jinja templates

Request
const response = await fetch('https://api-alpha.julep.ai/api/sessions/{session_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "situation": "text",
  "summary": "text",
  "created_at": "2024-09-08T02:45:05.707Z",
  "updated_at": "2024-09-08T02:45:05.707Z",
  "metadata": {},
  "render_templates": false
}

Update a specific session by id

Update session parameters

PUThttps://api-alpha.julep.ai/api/sessions/{session_id}
Authorization
Path parameters
session_id*string (uuid)
Body
situation*string

Updated situation for this session

metadataobject

Optional metadata

Response
Body
id*string (uuid)
updated_at*string (date-time)
jobsarray of string (uuid)

IDs (if any) of jobs created as part of this request

Request
const response = await fetch('https://api-alpha.julep.ai/api/sessions/{session_id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "situation": "text"
    }),
});
const data = await response.json();
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "updated_at": "2024-09-08T02:45:05.707Z",
  "jobs": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Delete a specific session by id

Delete session

DELETEhttps://api-alpha.julep.ai/api/sessions/{session_id}
Authorization
Path parameters
session_id*string (uuid)
Response
Body
id*string (uuid)
deleted_at*string (date-time)
jobsarray of string (uuid)

IDs (if any) of jobs created as part of this request

Request
const response = await fetch('https://api-alpha.julep.ai/api/sessions/{session_id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "deleted_at": "2024-09-08T02:45:05.707Z",
  "jobs": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Chat

Interact with the session

POSThttps://api-alpha.julep.ai/api/sessions/{session_id}/chat
Authorization
Path parameters
session_id*string (uuid)
Header parameters
Body
messages*array of InputChatMLMessage (object)

A list of new input messages comprising the conversation so far.

toolsnullable array of Tool (object)

(Advanced) List of tools that are provided in addition to agent's default set of tools. Functions of same name in agent set are overriden

tool_choicenullable one of

Can be one of existing tools given to the agent earlier or the ones included in the request

frequency_penaltynullable number

(OpenAI-like) 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.

length_penaltynullable number

(Huggingface-like) Number between 0 and 2.0. 1.0 is neutral and values larger than that penalize number of tokens generated.

logit_biasnullable object

Modify the likelihood of specified tokens appearing in the completion.

Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.

max_tokensnullable integer

The maximum number of tokens to generate in the chat completion.

The total length of input tokens and generated tokens is limited by the model's context length.

presence_penaltynullable number

(OpenAI-like) 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.

repetition_penaltynullable number

(Huggingface-like) 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.

response_formatobject

An object specifying the format that the model must output.

Setting to { "type": "json_object" } enables JSON mode, which guarantees the message the model generates is valid JSON.

Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.

seednullable integer

This feature is in Beta. If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed, and you should refer to the system_fingerprint response parameter to monitor changes in the backend.

stopone of

Up to 4 sequences where the API will stop generating further tokens.

streamnullable boolean

If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a data: [DONE] message. Example Python code.

temperaturenullable number

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.

Example: 0.75
top_pnullable number

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.

Example: 1
min_pnumber

Minimum probability compared to leading token to be considered

Example: 0.01
presetenum

Generation preset name (problem_solving|conversational|fun|prose|creative|business|deterministic|code|multilingual)

problem_solvingconversationalfunprosecreativebusinessdeterministiccodemultilingual
recallboolean

Whether previous memories should be recalled or not

recordboolean

Whether this interaction should be recorded in history or not

rememberboolean

Whether this interaction should form memories or not

Response
Body
id*string (uuid)

A unique identifier for the chat completion.

finish_reason*enum

The reason the model stopped generating tokens. This will be stop if the model hit a natural stop point or a provided stop sequence, length if the maximum number of tokens specified in the request was reached, content_filter if content was omitted due to a flag from our content filters, tool_calls if the model called a tool, or function_call (deprecated) if the model called a function.

stoplengthtool_callscontent_filterfunction_call
response*array of array of ChatMLMessage (object)

A list of chat completion messages produced as a response.

usage*CompletionUsage (object)

Usage statistics for the completion request.

jobsarray of string (uuid)

IDs (if any) of jobs created as part of this request

Request
const response = await fetch('https://api-alpha.julep.ai/api/sessions/{session_id}/chat', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "messages": [
        {
          "content": "text",
          "role": "user"
        }
      ]
    }),
});
const data = await response.json();
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "finish_reason": "stop",
  "response": [
    [
      {
        "role": "user",
        "content": "text",
        "name": "text",
        "created_at": "2024-09-08T02:45:05.707Z",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  ],
  "usage": {},
  "jobs": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Get suggestions made by the agent based on the session

Get autogenerated suggestions for session user and agent

Sorted (created_at descending)

GEThttps://api-alpha.julep.ai/api/sessions/{session_id}/suggestions
Authorization
Path parameters
session_id*string (uuid)
Query parameters
Response
Body
itemsarray of Suggestion (object)
Request
const response = await fetch('https://api-alpha.julep.ai/api/sessions/{session_id}/suggestions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();
Response
{
  "items": [
    {
      "created_at": "2024-09-08T02:45:05.707Z",
      "target": "user",
      "content": "text",
      "message_id": "123e4567-e89b-12d3-a456-426614174000",
      "session_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Get a session's chat history

Get all messages in a session

Sorted (created_at ascending)

GEThttps://api-alpha.julep.ai/api/sessions/{session_id}/history
Authorization
Path parameters
session_id*string (uuid)
Query parameters
Response
Body
itemsarray of ChatMLMessage (object)
Request
const response = await fetch('https://api-alpha.julep.ai/api/sessions/{session_id}/history', {
    method: 'GET',
    headers: {},
});
const data = await response.json();
Response
{
  "items": [
    {
      "role": "user",
      "content": "text",
      "name": "text",
      "created_at": "2024-09-08T02:45:05.707Z",
      "id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}
PreviousUsersNextMemories

Last updated