Skip to main content
POST
https://api.agenthuman.com
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.agenthuman.com/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "avatar_id": "<string>",
  "metadata": {}
}
'
{
  "success": true,
  "session": {
    "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
    "avatar": {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "name": "Professional Avatar (Look)",
      "url": "https://example.com/avatars/preview.jpg"
    },
    "session_type": "webrtc_video",
    "status": "created",
    "access_token": "access_token_xxxxxxxxxxxxx",
    "started_at": null,
    "ended_at": null,
    "expiration": null,
    "created_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "user_name": "John Doe",
      "session_purpose": "Customer Support"
    }
  },
  "usage": {
    "concurrency": {
      "current": 0,
      "max": 1,
      "available": 1
    },
    "minutes": {
      "total_remaining": 120
    }
  },
  "message": "Session created successfully"
}
What This Does: Creates a session with a Daily.co video room where your avatar will appear. The session starts in created status - call Start Session to activate the avatar server.

​
Body

​
avatar_id
string
required
The ID of the avatar to use for this session. Must be a look (an avatar with parent_id set). Characters (top-level avatars) cannot be used directly for sessions.
​
metadata
object
Optional metadata object to attach to the session. Must be a valid JSON object. Defaults to {} if not provided.

​
Response

​
success
boolean
Whether the session was created successfully
​
session
object
The created session object (See Session schema).
​
usage
object
Current usage snapshot (minutes + concurrency) returned by usage enforcement.
​
message
string
Success message

​
Important Notes

Session Lifecycle: Creating a session does not start it. The session is created in created status and will transition to started when you call the Start Session endpoint.
Daily.co Integration: Each session automatically gets a Daily.co video room created for video streaming. Use the daily_room.url and daily_room.token to connect to the video session. The room expires based on your subscription plan’s session time limits.
Session Type: Currently, only webrtc_video session type is supported. This is automatically set when creating a session.
Metadata Validation: The metadata field must be a valid JSON object (e.g., {"key": "value"}). Arrays, strings, numbers, booleans, or null values will be rejected with a 400 error. If not provided, it defaults to an empty object {}.

​
Behavior

  • Creates a new session associated with the specified avatar
  • Session is created in created status (not started)
  • Returns access_token needed for WebSocket authentication
  • Automatically creates a Daily.co video room with:
    • Unique room URL for video streaming
    • Meeting token for authentication
    • Expiration time based on your subscription plan limits
  • Only allows creating sessions for avatars you have access to (owned, shared via access rules, or public)
  • Avatar type requirement: sessions must use a look (an avatar with parent_id set)
  • Metadata defaults to {} and must be a valid JSON object
  • Session IDs are prefixed with sess_

​
Use Cases

  • Create a session before joining a Daily.co video room
  • Set up sessions with custom metadata for tracking
  • Pre-create multiple sessions for batch processing
  • Initialize sessions programmatically
{
  "success": true,
  "session": {
    "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
    "avatar": {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "name": "Professional Avatar (Look)",
      "url": "https://example.com/avatars/preview.jpg"
    },
    "session_type": "webrtc_video",
    "status": "created",
    "access_token": "access_token_xxxxxxxxxxxxx",
    "started_at": null,
    "ended_at": null,
    "expiration": null,
    "created_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "user_name": "John Doe",
      "session_purpose": "Customer Support"
    }
  },
  "usage": {
    "concurrency": {
      "current": 0,
      "max": 1,
      "available": 1
    },
    "minutes": {
      "total_remaining": 120
    }
  },
  "message": "Session created successfully"
}