Skip to main content
POST
/
api
/
sessions
Create Session
curl --request POST \
  --url https://api.example.com/api/sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "organizationId": "<string>",
  "initialMessage": "<string>",
  "repoUrl": "<string>",
  "baseBranch": "<string>",
  "model": "<string>"
}
'
{
  "session": {}
}

​
Authentication

Requires browser authentication (dashboard). API keys cannot create sessions — sessions must be attributed to a specific user.

​
Request body

​
organizationId
string
required
The ID of the workspace to create the session in.
​
initialMessage
string
The initial prompt for the agent. A title is auto-generated from this message.
​
repoUrl
string
GitHub repository URL to clone (e.g., https://github.com/owner/repo). The sandbox will clone this repo before the agent starts working.
​
baseBranch
string
The branch to base changes on. Defaults to main. Only used when repoUrl is provided.
​
model
string
The Claude model to use. Defaults to claude-opus-4-6.

​
Response

Returns 201 Created with the newly created session.
​
session
object
The created session object. See List Sessions for the full schema.

​
Example

This endpoint requires browser authentication (session cookie). The example below shows the request shape — to create sessions, use the Magnet dashboard or the API from an authenticated browser context.
cURL
curl -X POST "https://magnet.run/api/sessions" \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=<your-session-token>" \
  -d '{
    "organizationId": "org_abc123",
    "initialMessage": "Add input validation to the signup form. Email should be validated, password needs 8+ chars with at least one number.",
    "repoUrl": "https://github.com/acme/web-app",
    "baseBranch": "main"
  }'

​
Response

{
  "session": {
    "id": "cm3abc123def",
    "title": "Add input validation to signup form",
    "status": "active",
    "createdAt": "2026-02-11T10:00:00.000Z",
    "updatedAt": "2026-02-11T10:00:00.000Z",
    "model": "claude-opus-4-6",
    "author": {
      "id": "user_123",
      "name": "Alice Chen"
    },
    "metadata": {
      "repository": "acme/web-app"
    },
    "messageCount": 1,
    "firstMessagePreview": "Add input validation to the signup form..."
  }
}

​
Errors

StatusDescription
400Invalid request body or API key used instead of browser session
401Invalid or missing authentication
403No access to the specified workspace
500Server error
Session creation requires browser authentication. If you need to create sessions programmatically, use the Magnet dashboard.