# Creating and Updating Sessions

In order to create and update sessions, the request needs to include a JSON array body that has the session objects. The objects can be of type [CreateSession](/v2-en/services/session-management/creating-and-updating-sessions/create-session-object.md) or [UpdateSession](/v2-en/services/session-management/creating-and-updating-sessions/update-session-object.md).

{% hint style="info" %}
The same endpoint handles both create and update operations for sessions. The operation type is determined by the presence of the `session_guid` parameter in the request body. Including `session_guid` indicates an **update operation**, while omitting it indicates a **create operation**.
{% endhint %}

***

**Example Request:**

{% hint style="warning" %}
Avoid making individual API calls in a loop since this endpoint accepts multiple session objects (both create and update operations) in a single request.
{% endhint %}

{% tabs %}
{% tab title="CURL" %}

```bash
curl -L -X POST 'https:https://<DOMAIN>/xapi/v2/session/batch' \
-H 'Content-Type: application/json' \
-d '[
    // Insert session
    {
        "name": "CS201",
        "description": "Let's learn the fundemental technologies used in Web Development",
        "start_date": "2025-08-05T12:00:00Z",
        "duration": 120,
        "lang": "en-US"
    },
    // Insert session with an incorrect start_date
    {
        "name": "TR102",
        "start_date": "2020-08-05T14:00:00Z",
        "duration": 120,
        "lang": "tr-TR",
        "options": {
            "allow_rating": false
        }
    },
    // Update session
    {
        "session_guid": "61E3D504-13EE-447F-9B36-6686C5C39FEB",
        "duration": 100
    },
    // Update session that doesn't exists
    {
        "session_guid": "8293D504-13EE-447F-9B36-6686C5C39FEB",
        "duration": 100
    }
]'
```

{% endtab %}

{% tab title="Python" %}

```python
client.sessions.upsert_sessions([
        #Insert session
        {
            "name": "CS201",
            "description": "Let's learn the fundemental technologies used in Web Development",
            "start_date": "2025-08-05T12:00:00Z",
            "duration": 120,
            "lang": "en-US"
        },
        #Insert session with an incorrect start_date
        {
            "name": "TR102",
            "start_date": "2020-08-05T14:00:00Z",
            "duration": 120,
            "lang": "tr-TR",
            "options": {
                "allow_rating": false
            }
        },
        #Update session
        {
            "session_guid": "61E3D504-13EE-447F-9B36-6686C5C39FEB",
            "duration": 100
        },
        #Update session that doesn't exist
        {
            "session_guid": "8293D504-13EE-447F-9B36-6686C5C39FEB",
            "duration": 100
        }
    ]);
```

{% endtab %}
{% endtabs %}

**Example Response:**

The response for this operation includes a json object like so:

```json
{
    "approved": [
        // JSON objects for session
    ],
    "rejected": [
        // JSON objects for session
    ]
}
```

{% hint style="info" %}
Response Status Codes will vary depending on how the operations went:

* <mark style="color:green;">**200 OK**</mark><mark style="color:green;">:</mark> All operations completed successfully
* <mark style="color:green;">**207 Multi-Status**</mark><mark style="color:green;">:</mark> Partial success - some operations failed
* <mark style="color:red;">**400 Bad Request**</mark><mark style="color:red;">:</mark> All operations failed
  {% endhint %}

