curl --request POST \
--url https://albus.sh/api/sessions/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_prompt": "<string>",
"agent_name": "<string>",
"agent": {
"model": {
"name": "<string>"
},
"tools": {
"web_search": {},
"terminal": {}
},
"system_prompt": "<string>",
"max_steps": 2,
"mcp_servers": [
{
"name": "<string>",
"url": "<string>",
"headers": {},
"allowed_tools": [
"<string>"
]
}
],
"output_format": {}
}
}
'import requests
url = "https://albus.sh/api/sessions/{id}"
payload = {
"user_prompt": "<string>",
"agent_name": "<string>",
"agent": {
"model": { "name": "<string>" },
"tools": {
"web_search": {},
"terminal": {}
},
"system_prompt": "<string>",
"max_steps": 2,
"mcp_servers": [
{
"name": "<string>",
"url": "<string>",
"headers": {},
"allowed_tools": ["<string>"]
}
],
"output_format": {}
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_prompt: '<string>',
agent_name: '<string>',
agent: {
model: {name: '<string>'},
tools: {web_search: {}, terminal: {}},
system_prompt: '<string>',
max_steps: 2,
mcp_servers: [{name: '<string>', url: '<string>', headers: {}, allowed_tools: ['<string>']}],
output_format: {}
}
})
};
fetch('https://albus.sh/api/sessions/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"session": {
"id": "<string>",
"state": "RUNNING",
"invocation_count": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"current_invocation_key": "<string>",
"agent_name": "<string>",
"agent_revision": "<string>"
},
"message": {
"cursor": 123,
"invocation_key": "<string>",
"role": "user",
"content": "<string>",
"created_at": "2023-11-07T05:31:56Z"
}
}{
"message": "Invalid request parameters"
}{
"message": "Invalid or expired token"
}{
"message": "Idempotency key reused with a different request body"
}{
"message": "Another invocation is currently running for this session"
}{
"message": "organization invocation quota exceeded"
}{
"message": "invocation failed (crash): signal 9",
"kind": "crash"
}{
"message": "Timed out waiting for the assistant response"
}Run or resume a session
Runs the session with the given ID, creating it if it does not exist and resuming it otherwise. Each call is a single invocation, optionally named by the Idempotency-Key header, whose value is the invocation’s key. Supplying a key makes the call safe to retry: retrying with the same key and an identical body re-attaches to the in-flight invocation and returns its current state; a differing body for the same key returns 409; a new key while another invocation is still running returns 423. Omitting the header starts a fresh, non-idempotent invocation each time; the server generates a key and returns it in the Idempotency-Key response header.
With wait_timeout_seconds the request long-polls: it blocks until the invocation’s assistant response is available and returns it in message. Omit it to wait up to 30 minutes, or pass 0 to return as soon as the invocation is accepted. A positive value bounds the wait in seconds; if it elapses first the request fails with 504 and a JSON body, letting the client distinguish an expected server-side timeout from a transport error; the client may retry.
curl --request POST \
--url https://albus.sh/api/sessions/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_prompt": "<string>",
"agent_name": "<string>",
"agent": {
"model": {
"name": "<string>"
},
"tools": {
"web_search": {},
"terminal": {}
},
"system_prompt": "<string>",
"max_steps": 2,
"mcp_servers": [
{
"name": "<string>",
"url": "<string>",
"headers": {},
"allowed_tools": [
"<string>"
]
}
],
"output_format": {}
}
}
'import requests
url = "https://albus.sh/api/sessions/{id}"
payload = {
"user_prompt": "<string>",
"agent_name": "<string>",
"agent": {
"model": { "name": "<string>" },
"tools": {
"web_search": {},
"terminal": {}
},
"system_prompt": "<string>",
"max_steps": 2,
"mcp_servers": [
{
"name": "<string>",
"url": "<string>",
"headers": {},
"allowed_tools": ["<string>"]
}
],
"output_format": {}
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_prompt: '<string>',
agent_name: '<string>',
agent: {
model: {name: '<string>'},
tools: {web_search: {}, terminal: {}},
system_prompt: '<string>',
max_steps: 2,
mcp_servers: [{name: '<string>', url: '<string>', headers: {}, allowed_tools: ['<string>']}],
output_format: {}
}
})
};
fetch('https://albus.sh/api/sessions/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"session": {
"id": "<string>",
"state": "RUNNING",
"invocation_count": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"current_invocation_key": "<string>",
"agent_name": "<string>",
"agent_revision": "<string>"
},
"message": {
"cursor": 123,
"invocation_key": "<string>",
"role": "user",
"content": "<string>",
"created_at": "2023-11-07T05:31:56Z"
}
}{
"message": "Invalid request parameters"
}{
"message": "Invalid or expired token"
}{
"message": "Idempotency key reused with a different request body"
}{
"message": "Another invocation is currently running for this session"
}{
"message": "organization invocation quota exceeded"
}{
"message": "invocation failed (crash): signal 9",
"kind": "crash"
}{
"message": "Timed out waiting for the assistant response"
}Authorizations
Headers
Optional but strongly encouraged. The key naming this invocation of the session, unique within your organization: reuse the same value to safely retry a request, read the invocation back with GET /traces/{invocation_key}, and use a new value to start a new invocation. When omitted, the server generates a key for the invocation and returns it in the Idempotency-Key response header, but the request is not retry-safe.
1 - 255Path Parameters
Query Parameters
Body
Response
Session run or resumed