Skip to main content
POST
/
api
/
messaging
/
sessions
Create a new session
curl --request POST \
  --url http://localhost:3000/api/messaging/sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": {
    "platform": "<string>",
    "username": "<string>",
    "discriminator": "<string>",
    "avatar": "<string>"
  },
  "timeoutConfig": {
    "timeoutMinutes": 722,
    "autoRenew": true,
    "maxDurationMinutes": 123,
    "warningThresholdMinutes": 123
  }
}
'
{
  "sessionId": "<string>",
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "metadata": {},
  "expiresAt": "2023-11-07T05:31:56Z",
  "timeoutConfig": {
    "timeoutMinutes": 123,
    "autoRenew": true,
    "maxDurationMinutes": 123,
    "warningThresholdMinutes": 123
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.elizaos.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Sessions API provides a simplified way to manage conversations without dealing with servers and channels. Sessions automatically handle timeout management, renewal, and expiration.

​
Request Body

​
agentId
string
required
UUID of the agent to create a session with
​
userId
string
required
UUID of the user initiating the session
​
metadata
object
Optional metadata to attach to the session
​
timeoutConfig
object
Optional timeout configuration for the session

​
Response

​
sessionId
string
Unique identifier for the created session
​
agentId
string
UUID of the agent
​
userId
string
UUID of the user
​
createdAt
string
ISO timestamp of session creation
​
expiresAt
string
ISO timestamp when the session will expire
​
timeoutConfig
object
The active timeout configuration for this session
​
metadata
object
Any metadata attached to the session

Body

application/json
​
agentId
string<uuid>
required

ID of the agent to start a session with

​
userId
string<uuid>
required

ID of the user creating the session

​
metadata
object

Additional metadata for the session

​
timeoutConfig
object

Optional timeout configuration for the session

Response

Session created successfully

​
sessionId
string

Unique identifier for the created session

​
agentId
string<uuid>
​
userId
string<uuid>
​
createdAt
string<date-time>
​
metadata
object
​
expiresAt
string<date-time>

When the session will expire

​
timeoutConfig
object

Active timeout configuration for the session