Skip to main content
POST
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.example.com/v1/sessions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_name": "<string>",
  "webhook_url": "<string>",
  "restore_from_session_id": "<string>",
  "restore_default_environment_from_user_id": "<string>",
  "enable_memory_snapshot": true
}
'
{
  "session_id": "f6a7b0e6-7f46-4a0d-9a47-92b7f0a4d2d3",
  "vnc_url": "https://vnc.agi.tech/session/f6a7b0e6...",
  "agent_name": "agi-0",
  "status": "ready",
  "created_at": "2025-10-05T18:04:34.281Z"
}

​
Overview

Creates a new session with an agent and browser environment. The session is ready to receive messages and execute tasks.

​
Request

​
Authorization
string
required
Bearer token for authentication
​
agent_name
string
default:"agi-0"
The agent model to use for this sessionOptions:
  • agi-0 - Full-featured agent (default)
  • agi-0-fast - Faster agent for quick tasks
​
webhook_url
string
URL to receive webhook notifications for session lifecycle and task execution events
  • Must be a valid HTTP or HTTPS URL
  • Maximum length: 2,000 characters
  • Must start with http:// or https://
See Webhooks documentation for details on webhook events and payloads.
​
restore_from_session_id
string
Restore session from a specific session’s snapshot
  • Provide the UUID of a previously saved session
  • The new session will restore from that session’s snapshot
  • Takes precedence over restore_default_environment_from_user_id
See Session Snapshots guide for details on saving and restoring snapshots.
​
restore_default_environment_from_user_id
string
Restore session from the user’s default environment snapshot
  • Provide your user ID to restore from your default environment
  • Creates a session that automatically restores from the default snapshot
  • Lower priority than restore_from_session_id
See Session Snapshots guide for details on setting default environments.
​
enable_memory_snapshot
boolean
default:"true"
Enable memory snapshots for faster restoration
  • true - Uses memory snapshots for faster restoration (default, recommended)
  • false - Uses filesystem snapshots only (slower but more reliable)
Only applies when restoring from a snapshot.

​
Response

​
session_id
string
required
Unique identifier (UUID) for the created session
​
vnc_url
string
URL to view and interact with the agent’s browser in real-time
​
agent_name
string
required
The agent model being used
​
status
string
required
Current session status (typically ready for new sessions)
​
created_at
string
required
ISO 8601 timestamp of session creation
{
  "session_id": "f6a7b0e6-7f46-4a0d-9a47-92b7f0a4d2d3",
  "vnc_url": "https://vnc.agi.tech/session/f6a7b0e6...",
  "agent_name": "agi-0",
  "status": "ready",
  "created_at": "2025-10-05T18:04:34.281Z"
}

​
Example Requests

import { AGIClient } from 'agi';

const client = new AGIClient({ apiKey: 'your_api_key' });

// Create session
const session = await client.createSession('agi-0');
console.log(`Session created: ${session.session_id}`);
console.log(`View browser at: ${session.vnc_url}`);

// Create session with webhook
const sessionWithWebhook = await client.createSession('agi-0', {
  webhook_url: 'https://your-server.com/webhooks/sessions'
});

​
Error Responses

​
422
error
Invalid agent name or request parameters
​
500
error
Infrastructure failure or bootstrap error

​
Use Cases

​
Quick Research Task

Create a session for one-time research without saving state: 
{
  "agent_name": "agi-0-fast"
}

​
Watch Agent Work

Open the vnc_url in your browser to watch the agent navigate and interact with websites in real-time.

​
With Webhooks

Create a session with webhook notifications for real-time event updates: 
{
  "agent_name": "agi-0",
  "webhook_url": "https://your-server.com/webhooks/sessions"
}
See Webhooks documentation for complete webhook setup and event details.

​
Restore from Default Snapshot

Create a session that automatically restores from your default environment: 
{
  "agent_name": "agi-0",
  "restore_default_environment_from_user_id": "your-user-id"
}

​
Restore from Specific Session

Create a session restoring from a specific session’s snapshot: 
{
  "agent_name": "agi-0",
  "restore_from_session_id": "550e8400-e29b-41d4-a716-446655440000"
}
See Session Snapshots guide for complete details on saving and restoring snapshots.

​
Best Practices

Always store the returned session_id - you’ll need it for all subsequent operations
Sessions consume resources. Always delete sessions when done to avoid unnecessary charges
The vnc_url is perfect for debugging. Open it in a browser to see exactly what the agent is doing