Skip to Content
API ReferenceSessions API

Sessions API

Create and manage stateful agent sessions for multi-turn interactions.

Overview

Sessions enable stateful interactions with agents, maintaining context across multiple requests. Use sessions for:

  • Multi-turn conversations
  • Workflows requiring state persistence
  • Interactive agents that build on previous inputs

Create Session

Initialize a new session with an agent.

POST /api/sessions

Request Body

{
  "agentId": "agent_123",
  "metadata": {
    "userId": "user_456",
    "context": "customer_support"
  }
}
FieldTypeRequiredDescription
agentIdstringYesID of the agent to create session with
metadataobjectNoOptional metadata for session tracking

Response

{
  "sessionId": "session_abc123xyz",
  "agentId": "agent_123",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Example

curl -X POST https://agents.zazmic.com/api/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123",
    "metadata": {"context": "demo"}
  }'

Get Session

Retrieve session details and history.

GET /api/sessions/:sessionId

Response

{
  "id": "session_abc123",
  "userId": "user_456",
  "agentId": "agent_123",
  "status": "active",
  "metadata": {
    "context": "demo"
  },
  "messageCount": 5,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z"
}

Example

curl https://agents.zazmic.com/api/sessions/session_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

List Sessions

Get all sessions for the authenticated user.

GET /api/sessions

Query Parameters

ParameterTypeDescription
statusstringFilter by status (active, completed, expired)
agentIdstringFilter by agent ID
limitnumberMax results (default: 50, max: 100)

Response

{
  "sessions": [
    {
      "id": "session_abc123",
      "agentId": "agent_123",
      "status": "active",
      "messageCount": 5,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 10
}

Update Session

Update session metadata or status.

PATCH /api/sessions/:sessionId

Request Body

{
  "status": "completed",
  "metadata": {
    "resolution": "issue_resolved"
  }
}

Delete Session

End and delete a session.

DELETE /api/sessions/:sessionId

Response

{
  "message": "Session deleted successfully"
}

Using Sessions with Chat

Sessions are commonly used with the Chat API for conversational experiences:

// 1. Create session
const { sessionId } = await fetch('/api/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ agentId: 'agent_123' })
}).then(r => r.json());
 
// 2. Send messages in session
const response = await fetch('/api/chat', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sessionId: sessionId,
    message: 'Hello, agent!'
  })
});
 
// 3. Stream response
const reader = response.body.getReader();
const decoder = new TextDecoder();
 
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
 
  const lines = decoder.decode(value).split('\n');
  for (const line of lines) {
    if (line.trim()) {
      const event = JSON.parse(line);
      console.log(event);
    }
  }
}

Session Lifecycle

  1. active - Session is open and accepting requests
  2. completed - Session was explicitly ended
  3. expired - Session timed out (24 hours of inactivity)

Billing

Sessions are charged per message/interaction, not for session creation. See agent-specific pricing for details.

Error Responses

Session Not Found

{
  "error": "Not found",
  "message": "Session not found",
  "statusCode": 404
}

Session Expired

{
  "error": "Session expired",
  "message": "This session has expired. Please create a new session.",
  "statusCode": 410
}

Best Practices

  • Clean up: Delete sessions when done to prevent clutter
  • Metadata: Use metadata for tracking and analytics
  • Timeout handling: Check for expired sessions before use
  • Error recovery: Create new session if current expires

Next Steps

Error ReferenceTasks API