<pre class="language-json"><code class="lang-json">{
    "approved": [
        {
            "session_guid": "1B27EB7F-6ECD-42B1-8CEC-4FE78B53A468",
            "name": "CS201",
            "description": null,
            "tags": null,
            "start_date": "2025-08-05T12:00:00+03:00",
            "timezone": "Europe/Istanbul",
            "duration": 120,
            "lang": "en-US",
            "status": 1,
            "replay_status": 0,
            "options": {
                "allow_rating": true,
                "preparation_time": 15,
                "session_duration": 120,
                "chat": {
                    "offMessageModule": false,
                    "offGeneralMsging": false,
                    "offGeneralMsgLimitForUser": false,
                    "offSpecialMsging": false,
                    "offSpecialMsgToAdmin": false,
                    "offSpecialMsgToUser": false,
                    "offNewMsgSound": false,
                    "offClearForReplay": false,
                    "onNewMsgSoundInAll": false,
                    "onNewMsgNotifyInAll": false
                },
                "duration": {
                    "allowExtendTime": true,
                    "useRemainingTime": false
                },
                "allow_users_stream_self_cam_mic": true,
                "hide_user_streams": false,
                "enable_attendance_check": true,
                "enable_simultaneous_interpretation": false,
                "enable_simultaneous_interpretation_for_users": false,
                "start_active": false,
                "return_url": "",
                "allow_reactions": true,
                "enable_recording_auto_start": null,
                "skip_approval_on_join": null,
                "enable_session_auto_start": null,
                "enable_session_auto_finish": null
            },
            "creation_date": "2025-02-06T16:07:35.488565+03:00",
            "updating_date": "2025-02-06T16:07:35.488565+03:00"
        },
        {
            "session_guid": "61E3D504-13EE-447F-9B36-6686C5C39FEB",
            "name": "Web Development 101",
            "description": null,
            "tags": null,
            "start_date": "2025-08-05T12:00:00+03:00",
            "timezone": "Europe/Istanbul",
            "duration": 100,
            "lang": "en-US",
            "status": 1,
            "replay_status": 0,
            "options": {
                "allow_rating": true,
                "preparation_time": 15,
                "session_duration": 100,
                "chat": {
                    "offMessageModule": false,
                    "offGeneralMsging": false,
                    "offGeneralMsgLimitForUser": false,
                    "offSpecialMsging": false,
                    "offSpecialMsgToAdmin": false,
                    "offSpecialMsgToUser": false,
                    "offNewMsgSound": false,
                    "offClearForReplay": false,
                    "onNewMsgSoundInAll": false,
                    "onNewMsgNotifyInAll": false
                },
                "duration": {
                    "allowExtendTime": true,
                    "useRemainingTime": false
                },
                "allow_users_stream_self_cam_mic": true,
                "hide_user_streams": false,
                "enable_attendance_check": true,
                "enable_simultaneous_interpretation": false,
                "enable_simultaneous_interpretation_for_users": false,
                "start_active": false,
                "return_url": "",
                "allow_reactions": true,
                "enable_recording_auto_start": null,
                "skip_approval_on_join": null,
                "enable_session_auto_start": null,
                "enable_session_auto_finish": null
            },
            "creation_date": "2025-02-06T15:23:48.490759+03:00",
            "updating_date": "2025-02-06T16:07:35.488565+03:00"
        }
    ],
    "rejected": [
        {
<strong>            "model": {
</strong>                "session_id": 0,
                "string_session_id": null,
                "the_guid": "8293D504-13EE-447F-9B36-6686C5C39FEB",
                "name": null,
                "description": null,
                "tags": null,
                "start_date": "1970-01-01T00:00:00+00:00",
                "duration": 100,
                "lang": "en-US",
                "account_id": 1329,
                "realtime_server": null,
                "conference_server": null,
                "file_server": null,
                "status": 1,
                "replay_status": 0,
                "ui_options": "{\"allow_rating\":true,\"preparation_time\":15,\"session_duration\":100,\"Chat\":{\"OffMessageModule\":false,\"OffGeneralMsging\":false,\"OffGeneralMsgLimitForUser\":false,\"OffSpecialMsging\":false,\"OffSpecialMsgToAdmin\":false,\"OffSpecialMsgToUser\":false,\"OffNewMsgSound\":false,\"OffClearForReplay\":false,\"OnNewMsgSoundInAll\":false,\"OnNewMsgNotifyInAll\":false},\"Duration\":{\"AllowExtendTime\":true,\"UseRemainingTime\":false},\"allow_users_stream_self_cam_mic\":true,\"hide_user_streams\":false,\"enable_attendance_check\":true,\"enable_simultaneous_interpretation\":false,\"enable_simultaneous_interpretation_for_users\":false,\"start_active\":false,\"return_url\":\"\",\"allow_reactions\":true,\"enable_recording_auto_start\":null,\"skip_approval_on_join\":null,\"enable_session_auto_start\":null,\"enable_session_auto_finish\":null}",
                "user_started": null,
                "user_finished": null,
                "user_added": 4490,
                "user_updated": 4490,
                "creation_date": null,
                "updating_date": null,
                "custom_field1": null,
                "custom_field2": null,
                "custom_field3": null,
                "custom_field4": null,
                "custom_field5": null,
                "repeating_options": null,
                "replay_access": "on",
                "allow_recording": true,
                "planned_duration": 100,
                "timezone": "Europe/Istanbul",
                "groups": [],
                "attendees": [],
                "owner": null,
                "files": [],
                "questions": [],
                "enrollOptions": null,
                "sessionGroups": [],
                "_isValid": null,
                "_errors": null
            },
            "state": {
                "code": 30,
                "details": "session_not_found"
            }
        },
        {
            "model": {
                "session_guid": null,
                "name": "TR102",
                "description": null,
                "tags": null,
                "start_date": "2020-08-05T14:00:00+00:00",
                "duration": 120,
                "lang": "tr-TR",
                "allow_recording": true,
                "inaccessible_replay": false,
                "options": {
                    "allow_rating": false,
                    "preparation_time": null,
                    "session_duration": null,
                    "chat": null,
                    "duration": null,
                    "allow_users_stream_self_cam_mic": null,
                    "hide_user_streams": null,
                    "enable_attendance_check": null,
                    "enable_simultaneous_interpretation": null,
                    "enable_simultaneous_interpretation_for_users": null,
                    "start_active": null,
                    "return_url": null,
                    "allow_reactions": null,
                    "enable_recording_auto_start": null,
                    "skip_approval_on_join": null,
                    "enable_session_auto_start": null,
                    "enable_session_auto_finish": null
                },
                "timezone": "Europe/Istanbul"
            },
            "state": {
                "code": 12,
                "details": [
                    "Invalid session start date."
                ]
            }
        }
    ]
}
</code></pre>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.perculus.com/v2-en/services/session-management/creating-and-updating-sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.