---
title: POST /harness/sessions
description: Create a session
full: true
---

**Auth:** required. Send an `ivy_` API key (`Authorization: Bearer ivy_…` or `X-Ivy-Api-Key`), a Clerk session JWT (`Authorization: Bearer …`) or the Clerk `__session` cookie (browser sessions). See [Authentication](/docs/api/authentication).

Creates an empty session owned by the caller and returns its id. The body is optional: set a `title` or a provider, model and tool `config`.

## Request

#### Request body

- `title` (string) —
Human-readable session label

- `clientId` (string) —
Client identifier for version vector tracking (auto-generated as `web_<ts>` if omitted)

- `config` (object) —

#### config properties

- `provider` (object) —

#### provider properties

- `type` (string) —
Provider identifier (anthropic, openai, openrouter)

- `model` (object) —

#### model properties

- `id` (string) —
Model identifier

- `tools` (object) —

#### tools properties

- `enabled` (string[]) —
Explicit tool allow-list; empty array means all tools are available

## Responses

### `201` Created

Session created

Response shape:

- `id` (string (uuid)) —
New session UUID (UUIDv7)

- `createdAt` (string (date-time)) —

### `400` Bad Request

Invalid request

Response shape: `object`

### `401` Unauthorized

Authentication required

Response shape: `object`

### `429` Too Many Requests

Rate limit exceeded

Response shape: `object`

**curl**

```bash
curl -X POST 'https://ivybiosciences.com/api/harness/sessions' \
  -H "Authorization: Bearer $IVY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

**JavaScript**

```js
const res = await fetch('https://ivybiosciences.com/api/harness/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.IVY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();
```

**Python**

```python
import os, requests

res = requests.post(
    "https://ivybiosciences.com/api/harness/sessions",
    headers={"Authorization": f"Bearer {os.environ['IVY_API_KEY']}"},
    json={},
)
data = res.json()
```