Mindset v3 / Deploy in your app / Threads

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

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-keystringheaderrequired

Your API key.

Path parameters

appUidstringpathrequired

Your application's uid

Request body

Content type: application/json.

agentUidstringbodyrequired

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

messagestringbodyrequired

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.

messageTypestringbody

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".

humanUidstringbody

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

externalUserIdstringbody

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

sdkUserEmailstringbody

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

realEmailAddressstringbody

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"}'