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

# Create Session

> Start a new agent coding session. If loop_id is omitted the server auto-creates a scoped loop.

Create a new session scoped to the authenticated API key's user. Sessions contain turns — the individual actions the agent wants human review on.

## Authentication

**Authorization** `string` *required*

Bearer API key.

## Body

**agent\_type** `string` (default: claude)

`claude` or `codex`.

**loop\_id** `string`

Existing loop to route turns into. If omitted, the server auto-creates a loop named `"<agent_type> — <repo>"` owned by the API-key user.

**context** `object`

Session context for reviewers.

**context**

**repo** `string`

Repository URL or path.

**branch** `string`

Current branch.

**commit** `string`

Short commit SHA.

**task** `string`

What the agent is trying to do (free text).

## Response

**error** `boolean`

**msg** `string`

**data.session** `object`

The newly created session (`id`, `status=active`, `loop_id`, `context`, `turn_count=0`, timestamps).

```bash cURL theme={null}
curl -X POST https://api.hitl.sh/v1/api/sessions \
  -H "Authorization: Bearer $HITL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "claude",
    "context": {
      "repo": "git@github.com:acme/app.git",
      "branch": "preview",
      "commit": "a1b2c3d",
      "task": "Add session export endpoint"
    }
  }'
```

```json 201 Created theme={null}
{
  "error": false,
  "msg": "session created",
  "data": {
    "session": {
      "id": "663f8...",
      "agent_type": "claude",
      "status": "active",
      "loop_id": "663f7...",
      "context": { "repo": "git@github.com:acme/app.git", "branch": "preview", "commit": "a1b2c3d", "task": "Add session export endpoint" },
      "turn_count": 0,
      "created_at": "2026-04-23T18:12:00Z",
      "updated_at": "2026-04-23T18:12:00Z"
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.