ReferenceSDKSession API

Updated 6 Nov 2026View as Markdown

Session API

The server-to-server call that creates a session for one of your users: endpoint, request and response fields, attribution, and errors.

Your server makes this call to create a session for a user. What a session is and what it can reach is in Sessions and trust.

Endpoint#

Method and pathPOST https://YOUR-MINDSET-HOST/api/v1/orgs/{orgSlug}/envs/{envSlug}/agent-sessions
AuthenticationYour org API key in the x-api-key header, not in Authorization
KeyA Full access key, created in Settings → API keys for the same environment as envSlug; a Skills only key is answered 404. See Environments
Where to find the valuesThe agent's Embed tab in the Studio shows the host, both slugs and the agent's handle
CallersServers only. The route sends no CORS headers, so a browser can't call it

Request body#

FieldTypeRequiredNotes
user.emailstringone of the twoMust contain @ and no spaces. Matched without regard to case
user.externalIdstringone of the twoYour own ID. Letters, numbers, _ and - only, 100 characters or fewer. Matched exactly
agentstringyesThe agent's handle or its ID. The ID survives a rename of the handle
createUserIfNeededbooleannotrue creates a user Mindset hasn't seen. Defaults to false, which refuses an unknown user
attributionobjectnoYour own string labels for this session. See Attribution
additionalResources.skillsarray of stringsnoSkills this one session gets on top of the agent's own. See Skills for one session

Send exactly one of user.email and user.externalId. The body is strict: a field not in this table is a 400, and so is any key of additionalResources other than skills.

Response#

A 200 with a JSON body:

FieldWhat it is
sessionThe opaque credential. Its contents can change between releases, so don't decode, rebuild or store it
enabledFeaturesRelease features switched on for this deployment that the browser SDK can act on. Optional, and missing means none

Return the whole body to the browser unchanged, with cache-control: no-store, from the endpoint your page's getSession function calls. If you pass only session, the SDK still runs, but nothing that sits behind a release feature appears, and nothing reports it.

Attribution#

RuleLimit
ValuesStrings only
KeysUp to 16, each up to 64 characters
Values' lengthUp to 256 characters
Over a limitA 400. Mindset never trims the labels

The labels reach three places:

WhereWhat arrives
Your trace exportEvery span the session produces, as mindset.tag.<key> attributes
An MCP server you attachedEvery call to it, including calls from a function the agent runs, in _meta["mindset/attribution"]. Off unless an admin turns it on for that server, through their AI tool on the admin MCP; the server's Settings tab shows whether the labels are passed on
Your functions and scriptsThey read a label as attribution.<key>, so they can decide per plan, region or account

They are set once, at creation. The page can't change them, and Mindset never decides anything on them: the session may do exactly the same with or without labels. To test a function or script that reads one, give the test run labels of its own. See Functions and Scripts.

Skills for one session#

additionalResources.skills adds Skills to the session it creates. The agent's own configuration is unchanged.

RuleDetail
What to nameA Skill of this environment that has an active version, by handle, @-prefixed handle or ID
How manyUp to 20 names, and at most 50 Skills in all once the agent's own are counted: over 50 is a 400 validation_error whose context.additionalResources gives max and count
A name that isn't such a SkillThe whole create is a 400 validation_error, and no session is made. context.additionalResources.skills lists each name with its reason: not_found, or not_published when no version of it is active
Who gets themThis session only. Another session for the same user, or the same user on your org's hub, has only the agent's own Skills
Changes to the SkillDeactivating it drops it from the session from its next turn; a newly activated version is used at once
A conversation opened later by linkIt runs in a new session with the agent's own configuration, without the Skills this session added
The audit trailThe session's creation names each Skill it added; one the agent already holds is not counted as added

Errors#

Every error body is JSON with a code and a message.

What happenedStatuscode
A body field not in the table above400validation_error
Both email and externalId, or neither400validation_error
An email or externalId that breaks its format400validation_error
attribution over the limits400validation_error
additionalResources.skills names a Skill that doesn't exist here or has no active version400validation_error
additionalResources.skills names more than 20, or the agent's own and the added Skills come to more than 50400validation_error
additionalResources.skills is sent where Skills are not available on this instance404not_found
A request body over 4 MiB413payload_too_large
The agent has no published version to embed400validation_error
Embedded in your own product isn't ticked for the agent403agent_not_available_here
A platform key sent instead of an org API key403credential_kind_not_accepted
An unknown user, without createUserIfNeeded404not_found
The agent isn't one of your org's agents, is archived, or is a personal agent404not_found
The key's org doesn't match orgSlug404not_found
envSlug isn't the key's environment, or doesn't exist404not_found
The key doesn't carry admin scope404not_found
The user exists but isn't active (invited and not onboarded, or removed)409user_not_active
The agent has configuration versions but none is active409no_version_in_force

The 404s for a wrong org, environment, agent or key scope look the same on purpose, so nobody holding a key can use them to learn which orgs or environments exist. During setup, check each value against the Embed tab. Leaving out createUserIfNeeded gives a 404 that looks like a wrong agent.

Example#

bash
curl -sS -X POST \
  "https://eu.mindset.ai/api/v1/orgs/acme/envs/production/agent-sessions" \
  -H "x-api-key: $MINDSET_ORG_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "user": { "email": "alice@acme.com" },
    "agent": "billing-help",
    "createUserIfNeeded": true,
    "attribution": { "plan": "enterprise", "region": "emea" }
  }'

Replace eu.mindset.ai, acme and production with the host and slugs from your Embed tab. Put an agent on your page has a complete server that makes this call.