> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.
# Create socket session
> 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 the apps a page shows, and returns the token the builder's browser connects with. Call it from your server each time a page opens, with a workspace API key that has the **Watch app builder updates** permission.
Available to white-label workspaces with live builder updates turned on. Your onboarding contact turns them on for your workspace.
Every app in `app_ids` must be one the key can watch, or no session opens. 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` and `socket_url` to the browser, and keep `session_id` on your server to change or end the session later.
A key holds up to 5,000 live sessions at once. A retry after a lost response opens another session, which counts toward that number until it expires. 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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/service/socket-sessions
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/service/socket-sessions:
post:
summary: Create socket session
description: >-
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 the apps a page shows, and returns the
token the builder's browser connects with. Call it from your server each
time a page opens, with a workspace API key that has the **Watch app
builder updates** permission.
Available to white-label workspaces with live builder updates turned on.
Your onboarding contact turns them on for your workspace.
Every app in `app_ids` must be one the key can watch, or no session
opens. 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` and `socket_url` to the browser, and keep `session_id`
on your server to change or end the session later.
A key holds up to 5,000 live sessions at once. A retry after a lost
response opens another session, which counts toward that number until it
expires. 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.
operationId: create_socket_session_api_service_socket_sessions_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SocketSessionCreateRequest'
required: true
responses:
'201':
description: Session opened.
headers:
X-RateLimit-Limit:
description: Requests allowed in the current minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests left in the current minute.
schema:
type: integer
X-RateLimit-Reset:
description: When the limit resets, in Unix time in seconds.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/SocketSessionResponse'
'401':
description: >-
The request has no Bearer token, or the key isn't valid
(`unauthenticated`).
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
examples:
unauthenticated:
summary: unauthenticated
value:
error:
code: unauthenticated
message: Invalid workspace API key
details: {}
'403':
description: >-
The key doesn't have the **Watch app builder updates** permission
(`scope_required`), live updates aren't turned on for the workspace
(`whitelabel_sockets_disabled`), or the key can't watch the app in
`error.details.app_id` (`app_not_allowed`). No session opens if any
app is refused.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
examples:
scope_required:
summary: scope_required
value:
error:
code: scope_required
message: The key needs the apps:watch scope
details:
required_scope: apps:watch
whitelabel_sockets_disabled:
summary: whitelabel_sockets_disabled
value:
error:
code: whitelabel_sockets_disabled
message: White-label sockets are not enabled for this workspace
details: {}
app_not_allowed:
summary: app_not_allowed
value:
error:
code: app_not_allowed
message: The key cannot watch this app
details:
app_id: 6a2024af837c7a06c83021c1
'409':
description: >-
The key already holds 5,000 live sessions (`session_limit_reached`).
End the ones you no longer use.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
examples:
session_limit_reached:
summary: session_limit_reached
value:
error:
code: session_limit_reached
message: >-
A key can hold at most 5000 live sessions; end unused
ones
details: {}
'422':
description: >-
`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`).
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
examples:
invalid_request:
summary: invalid_request
value:
error:
code: invalid_request
message: Invalid request
details:
errors:
- type: too_short
loc:
- body
- app_ids
msg: >-
List should have at least 1 item after validation,
not 0
input: []
ctx:
field_type: List
min_length: 1
actual_length: 0
'429':
description: Rate limit reached (`rate_limited`). Retry later.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
examples:
rate_limited:
summary: rate_limited
value:
error:
code: rate_limited
message: Rate limit exceeded
details: {}
headers:
X-RateLimit-Limit:
description: Requests allowed in the current minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests left in the current minute.
schema:
type: integer
X-RateLimit-Reset:
description: When the limit resets, in Unix time in seconds.
schema:
type: integer
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
security:
- WorkspaceApiKeyBearerAuth:
- apps:watch
components:
schemas:
SocketSessionCreateRequest:
properties:
app_ids:
items:
type: string
pattern: ^[0-9a-f]{24}$
type: array
maxItems: 8
minItems: 1
title: App Ids
description: >-
IDs of the apps the session may watch, up to 8. The key must be able
to watch every one.
examples:
- - 6a2024af837c7a06c83021c1
additionalProperties: false
type: object
required:
- app_ids
title: SocketSessionCreateRequest
SocketSessionResponse:
properties:
session_id:
type: string
title: Session Id
description: >-
ID of the session, for changing its apps or ending it. Keep it on
your server. It can't open a connection.
examples:
- 3f9a1c0e7b2d4e8f9a6b5c4d3e2f1a0b
session_token:
type: string
title: Session Token
description: >-
Secret the browser connects with, as `auth.session_token`. Pass it
to the browser and don't store it.
examples:
- b44ws_Jd8lQ2v0mX4rT9yK1pN6sB3hW7cF5gA0eZ2uL8oI4qR
socket_url:
type: string
title: Socket Url
description: Origin the browser connects to.
examples:
- https://ws.base44.com
socket_path:
type: string
title: Socket Path
description: Socket.IO path on that origin.
examples:
- /ws/socket.io/
expires_in:
type: integer
title: Expires In
description: >-
Seconds until the session and its token expire. A session is never
extended.
examples:
- 3600
type: object
required:
- session_id
- session_token
- socket_url
- socket_path
- expires_in
title: SocketSessionResponse
StandardErrorEnvelope:
properties:
error:
$ref: '#/components/schemas/StandardError'
description: What went wrong.
type: object
required:
- error
title: StandardErrorEnvelope
description: The error body returned in the standard envelope.
StandardError:
properties:
code:
type: string
title: Code
description: >-
Stable machine-readable cause of the failure. Match on this, not on
`message`.
example: not_found
message:
type: string
title: Message
description: Human-readable explanation. It isn't a stable contract.
example: App not found
details:
additionalProperties: true
type: object
title: Details
description: >-
Structured context for the failure, or an empty object when there's
none.
example: {}
type: object
required:
- code
- message
title: StandardError
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: >-
Personal access token, sent as `Authorization: Bearer `. Each
operation lists the permission it needs: `read_only` or `full_access`. A
full-access token can call every operation. A read-only token can call
only the operations that list `read_only`; anything else returns 403
`read_only_credential_route_not_allowed`.
WorkspaceApiKeyBearerAuth:
type: http
scheme: bearer
description: 'Workspace API key, sent as `Authorization: Bearer `.'
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.