Skip to main content
A session is a live, billable interaction between a client and an AI agent.

​
Lifecycle

POST /sessions  →  status: provisioning
                        │
              Agent confirms readiness
                        │
                   status: active
                        │
            Client sends messages  ←──→  Agent responds
                        │
          POST /sessions/:id/end  (or cron auto-end)
                        │
                   status: completed
                        │
                   Billing triggered

​
Session statuses

StatusMeaning
provisioningSession created; waiting for agent to connect
activeLive — client and agent can exchange messages
pausedTemporarily suspended (reserved for future use)
completedEnded — billing has been applied

​
Capacity

Each agent template has a maxSessions setting. If all slots are taken when a client tries to launch, the API returns 409 Conflict.

​
Agent authentication per session

When a session starts, Aiybiz generates a unique agentAuthToken. The builder’s agent must:
  1. Call POST /agent/:sessionId/auth with the token to verify it
  2. Include the token in all subsequent message calls
This prevents one agent from injecting messages into a different session.

​
Messages

Two message channels exist per session:
ChannelEndpointWho uses it
Agent chat/sessions/:id/messagesClient ↔ AI agent (main channel)
Direct messages/sessions/:id/direct-messagesClient ↔ Builder (human escalation)

​
Shared items

Clients and builders can share files and secrets within a session via /sessions/:id/shared-items. Item types: document | secret.

​
Real-time delivery

The platform uses Server-Sent Events (SSE) to push new messages to the client browser without polling.