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 recent sessions with pagination.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| limit | integer | Optional | Number of results per page.(default: 20) |
bash
curl -s "https://agentinbox.in/api/v1/sessions?limit=20" \ -H "Authorization: Bearer $AGENTINBOX_API_KEY"typescript
const sessions = await client.sessions.list({ limit: 20,}); console.log(sessions.data.length);python
sessions = client.sessions.list(limit=20)print(len(sessions))Responses
HTTP 200
{ "object": "list", "data": [ { "id": "sess_789", "name": "user-signup-flow", "status": "active", "createdAt": "2024-06-12T10:00:00Z" } ], "hasMore": false}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/00000000-0000-4000-8000-000000000004?include=inboxes,waits" \ -H "Authorization: Bearer $AGENTINBOX_API_KEY"typescript
const detail = await client.sessions.get("00000000-0000-4000-8000-000000000004", { include: ["inboxes", "waits"],});console.log(detail.session.status, detail.inboxes, detail.waits);python
detail = client.sessions.get("00000000-0000-4000-8000-000000000004", include=["inboxes", "waits"])print(detail["session"]["status"], detail.get("inboxes"), detail.get("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}Mark 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/00000000-0000-4000-8000-000000000004?include=timeline" \ -H "Authorization: Bearer $AGENTINBOX_API_KEY"typescript
const detail = await client.sessions.get("00000000-0000-4000-8000-000000000004", { include: ["timeline"],});console.log(detail.timeline);python
detail = client.sessions.get("00000000-0000-4000-8000-000000000004", include=["timeline"])print(detail.get("timeline"))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 expired when their TTL elapses.
Schema: Session
The Session object tracks a workflow's lifecycle and groups related resources.
Session Object
{ "id": string, "name": string, "status": "active" | "completed" | "expired", "createdAt": string, "updatedAt": string, "completedAt": string | null, "metadata": object, "inboxes": string[], "waits": string[]}