Mindset v3 / Deploy in your app / Agent Sessions

Create a new agent session

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

Your API key.

Path parameters

appUidstringpathrequired

Your application's uid

Request body

Content type: application/json.

agentUidstringbodyrequired

Uid of the agent to link to

externalUserIdstringbody

User Id from external system

userEmailstringbody

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

sdkUserEmailstringbody

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

humanUidstringbody

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

realEmailAddressstringbody

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

tagsstring[]body

Array of tags (max 10)

contextUidsstring[]body

Array of existing context Uids (max 30)

mcpserverUidsstring[]body

Array of existing MCP server Uids (max 5)

planUidsstring[]body

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

skillUidsstring[]body

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

forcePlanUidstringbody

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