Sessions API¶

Endpoints for managing conversational sessions with your Agentic App.

Create a Session¶

Establishes a new conversation session for a specific user with the Agentic App.

Note: This is the starting point for any new interaction.

Method	POST
Endpoint	/apps/<AppID>/environments/<EnvName>/sessions
Content-type	application/json
Authorization Header	x-api-key: <API-KEY>

Path Parameters¶

Fields	Description
AppID	Unique Identifier for the app.
EnvName	Name of the environment to be used for the agent.

Request Parameters¶

Fields	Description
sessionIdentity	This is an array of objects with a `type` and `value` used to identify or create sessions and manage user session mappings. The three supported identifier types are: The objects can be of three types: userReference (highest priority) sessionReference sessionIdentity(lowest priority) Refer to [this](overview.md) for a detailed description.

Sample Request¶

{
  "sessionIdentity": [
    {
      "type": "userReference",  
      "value": "usr_1a2b3c4d5e"  //Your UserReference Value
    }
  ]
}

Response¶

Returns the details of the newly created session, which are essential for managing and continuing the conversation.

Sample Response¶

{
  "session": {
    "sessionId": "s-a302e3c6-308b-4a0a-9a5f-a01a5846fae1",
    "sessionReference": "Se_skwos333",
    "userReference": "usr_1a2b3c4d5e",
    "status": "idle",
    "userId": "u-4c2221e1-46c2-53c5-9876-fd6699052c15",
    "createdAt": "2025-02-17T19:07:00.070Z"
  }
}

Response Parameters¶

Field	Description
sessionId	A unique identifier for the session.
status	Indicates the current state of the session. Possible values: `idle`, `busy`, `error`.
sessionReference	A unique reference string associated with the session for easier cross-request tracking.
userReference	Unique reference string for the user associated with the session.
userId	Internal system-generated identifier for the user.
createdAt	Timestamp indicating when the session was created.

Note: When a new session is initiated, and the application requires permissions for OAuth authorization from the user, the API response includes a special event of type IDP_Redirect.

This event provides a URL that the user must visit to complete the authorization process. If the required authorization is not completed, the associated tools will return an error upon invocation.

{
  "messageId": "msg-260f4d3c-5b8c-4056-af97-11317fc28c8d",
  "events": [
    {
      "type": "IDP_Redirect",
      "content": {
        "auth_profiles": [
          {
            "url": "https://agent-platform.kore.ai/r/396c63515671634648357955",
            "idpName": "Google",
            "isAuthorized": false,
            "sso_type": "oauth2"
          }
        ]
      }
    }
  ],
  "sessionInfo": {
    "status": "idle",
    "userReference": "s-b8987503-696b-4111-a006-49c0cbcf0fb9",
    "sessionReference": "s-b8987503-696b-4111-a006-49c0cbcf0fb9",
    "userId": "u-f5e5e830-70d4-53d6-8034-86bfa765c04a",
    "sessionId": "s-54f40bda-1505-4f9e-b38e-88d39ea36d58",
    "runId": "r-41ad20e0-6295-4f0e-9b04-e51875356107",
    "appId": "aa-c31cccce-d0bf-4db5-a177-7ff45941c2d8",
    "attachments": []
  }
}

List Sessions¶

Lists sessions for the selected app and environment. Supports optional filters such as session ID, user reference, and date range.

Method	POST
Endpoint	/apps/<AppID>/environments/<EnvName>/sessions/list
Content-type	application/json
Authorization Header	x-api-key: <API-KEY>

Path Parameters¶

Fields	Description
AppID	Unique Identifier for the app.
EnvName	The name of the environment in which the application will run.

Request Parameters¶

Fields	Description	Mandatory
sessionId	To filter sessions by a specific session ID, provide the unique session ID.	No
userReference	To Filter sessions by user reference, provide the userReference string.	No
date	To filter the sessions by date, provide the start and end dates.	No
filters	This field is for future implementation	No
offset	Number of records to skip (for pagination).	No

Sample Request¶

{
  "sessionId": "string",               
  "userReference": "string",           
  "date": {                           
    "start": "string",
    "end": "string"
  },
  "filters": [                        // For future use
    {
      "key": "string",
      "value": "string",
      "operator": "string"
    }
  ],
  "offset": "number"
}

Response Parameters¶

Fields	Description
sessions	Details of the sessions
pagination	Details related to pagination include the total number of matching sessions, the Index of the last item returned in this response, and whether more sessions are available beyond the current result.

Sample Response¶

{
  "sessions": [
    {
      "sessionId": "string",
      "sessionReference": "string",
      "status": "string",
      "userId": "string",
      "createdAt": "string"  // ISO timestamp
    }
  ],
  "pagination": {
    "totalCount": "number",
    "endIndex": "number",
    "hasMore": "boolean"
  }
}

Send Feedback