API Reference: Sessions
Complete reference for the Sessions API including endpoints, request/response schemas, and examples.
Authentication
All session endpoints require a valid API key passed in the
Authorization header as Bearer <token>.POST
/api/v1/sessionsCreate a new session to track a workflow or automation. Sessions group related inboxes and waits.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Required | A descriptive name for the session. |
| metadata | object | Optional | User-defined key-value pairs for tracking or tagging. |
bash
curl -X POST https://agentinbox.in/api/v1/sessions \ -H "Authorization: Bearer $AgentInbox_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "user-signup-flow", "metadata": { "environment": "staging" } }'typescript
const session = await client.sessions.create({ name: "user-signup-flow", metadata: { environment: "staging" },}); console.log(session.id); // "sess_789"python
session = client.sessions.create( name="user-signup-flow", metadata={"environment": "staging"},) print(session.id) # "sess_789"Responses
HTTP 201
{ "id": "sess_789", "name": "user-signup-flow", "status": "active", "createdAt": "2024-06-12T10:00:00Z", "updatedAt": "2024-06-12T10:00:00Z", "completedAt": null, "metadata": { "environment": "staging" }, "inboxes": [], "waits": []}HTTP 400
{ "error": "Invalid request", "message": "name is required"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 500
{ "error": "Internal server error", "message": "Failed to create session"}GET
/api/v1/sessionsList all sessions with pagination. Filter by status to find active or completed sessions.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| limit | integer | Optional | Number of results per page.(default: 20) |
| offset | integer | Optional | Number of results to skip.(default: 0) |
| status | string | Optional | Filter by session status. One of active, completed, or failed. |
bash
curl -s "https://agentinbox.in/api/v1/sessions?status=active&limit=20" \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
const sessions = await client.sessions.list({ status: "active", limit: 20, offset: 0,}); console.log(sessions.data.length);python
sessions = client.sessions.list(status="active", limit=20, offset=0)print(len(sessions.data))Responses
HTTP 200
{ "data": [ { "id": "sess_789", "name": "user-signup-flow", "status": "active", "createdAt": "2024-06-12T10:00:00Z" } ], "pagination": { "limit": 20, "offset": 0, "total": 5 }}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 500
{ "error": "Internal server error", "message": "Failed to list sessions"}GET
/api/v1/sessions/{id}Retrieve a session with its associated inboxes and waits.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique session ID. |
bash
curl -s https://agentinbox.in/api/v1/sessions/sess_789 \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
const session = await client.sessions.get("sess_789");console.log(session.status, session.inboxes, session.waits);python
session = client.sessions.get("sess_789")print(session.status, session.inboxes, session.waits)Responses
HTTP 200
{ "id": "sess_789", "name": "user-signup-flow", "status": "active", "createdAt": "2024-06-12T10:00:00Z", "updatedAt": "2024-06-12T10:02:31Z", "completedAt": null, "metadata": {}, "inboxes": ["inb_123"], "waits": ["wait_456"]}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Session not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to retrieve session"}POST
/api/v1/sessions/{id}/completeMark a session as completed. This sets the status to completed and records the completion timestamp.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique session ID to complete. |
Responses
HTTP 200
{ "id": "sess_789", "status": "completed", "completedAt": "2024-06-12T10:05:00Z"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Session not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to complete session"}GET
/api/v1/sessions/{id}/timelineGet the event timeline for a session. Useful for debugging and replaying workflows.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique session ID. |
bash
curl -s https://agentinbox.in/api/v1/sessions/sess_789/timeline \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
const timeline = await client.sessions.timeline("sess_789");console.log(timeline.events);python
timeline = client.sessions.timeline("sess_789")print(timeline.events)Responses
HTTP 200
{ "events": [ { "timestamp": "2024-06-12T10:00:00Z", "type": "session.created", "payload": { "sessionId": "sess_789" } }, { "timestamp": "2024-06-12T10:00:01Z", "type": "inbox.created", "payload": { "inboxId": "inb_123" } }, { "timestamp": "2024-06-12T10:02:30Z", "type": "message.received", "payload": { "messageId": "msg_456" } }, { "timestamp": "2024-06-12T10:02:31Z", "type": "wait.completed", "payload": { "waitId": "wait_456" } } ]}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Session not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to retrieve timeline"}POST
/api/v1/sessions/{id}/replayReplay a session's execution to debug or re-run workflows.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique session ID to replay. |
Responses
HTTP 200
{ "steps": [ { "index": 0, "timestamp": "2024-06-12T10:00:00Z", "action": "create_inbox", "input": { "ttlSeconds": 3600 }, "output": { "id": "inb_123" }, "durationMs": 120 }, { "index": 1, "timestamp": "2024-06-12T10:00:01Z", "action": "create_wait", "input": { "type": "otp", "timeoutSeconds": 120 }, "output": { "id": "wait_456" }, "durationMs": 45 } ]}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Session not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to replay session"}Session Lifecycle
Sessions start as active. Use the complete endpoint when your workflow finishes. Sessions automatically transition to failed if a critical error occurs.
Schema: Session
The Session object tracks a workflow's lifecycle and groups related resources.
Session Object
{ "id": string, "name": string, "status": "active" | "completed" | "failed", "createdAt": string, "updatedAt": string, "completedAt": string | null, "metadata": object, "inboxes": string[], "waits": string[]}