Start Session

This endpoint starts a new session and returns a session ID. An existing session cannot provide a session ID during creation.

---

Endpoint

POST /session/start

---

Parameters

Query Parameters

• session_id (optional):

  • Type: string

  • Description: Specify a session ID. Should not be provided when starting a new session. Use observe to interact with existing sessions.

• keep_alive (optional):

  • Type: boolean

  • Description: Keep the session alive beyond its timeout period. Default is false.

• session_timeout (optional):

  • Type: integer

  • Description: Set a custom timeout for the session in minutes. Default is 10.

  • Range: 0 < x ≤ 30

• screenshot (optional):

  • Type: boolean

  • Description: Request a screenshot during the session. Default is null (no screenshot).

---

Response

Response Parameters

• session_id (required):

  • Type: string

  • Description: The unique identifier for the created session.

• error (optional):

  • Type: string

  • Description: Error message if something goes wrong during session creation.

---

Error Responses

• 400 (Invalid Request):

  • Description: Input parameters are not valid.

• 500 (Internal Server Error):

  • Description: The server encountered an unexpected condition.

---

Authorizations

• Authorization (required):

  • Type: string

  • Location: Header

  • Description: Access token received from the authorization server in the OAuth 2.0 flow.

---

Body

Content Type: application/json

• keep_alive:

  • Type: boolean

  • Default: false

  • Description: If true, the session will not be closed after the operation is completed.

• screenshot:

  • Type: boolean | null

  • Description: Whether to include a screenshot in the response.

• session_id:

  • Type: string | null

  • Description: The ID of the session. A new session is created if not provided.

• session_timeout_minutes:

  • Type: integer

  • Default: 5

  • Description: Session timeout in minutes. Cannot exceed the global timeout.

  • Range: 0 < x ≤ 30

---

Example Request

curl --location \
--request POST 'https://api.notexai.pro/session/start' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-api-key' \
--data '{
    "keep_alive": true,
    "session_timeout_minutes": 15,
    "screenshot": false
}'

---

Response Example

200 - application/json

{
    "created_at": "2025-01-24T10:00:00Z",
    "duration": "10 minutes",
    "last_accessed_at": "2025-01-24T10:05:00Z",
    "session_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "status": "active",
    "timeout_minutes": 10,
    "error": null
}

---

Status Options

• active: Session is currently active.

• closed: Session has been closed.

• error: An error occurred during the session.

• timed_out: Session timed out after exceeding the timeout period.

---

Important Notes

• Ensure session_id is not provided when creating a new session.

• Use observe to interact with existing sessions.

• Monitor timeout settings to avoid unexpected session termination.