Observe Page

This endpoint observes the actions available on a given URL within the session’s environment.

---

Endpoint

POST /env/observe

---

Parameters

Query Parameters

• session_id (optional):

  • Type: string

  • Description: The session ID of the session within which the environment will be observed.

• url (required):

  • Type: string

  • Description: The URL to analyze and fetch available actions.

• 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.

---

Response

Response Parameters

• session_id (required):

  • Type: string

  • Description: The unique identifier for the session used in the observation.

• title (required):

  • Type: string

  • Description: The title of the observed page.

• url (required):

  • Type: string

  • Description: The URL of the observed page.

• timestamp (required):

  • Type: string

  • Description: The timestamp when the observation was performed, in ISO 8601 format.

• screenshot (optional):

  • Type: string (base64)

  • Description: A base64-encoded screenshot of the observed page, if requested.

• data (optional):

  • Type: string

  • Description: The data retrieved during the observation.

• space (optional):

  • Type: object

  • Description: The available action space, including descriptions and categories.

---

Error Responses

• 400 (Invalid Request):

  • Description: Returned when the input parameters are not valid or a required parameter is missing.

• 500 (Internal Server Error):

  • Description: Returned when the server encounters an unexpected condition.

---

Authorizations

• Authorization (required):

  • Type: string

  • Location: Header

  • Description: The 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.

• max_nb_actions:

  • Type: integer

  • Default: 100

  • Description: The maximum number of actions to list before stopping. Used when min_nb_actions is not provided.

• min_nb_actions:

  • Type: integer | null

  • Description: The minimum number of actions to list before stopping. If not provided, the listing continues until max_nb_actions is reached.

• 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.

• url:

  • Type: string

  • Description: The URL to observe.

---

Example Request

curl --location \
--request POST 'https://api.notexai.pro/env/observe' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-api-key' \
--data '{
    "session_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "url": "https://example.com",
    "keep_alive": true,
    "screenshot": true
}'

---

Example Response

200 - application/json

{
    "session_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "title": "Example Page Title",
    "url": "https://example.com",
    "timestamp": "2025-01-24T14:00:00Z",
    "screenshot": "...base64-encoded-data...",
    "data": "...retrieved data...",
    "space": {
        "description": "This page allows users to search for items.",
        "actions": [
            {
                "id": "action1",
                "description": "Search for an item.",
                "category": "search"
            }
        ]
    }
}