> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magnet.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Session

> Create a new AI coding session. Optionally link a repository and provide an initial prompt.

## Authentication

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

## Request body

<ParamField body="organizationId" type="string" required>
  The ID of the workspace to create the session in.
</ParamField>

<ParamField body="initialMessage" type="string">
  The initial prompt for the agent. A title is auto-generated from this message.
</ParamField>

<ParamField body="repoUrl" type="string">
  GitHub repository URL to clone (e.g., `https://github.com/owner/repo`). The sandbox will clone this repo before the agent starts working.
</ParamField>

<ParamField body="baseBranch" type="string">
  The branch to base changes on. Defaults to `main`. Only used when `repoUrl` is provided.
</ParamField>

<ParamField body="model" type="string">
  The Claude model to use. Defaults to `claude-opus-4-6`.
</ParamField>

## Response

Returns `201 Created` with the newly created session.

<ResponseField name="session" type="object">
  The created session object. See [List Sessions](/api-reference/sessions/list-sessions) for the full schema.
</ResponseField>

## Example

<Note>
  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.
</Note>

```bash cURL theme={null}
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

```json theme={null}
{
  "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

| Status | Description                                                     |
| ------ | --------------------------------------------------------------- |
| `400`  | Invalid request body or API key used instead of browser session |
| `401`  | Invalid or missing authentication                               |
| `403`  | No access to the specified workspace                            |
| `500`  | Server error                                                    |

<Note>
  Session creation requires browser authentication. If you need to create sessions programmatically, use the Magnet dashboard.
</Note>