# Create a new agent session

> You're reading the Mindset v3 documentation. v3 is no longer sold; this is reference for existing customers. Mindset 4 docs are at /docs.

Mindset v3 REST API reference: Agent Sessions.

**POST** `/api/v1/appuid/{appUid}/agentsessions`

## Base URL

Requests go to your region's API host, for example `https://a.api.mindset.ai`. Hosts: `https://a.api.mindset.ai`, `https://b.api.mindset.ai`, `https://c.api.mindset.ai`, `https://d.api.mindset.ai`.

## Authorization

- `x-api-key` (string, required, header)

  Your API key.

## Path parameters

- `appUid` (string, required, path)

  Your application's uid

## Request body

Content type: `application/json`.

- `agentUid` (string, required, body)

  Uid of the agent to link to

* `externalUserId` (string, body)

  User Id from external system

- `userEmail` (string, body)

  email address format user identifier. Deprecated. Prefer using sdkUserEmail or externalUserId.

* `sdkUserEmail` (string, body)

  SDK user email address. Mutually exclusive with other user identifiers.

- `humanUid` (string, body)

  Direct Mindset human UID. Mutually exclusive with other user identifiers.

* `realEmailAddress` (string, body)

  User's actual email address for SSO or email-based auth. Mutually exclusive with other user identifiers.

- `tags` (string\[], body)

  Array of tags (max 10)

* `contextUids` (string\[], body)

  Array of existing context Uids (max 30)

- `mcpserverUids` (string\[], body)

  Array of existing MCP server Uids (max 5)

* `planUids` (string\[], body)

  Array of existing plan Uids (max 20). Overrides agent-level planUids.

- `skillUids` (string\[], body)

  Array of existing skill Uids (max 20). Overrides agent-level skillUids.

* `forcePlanUid` (string, body)

  Forces plan activation on session start. Must be a valid plan UID if provided.

```json
{
  "agentUid": "string",
  "externalUserId": "string",
  "userEmail": "string",
  "sdkUserEmail": "string",
  "humanUid": "string",
  "realEmailAddress": "string",
  "tags": [
    "string"
  ],
  "contextUids": [
    "string"
  ],
  "mcpserverUids": [
    "string"
  ],
  "planUids": [
    "string"
  ],
  "skillUids": [
    "string"
  ],
  "forcePlanUid": "string"
}
```

## Responses

### 201

Agent Session created successfully

```json
{
  "uid": "string",
  "agentSessionUid": "string",
  "humanUid": "string",
  "externalUserId": "string",
  "userEmail": "string",
  "agentUid": "string",
  "tags": [
    "string"
  ],
  "contextUids": [
    "string"
  ],
  "mcpserverUids": [
    "string"
  ],
  "createdAt": "string",
  "lastUsedAt": "string"
}
```

### 400

Bad Request

### 401

Unauthorized

### 403

Forbidden

### 422

Unprocessable Entity

### 500

Internal Server Error

## Example request

```bash
curl -X POST "https://a.api.mindset.ai/api/v1/appuid/{appUid}/agentsessions" \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"agentUid":"string","externalUserId":"string","userEmail":"string","sdkUserEmail":"string","humanUid":"string","realEmailAddress":"string","tags":["string"],"contextUids":["string"],"mcpserverUids":["string"],"planUids":["string"],"skillUids":["string"],"forcePlanUid":"string"}'
```