> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindset.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Sessions API

> Parameters full description

<Card title="Note" icon="link" iconType="solid" href="/deploy/api/agent-sessions/retrieve-a-collection-of-agent-sessions" cta="Agent sessions API playground">
  You can find below the full description of Parameters for each POST/GET/DELETE methods and also what parameters you can expect from the API responses.

  <br />

  If you want to test the API, please see the Agent sessions API playground.
</Card>

<AccordionGroup>
  <Accordion title="POST - Create a new agentSession">
    ## Parameters:

    #### **agentUid** *String*

    Uid of the agent to link to

    #### **externalUserId** *String*

    User Id from external system

    #### **userEmail** *String*

    email address format user identifier. Deprecated. Prefer using externalId instead.

    #### **tags** *String\[]*

    Array of tags (max 10). You will be able to view reports based grouping or filtering of activity according to the tags applied when creating the session.

    #### **contextUids** *String\[]*

    Array of existing context Uids (max 30)

    #### **mcpserverUids** *String\[]*

    Array of existing mcpserver Uids (max 5)

    #### **planUids** *String\[]*

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

    #### **skillUids** *String\[]*

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

    #### **forcePlanUid** *String*

    Starts a plan automatically when the user opens the agent, and again whenever they start a new conversation, so they land straight in a guided flow without typing anything. The plan you set here must also be one of the session's `planUids`, the plans you make available to that user. If it isn't one of them, Mindset AI rejects the request.

    We recommend setting only one "on open" behavior per agent. If you combine `forcePlanUid` with an icebreaker or an `initialQuestion`, each one sends a message to the user the moment they open the agent, so the agent pushes a series of messages before the user gets a chance to respond. When both an icebreaker and `forcePlanUid` are set, the icebreaker is delivered first and the forced plan starts on the next turn. An `initialQuestion` takes priority over both, so if you set one, `forcePlanUid` is ignored.

    <Warning>
      The forced plan should fit how the agent is configured. `forcePlanUid` decides which plan starts, but it does not change the agent's personality or purpose. If the plan asks the agent to do work that falls outside its configured role, the agent may decline to run it and tell the user the task is outside its scope. Choose a plan whose task matches what the agent is for. For example, an onboarding plan suits an onboarding or general assistant agent, not a specialized analytics agent whose job is to explore data. Some language models are stricter than others about attempting activities they are not designed for, so a forced plan that one model runs may be declined by another. Test the forced plan with the agent's configured model before you rely on it.
    </Warning>
  </Accordion>

  <Accordion title="GET - Query the list of agentSessions">
    ## Parameters:

    #### **startAfter - Querying for “the next page”** *String*

    Use the `startAfter` parameter and provide the `createdAt` string of the last agent session in the current results set When there are no more results you will receive an empty array in the response and a 404 status code

    #### **externalUserId** *String*

    Filter results to a specific externalUserId

    #### **userEmail** *String*

    Filter results to a specific email address format user identifier. Deprecated. Prefer using externalId.

    #### **contextUid** *String*

    Filter results to a specific contextUid

    #### **agentUid** *String*

    Filter results to a specific agentUid
  </Accordion>

  <Accordion title="DELETE - Delete an agentSession by providing its uid" />

  <Accordion title="RESPONSE DATA">
    You will get the same response data when calling POST or GET.

    ***Note***: When retrieving a collection of agentSessions, the response will be an array of objects.

    #### **uid** *String*

    Mindset internal agentSession uid

    #### **agentSessionUid** *String*

    Unique Identifier of the agentSession you have to use with the Mindset Agents SDK.

    #### **humanUid** *String*

    Mindset internal humanUid uid of the user who the agentSession was created for.

    #### **externalUserId** *String*

    User Id from your system you provided.

    #### **userEmail** *String*

    User email from your system you provided.

    #### **agentUid** *String*

    agentUid of the agent linked to the agentSession.

    #### **tags** *String\[]*

    Array of tags provided when creating the agentSession.

    #### **contextUids** *String\[]*

    Array of context Uids provided when creating the agentSession.

    #### **mcpserverUids** *String\[]*

    Array of mcpserver Uids provided when creating the agentSession.

    #### **planUids** *String\[]*

    Array of plan Uids provided when creating the agentSession. Overrides agent-level planUids.

    #### **skillUids** *String\[]*

    Array of skill Uids provided when creating the agentSession. Overrides agent-level skillUids.

    #### **forcePlanUid** *String*

    Plan UID forced active on session start, if provided.

    #### **createdAt** *ISO timestamp*

    agentSession creation date

    #### **lastUsedAt** *ISO timestamp*

    Last time the agentSession was used. This is updated each time a message is sent or received in the agentSession.
  </Accordion>
</AccordionGroup>