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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
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
Client-provided session identifier. Use the same value across requests to continue the same agent session.
2 - 100^[0-9a-zA-Z._:-]+$Query Parameters
Wait up to this many seconds for the assistant response. Omit to wait up to 30 minutes; use 0 to return after the invocation is accepted.
0 <= x <= 1800Body
The user prompt driving this invocation.
Human-readable name identifying the agent (e.g. "support-triage"). Invocations sharing a name are grouped as one agent; each distinct configuration under it becomes a revision.
The agent configuration for an invocation: the model, tools, instructions, and MCP servers that define its behavior. Invocations with the same configuration share a revision.
Show child attributes
Show child attributes
Response
Session run or resumed
Show child attributes
Show child attributes
The assistant message this invocation produced. Absent when the invocation has not answered yet — a call with wait_timeout_seconds=0, or a wait that returned before the response existed. Use GET /sessions/{id} to read it later.
Show child attributes
Show child attributes