Create socket session

Changed on

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Opens a live-updates session for specific apps, and returns the token the builder's browser connects with. Call it from your server each time a page opens. Authenticate with a workspace API key that has the Watch app builder updates permission, or with a personal access token. A read-only personal access token works too.

Available only to white-label workspaces on the Builder plan or higher, with live AI chat updates turned on. Ask your onboarding contact to turn them on for your workspace.

Every app in app_ids must be one the credential can watch, or no session opens. A key watches the apps it's granted. A personal access token watches the apps in its workspace that its owner can edit, limited to its selected apps when it has them. A session watches up to 8 apps for 60 minutes and is never extended, so open a new one rather than reusing a token. Return session_token, socket_url, and socket_path to the browser, and keep session_id on your server to change or end the session later.

A key or token holds up to 5,000 live sessions at once. Send an Idempotency-Key header so a retry after a lost response doesn't open a second session. Session calls are limited to 600 requests a minute per workspace. Some workspaces have a different limit. Every request that counts against the limit gets X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time in seconds) headers, and a 429 also gets Retry-After in seconds.

post/api/v1/socket-sessions

Request

  • Base URL: https://app.base44.com
  • URL: https://app.base44.com/api/v1/socket-sessions
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Headers

Idempotency-Keystring

A unique value you choose for this page open, such as a UUID. A retry with the same value and the same app_ids returns the same session_id with a new session_token, and the earlier token stops working. The value is kept for the session's lifetime.

Example:5d0e2a9c-6f1b-4c3e-8a7d-2b9f0c1e4a6d

Request body

app_idsstring[] required

IDs of the apps the session can watch, up to 8. The key must be able to watch every one.

Example request

{
  "app_ids": [
    "6a2024af837c7a06c83021c1"
  ]
}

Response

Session opened.

session_idstring required

ID of the session, for changing its apps or ending it. Keep it on your server. It can't open a connection.

session_tokenstring required

Secret the browser connects with, as auth.session_token. Pass it to the browser and don't store it.

socket_urlstring required

Origin the browser connects to.

socket_pathstring required

Socket.IO path on that origin.

expires_ininteger required

Seconds until the session and its token expire. A session is never extended.

Example response

{
  "session_id": "3f9a1c0e7b2d4e8f9a6b5c4d3e2f1a0b",
  "session_token": "b44ws_Jd8lQ2v0mX4rT9yK1pN6sB3hW7cF5gA0eZ2uL8oI4qR",
  "socket_url": "https://ws.base44.com",
  "socket_path": "/ws/socket.io/",
  "expires_in": 3600
}

Changes

  • c23775445de2Revision changes
    • breaking

      header request parameter Idempotency-Key list-of-types was narrowed by removing types null

    • breaking

      for the header request parameter Idempotency-Key, the minLength was increased from 0 to 1

    • warning

      for the header request parameter Idempotency-Key, the maxLength was set to 128

    • info

      for the header request parameter Idempotency-Key, the type was generalized from no type to string

  • bf3bf64eaea3Revision changes
    • info

      endpoint added