---
schema_version: "1"
id: bea0228fed0b707fa238565f408fba7a3ea07c9ccf0a8d74876e5e35209dcb05
title: Create Session
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/data-cloud/agentic-memory-context/references/agentic-memory-context-ref/agentic-memory-api-create-session.md
canonical_url: https://developer.salesforce.com/docs/data/agentic-memory-context/references/agentic-memory-context-api-ref/agentic-memory-api-create-session.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: e877c27c10b6adda2bf9614798143b712db7f27b41479551599401ba024adcd1
products:
  - Agentic Memory & Context
  - Data 360 Developer Documentation
---
# Create Session

Create a new session within a conversation. Provide a session ID, owner information, and at least one initial participant.

**URI:** `/api/v1/agentic/conversations/{conversationId}/sessions`

**Format:** `application/json`

**HTTP Method:** `POST`

**Authentication:** Bearer JWT

## Path Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| conversationId | Yes | Conversation identifier. |

## Request Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer JWT token. |
| agent_id | Yes | Registered agent API name. |

## Request Body Schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| sessionId | String | Yes | Caller-supplied unique identifier for this session. |
| conversationOwnerId | String | Yes | Individual or User ID. Must align with parent conversation. |
| ownerType | String | Yes | Type of owner. Values: `individual`, `employee`. |
| participants | Array | Yes | Initial participant set. Minimum 1 participant required. |
| participants[].id | String | Yes | Participant identifier. |
| participants[].type | String | Yes | Participant type. Values: `individual`, `employee`, `agent`, or free-form string. |
| participants[].role | String | Yes | Participant role. Values: `owner`, `participant`. |
| participants[].startTime | String (ISO 8601) | No | Join time. |
| participants[].endTime | String (ISO 8601) | No | Leave time. Null indicates active participation. |
| participants[].orgId | String | No | Organization ID for cross-org handoffs. |
| variable | Map | No | Arbitrary metadata. |

### Example Request

```json
{
  "sessionId": "sess-9001",
  "conversationOwnerId": "003AB000000XYZ",
  "ownerType": "individual",
  "participants": [
    {
      "id": "003AB000000XYZ",
      "type": "individual",
      "role": "owner",
      "startTime": "2026-01-01T00:00:00Z"
    }
  ],
  "variable": {}
}
```

## Response Body Schema

| Field | Type | Description |
|-------|------|-------------|
| statusCode | String | Operation status. Value: `created`. |
| conversationId | String | Parent conversation identifier. |
| sessionId | String | The created session identifier. |

### Example Response

**Status:** `201 Created`

```json
{
  "statusCode": "created",
  "conversationId": "conv-2025-001",
  "sessionId": "sess-9001"
}
```

## Error Codes

| Status Code | Description |
|-------------|-------------|
| 400 | Bad Request. Invalid request format or missing required fields. |
| 401 | Unauthorized. Invalid or missing JWT token. |
| 404 | Not Found. Conversation does not exist. |
| 500 | Internal Server Error. |