# Create a conversation thread by resolving a user and invoking an AI agent

> 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: Threads.

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

## 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)

  Agent UID to invoke. Can be a plain agentUid or composite agentUid::sessionUid.

* `message` (string, required, body)

  Message to send to the agent. When messageType is 'user' (default), appears as a visible user message in the conversation. When messageType is 'system', used as an invisible prompt that triggers the agent without appearing in the conversation.

- `messageType` (string, body)

  Message type. 'user' (default) sends a visible user message. 'system' sends an invisible prompt (like an icebreaker) that triggers the agent without appearing in the conversation.

  One of: `user`, `system`. Default: `"user"`.

* `humanUid` (string, body)

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

- `externalUserId` (string, body)

  External system user identifier. Valid characters are A-Za-z0-9\_-. Mutually exclusive with other user identifiers.

* `sdkUserEmail` (string, body)

  SDK user email address. 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.

```json
{
  "agentUid": "string",
  "message": "string",
  "messageType": "user",
  "humanUid": "string",
  "externalUserId": "string",
  "sdkUserEmail": "string",
  "realEmailAddress": "string"
}
```

## Responses

### 201

Thread created successfully

```json
{
  "threadUid": "string",
  "humanUid": "string",
  "agentUid": "string"
}
```

### 400

Bad Request

### 401

Unauthorized

### 403

Forbidden - API key does not match appUid

### 404

Agent not found

### 422

Validation error (missing/invalid fields, identity resolution failure, or user not permitted)

### 502

Agent service returned an error

### 503

Agent service unavailable

### 504

Agent service did not respond in time

## Example request

```bash
curl -X POST "https://a.api.mindset.ai/api/v1/appuid/{appUid}/threads" \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"agentUid":"string","message":"string","messageType":"user","humanUid":"string","externalUserId":"string","sdkUserEmail":"string","realEmailAddress":"string"}'
```