curl --request POST \
--url https://api.example.com/sessions/ \
--header 'Content-Type: application/json' \
--header 'x-user-id: <x-user-id>' \
--data '
{
"agent_id": "<string>",
"workspace_id": "<string>",
"name": "<string>",
"chat_model_config": {
"type": "<string>",
"credential_id": "<string>",
"model": "<string>",
"parameters": {}
},
"fallback_chat_model_config": {
"type": "<string>",
"credential_id": "<string>",
"model": "<string>",
"parameters": {}
}
}
'import requests
url = "https://api.example.com/sessions/"
payload = {
"agent_id": "<string>",
"workspace_id": "<string>",
"name": "<string>",
"chat_model_config": {
"type": "<string>",
"credential_id": "<string>",
"model": "<string>",
"parameters": {}
},
"fallback_chat_model_config": {
"type": "<string>",
"credential_id": "<string>",
"model": "<string>",
"parameters": {}
}
}
headers = {
"x-user-id": "<x-user-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-user-id': '<x-user-id>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '<string>',
workspace_id: '<string>',
name: '<string>',
chat_model_config: {type: '<string>', credential_id: '<string>', model: '<string>', parameters: {}},
fallback_chat_model_config: {type: '<string>', credential_id: '<string>', model: '<string>', parameters: {}}
})
};
fetch('https://api.example.com/sessions/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/sessions/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => '<string>',
'workspace_id' => '<string>',
'name' => '<string>',
'chat_model_config' => [
'type' => '<string>',
'credential_id' => '<string>',
'model' => '<string>',
'parameters' => [
]
],
'fallback_chat_model_config' => [
'type' => '<string>',
'credential_id' => '<string>',
'model' => '<string>',
'parameters' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-user-id: <x-user-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/sessions/"
payload := strings.NewReader("{\n \"agent_id\": \"<string>\",\n \"workspace_id\": \"<string>\",\n \"name\": \"<string>\",\n \"chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n },\n \"fallback_chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-user-id", "<x-user-id>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/sessions/")
.header("x-user-id", "<x-user-id>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": \"<string>\",\n \"workspace_id\": \"<string>\",\n \"name\": \"<string>\",\n \"chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n },\n \"fallback_chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/sessions/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-user-id"] = '<x-user-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"<string>\",\n \"workspace_id\": \"<string>\",\n \"name\": \"<string>\",\n \"chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n },\n \"fallback_chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n }\n}"
response = http.request(request)
puts response.read_body{
"session_id": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Create a new session
Create (or resume) a session for a given agent and workspace.
At most one session exists per (user_id, agent_id, workspace_id)
triple — a second call with the same triple updates the existing session
rather than creating a duplicate.
Args:
body (CreateSessionRequest): Agent, workspace, and model config.
user_id (str): Injected authenticated user ID.
storage (StorageBase): Injected storage backend.
Returns:
CreateSessionResponse: The session identifier.
Raises:
HTTPException: 404 if the agent or credential does not exist or
does not belong to the authenticated user.
curl --request POST \
--url https://api.example.com/sessions/ \
--header 'Content-Type: application/json' \
--header 'x-user-id: <x-user-id>' \
--data '
{
"agent_id": "<string>",
"workspace_id": "<string>",
"name": "<string>",
"chat_model_config": {
"type": "<string>",
"credential_id": "<string>",
"model": "<string>",
"parameters": {}
},
"fallback_chat_model_config": {
"type": "<string>",
"credential_id": "<string>",
"model": "<string>",
"parameters": {}
}
}
'import requests
url = "https://api.example.com/sessions/"
payload = {
"agent_id": "<string>",
"workspace_id": "<string>",
"name": "<string>",
"chat_model_config": {
"type": "<string>",
"credential_id": "<string>",
"model": "<string>",
"parameters": {}
},
"fallback_chat_model_config": {
"type": "<string>",
"credential_id": "<string>",
"model": "<string>",
"parameters": {}
}
}
headers = {
"x-user-id": "<x-user-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-user-id': '<x-user-id>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '<string>',
workspace_id: '<string>',
name: '<string>',
chat_model_config: {type: '<string>', credential_id: '<string>', model: '<string>', parameters: {}},
fallback_chat_model_config: {type: '<string>', credential_id: '<string>', model: '<string>', parameters: {}}
})
};
fetch('https://api.example.com/sessions/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/sessions/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => '<string>',
'workspace_id' => '<string>',
'name' => '<string>',
'chat_model_config' => [
'type' => '<string>',
'credential_id' => '<string>',
'model' => '<string>',
'parameters' => [
]
],
'fallback_chat_model_config' => [
'type' => '<string>',
'credential_id' => '<string>',
'model' => '<string>',
'parameters' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-user-id: <x-user-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/sessions/"
payload := strings.NewReader("{\n \"agent_id\": \"<string>\",\n \"workspace_id\": \"<string>\",\n \"name\": \"<string>\",\n \"chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n },\n \"fallback_chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-user-id", "<x-user-id>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/sessions/")
.header("x-user-id", "<x-user-id>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": \"<string>\",\n \"workspace_id\": \"<string>\",\n \"name\": \"<string>\",\n \"chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n },\n \"fallback_chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/sessions/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-user-id"] = '<x-user-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"<string>\",\n \"workspace_id\": \"<string>\",\n \"name\": \"<string>\",\n \"chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n },\n \"fallback_chat_model_config\": {\n \"type\": \"<string>\",\n \"credential_id\": \"<string>\",\n \"model\": \"<string>\",\n \"parameters\": {}\n }\n}"
response = http.request(request)
puts response.read_body{
"session_id": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Headers
Caller's user ID. Temporary header-based identity; will be replaced by JWT auth.
Body
Request body for creating a new session.
Agent this session belongs to.
Workspace this session belongs to.
Display name. Defaults to current datetime if omitted.
Model provider and parameters. Can be set later via PATCH.
Show child attributes
Show child attributes
Fallback model used when the primary model fails. Can be set later via PATCH.
Show child attributes
Show child attributes
Response
Successful Response
Response body after creating a session.
Server-assigned session identifier.