--- title: "Create socket session" method: POST path: "/api/v1/socket-sessions" --- # Create socket session `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 This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production. 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. ## Headers - `Idempotency-Key` string: 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. ## Request body - SocketSessionCreateRequest - `app_ids` string[], required: IDs of the apps the session can watch, up to 8. The key must be able to watch every one. ## Response `201` Session opened. - SocketSessionResponse - `session_id` string, required: ID of the session, for changing its apps or ending it. Keep it on your server. It can't open a connection. - `session_token` string, required: Secret the browser connects with, as `auth.session_token`. Pass it to the browser and don't store it. - `socket_url` string, required: Origin the browser connects to. - `socket_path` string, required: Socket.IO path on that origin. - `expires_in` integer, required: Seconds until the session and its token expire. A session is never extended. ## Other responses - `401`: The request has no Bearer token, or the key or personal access token isn't valid (`unauthenticated`). - `403`: The key doesn't have the **Watch app builder updates** permission (`scope_required`), the workspace turned personal access tokens off (`personal_access_token_policy_violation`), live updates aren't turned on for the workspace (`whitelabel_sockets_disabled`), the workspace's plan is below Builder (`white_label_plan_required`), or the credential can't watch the app in `error.details.app_id` (`app_not_allowed`). No session opens if any app is refused. - `409`: The key or token already holds 5,000 live sessions (`session_limit_reached`), so end the ones you no longer use. Or the `Idempotency-Key` was already sent with different `app_ids` (`idempotency_key_reused`), or a request with it is still in progress (`idempotency_key_in_use`). - `422`: `app_ids` is empty, lists more than 8 apps, or holds a value that isn't an app ID, or the body has other fields (`invalid_request`). - `429`: Rate limit reached (`rate_limited`). Retry later. ## Changes > 58 revisions in range; 1 not diffed. - **2026-10-21** `c23775445de2`: 2 breaking, 1 warning, 1 info - `header` request parameter `Idempotency-Key` list-of-types was narrowed by removing types `null` - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `0` to `1` - for the `header` request parameter `Idempotency-Key`, the maxLength was set to `128` - for the `header` request parameter `Idempotency-Key`, the type was generalized from no type to `string` - **2026-10-19** `bf3bf64eaea3`: 1 info - endpoint added [Operation history](https://skmtc.dev/adexad/apis/base44-app-management-api/changes/api/v1/socket-sessions/post.md) --- [API](https://skmtc.dev/adexad/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/adexad/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adexad/apis/base44-app-management-api/revisions/fa29e915c226?raw)