HTTP API v2
This documentation is for the latest version of the API. You can see documentation for v1 of the API here.
All API access is over HTTPS and accessed from https://api.jamsocket.com/v2/
.
Authentication
Jamsocket uses access tokens for authentication with its API. For those endpoints which require authentication, the Jamsocket API uses a Bearer Authorization header like the following, where <token>
is an access token you've generated on the Jamsocket Settings page (opens in a new tab):
Authorization: Bearer <token>
Backends
Get a connection URL for a backend
POST /v2/service/{account}/{service}/connect
Request body options
Note: the entire request body itself and all values in it are optional.
Option | Description |
---|---|
key | when provided, returns a running backend that was started with the same key. If no running backend holds the given key, a new backend will be spawned. Learn more about keys in our keys explainer. |
user | when provided, the connection URL returned will have the user value passed in the x-verified-username header on every HTTP request forwarded to the session backend. (Jamsocket guarantees that any header starting with x-verified-* can't be forged by the client.) |
auth | when provided, the connection URL returned will have the JSON-serialized auth value passed in the x-verified-user-data header on every HTTP request forwarded to the session backend. (Jamsocket guarantees that any header starting with x-verified-* can't be forged by the client.) |
spawn | may be a Spawn Config or false to prevent spawning a new backend when no running backend holds the provided key . (See Spawn Config below for more details.) |
Spawn Config (fields for the spawn
option config)
Option | Description |
---|---|
tag | when provided, the backend is spawned with the most recent image with the same tag. You may also pass an image digest as the tag value. |
cluster | the cluster to spawn the session backend to. (Only relevant for Jamsocket customers who have multiple clusters.) |
lifetime_limit_seconds | the maximum amount of time (in seconds) the backend is allowed to run. Jamsocket will terminate the backend if this threshold is reached. |
max_idle_seconds | the amount of time (in seconds) a backend will run after all its connections are closed. Jamsocket will terminate the backend if this threshold is reached. (By default, this value is 300 seconds.) |
executable | an Executable Config for the backend's executor. Right now, only Docker is supported as an executor. (See Executable Config below for more details.) |
Executable Config (fields for the spawn.executable
option config)
Option | Description |
---|---|
mount | may be true or a path which identifies a directory to mount into the session backend. This feature requires special configuration of the VM running your backends. Contact us if you're interested in using this feature. |
env | a dictionary of key:value pairs to be set as environment variables in the session backend's container. Note: Environment variables passed in env may not be one of the reserved env vars PORT , SESSION_BACKEND_ID , SESSION_BACKEND_KEY , or SESSION_BACKEND_FENCING_TOKEN . Learn more about the environment variables we pass into all backend containers here. |
resource_limits | a Resource Limits Config for setting resource limits on the session backend. (See Resource Limits Config below for more details.) |
Resource Limits Config (fields for the spawn.executable.resource_limits
option config)
Option | Description |
---|---|
memory_limit_bytes | a memory limit (given in bytes) which, when exceeded, will cause the session backend to be terminated. This can be used to prevent a session backend from consuming too much memory on a VM and, thus, affecting the performance or availability of your other session backends. |
cpu_period_percent | the percentage of the cpu_period window's cycles that the session backend is allowed to use. |
cpu_period | the window of time (in microseconds) that's used when limiting CPU with cpu_period_percent . Only relevant when setting cpu_period_percent . (defaults to 100_000 - i.e. 100ms) |
cpu_time_limit | the total CPU time a session backend is allowed to use (in seconds). |
Request body schema
{
key?: string
user?: string
auth?: Record<string, any>
spawn?: boolean | {
tag?: string
lifetime_limit_seconds?: number
max_idle_seconds?: number
executable?: {
mount?: string | boolean
env?: Record<string, string>
resource_limits?: {
memory_limit_bytes?: number
}
}
}
}
Example request
{
"key": "document-123",
"user": "user-123",
"auth": {
"can_write": true
},
"spawn": {
"max_idle_seconds": 300,
"executable": {
"env": {
"MY_ENV_VAR": "foo"
},
"resource_limits": {
"memory_limit_bytes": 1000000000
}
}
}
}
Response body
Field | Description |
---|---|
backend_id | the backend’s ID (sometimes called the backend's "name") |
url | the connection url used to route requests to the spawned backend |
token | the token included in the connection URL |
secret_token | an additional security token that you may choose to include in requests to your session backend. If you choose to have this token sent from a client, the session backend should check that the value matches the one provided by Jamsocket in the x-verified-secret header of the request. (Jamsocket guarantees that any header starting with x-verified-* can't be forged by the client.) |
ready_url | a browser-friendly URL that displays a loading page and which redirects to the backend’s url once the backend has a ready status |
status_url | a Jamsocket API endpoint that returns the backend’s most recent status (see the /backend/{backend_id}/status endpoint) |
status | the current status of the backend returned from the spawn request, is usually scheduled but may be another status if the backend returned was already running due to spawning with a key |
spawned | is true if the spawn request resulted in a newly-spawned backend, may be false if an existing backend is currently holding the given key (read more about spawning with keys) |
Example response
{
"backend_id": "knrv5",
"spawned": true,
"status": "scheduled",
"token": "4ahosrz8D53AmXj-Pzs0XlGANt3yG56asVqvNVzma9s",
"url": "https://knrv5.p.jamsocket.net/4ahosrz8D53AmXj-Pzs0XlGANt3yG56asVqvNVzma9s/",
"secret_token": "qB9Tky7m10ym-x0w5I6eTn41odJawYwVW4EgabC4r12",
"status_url": "https://api.jamsocket.com/v2/backend/knrv5/status",
"ready_url": "https://ready.jamsocket.com/knrv5/4ahosrz8D53AmXj-Pzs0XlGANt3yG56asVqvNVzma9s/"
}
Requires auth headers (see Authentication) and Content-Type: application/json
header.
Get a backend's current status
GET /v2/backend/{backend_id}/status
Returns a backend's most recent status.
Example responses
{
"status": "ready",
"time": "2024-01-02T01:23:45.678Z"
}
{
"status": "terminating",
"termination_reason": "swept",
"termination_kind": "soft",
"time": "2024-01-02T01:28:45.678Z"
}
{
"status": "terminated",
"termination_reason": "swept",
"termination_kind": "soft",
"exit_error": false,
"time": "2024-01-02T01:28:45.891Z"
}
{
"status": "terminated",
"exit_error": true,
"time": "2024-01-02T01:30:45.678Z"
}
Backend statuses
Status | Description |
---|---|
scheduled | the backend has been created and scheduled to a VM |
loading | the image is being fetched |
starting | the image has been fetched and is being started |
waiting | the image has been started but a server has not been detected on port 8080 |
ready | the backend is listening on port 8080 |
terminating | the backend has been sent a SIGINT |
hard-terminated | the backend is being forcibly stopped |
terminated | the backend has stopped running |
The terminating
and hard-terminating
statuses may include the following extra metadata:
termination_kind
- indicates whether the termination was a soft termination or a hard termination
Termination Kind | Description |
---|---|
soft | the backend was sent a SIGINT signal (a terminating status is always a soft termination) |
hard | the backend container was forcibly stopped (a hard-terminating status is always a hard termination) |
termination_reason
- a string indicating the reason for the termination, possible values include:
Termination Reason | Description |
---|---|
swept | the backend was swept automatically after max_idle_seconds or lifetime_limit_seconds |
external | a termination signal was sent by the Jamsocket platform or via the API |
startup_timeout | a timeout occurred while waiting for the backend to become ready |
key_expired | an error in the Jamsocket platform prevented the VM from renewing the backend's key |
lost | the backend stopped running but its status wasn't updated due to an error in the Jamsocket platform |
The terminated
status may include the following extra metadata:
Field | Description |
---|---|
termination_kind | same as above, but may also be null if the backend exited or failed on its own |
termination_reason | same as above, but may also be null if the backend exited or failed on its own |
exit_error | indicates if the container exited with a non-zero error code (is either true or false ) |
The /v2/backend/{backend_id}
endpoint returns more detailed metadata for terminated
statuses, including an exit_code
, since it is an authenticated endpoint.
This endpoint supports CORS (learn more).
Get a backend's status stream
GET /v2/backend/{backend_id}/status/stream
Streams a backend's statuses with a standard server-sent events (SSE) format. Statuses have the same format as those returned from the /v2/backend/{backend_id}/status
endpoint. The response is a stream where each line looks like:
data:{"status":"ready","time":"2024-01-02T01:23:45.678Z"}
This endpoint supports CORS (learn more).
Get a backend's metadata
GET /v2/backend/{backend_id}
Gets information about a backend.
Example response
{
"account_name": "taylor",
"cluster_name": "p.jamsocket.net",
"created_at": "2024-01-02T01:02:34.567Z",
"environment_name": "default",
"id": "kg5ff",
"image_digest": "sha256:c35dd2db3acdce8b6e348b5f2ac4f82f97cef4a5a833893a17f930ce2de97180",
"key": "my-key",
"max_mem_bytes": 1234567,
"service_name": "my-service",
"statuses": [
{
"time": "2024-01-02T01:02:34.567Z",
"status": "scheduled"
},
{
"time": "2024-01-02T01:02:34.678Z",
"status": "loading"
},
{
"time": "2024-01-02T01:02:34.789Z",
"status": "starting"
},
{
"time": "2024-01-02T01:02:34.890Z",
"status": "waiting"
},
{
"time": "2024-01-02T01:02:35.123Z",
"status": "ready"
},
{
"time": "2024-01-02T01:30:00.123Z",
"status": "terminating",
"last_status": "ready",
"termination_reason": "external"
},
{
"time": "2024-01-02T01:30:00.234Z",
"status": "terminated",
"exit_code": null,
"last_status": "ready",
"terminatation_reason": "external",
"termination_kind": "soft"
}
]
}
Requires auth headers (see Authentication).
Get backends by service
GET /v2/service/{account}/{service}/backends?start={timestamp}&end={timestamp}
Returns a list of backends for a given service with optional start
and end
query param filters. The start
and end
query params are both ISO 8601 datetimes that look like 2024-01-23T04:56:00Z
. Backends are filtered and sorted in reverse chronological order by their created_at
field.
Example response
{
"backends": [
{
"account_name": "taylor",
"cluster_name": "p.jamsocket.net",
"created_at": "2024-01-02T12:34:56.789Z",
"environment_name": "default",
"id": "abcdef",
"image_digest": "sha256:a8bd741c8d4dd3afe4517f5fad29c150319cb411ed6bc3647346b2c4042771c5",
"key": "my-key",
"max_mem_bytes": 12345678,
"ready_timestamp": "2024-01-02T12:34:57.123Z",
"service_name": "my-service",
"status": {
"status": "ready",
"time": "2024-01-02T12:34:57.123Z"
}
}
]
}
Requires auth headers (see Authentication).
Get an account's running backends
GET /v2/account/{account}/backends
Gets all the currently running backends across all of a given account's services.
Example response
{
"running_backends": [
{
"account_name": "taylor",
"cluster_name": "p.jamsocket.net",
"created_at": "2024-01-02T12:34:56.789Z",
"environment_name": "default",
"id": "abcde",
"image_digest": "sha256:53671da1930d42c1ead1448211f97610d21b225cfc52cf8e73393d699f831f73",
"key": "my-key",
"service_name": "my-service",
"status": {
"status": "ready",
"time": "2024-01-02T12:35:00.123Z"
}
}
]
}
Requires auth headers (see Authentication).
Terminate a backend
POST /v2/backend/{backend_id}/terminate
Sends a SIGINT signal to the backend container. In most cases, you do not need to call this; backends will be terminated
automatically after they hit max_idle_seconds
or lifetime_limit_seconds
.
Optionally, takes the body {"hard":true}
for a hard termination (this forcibly stops the backend container).
Returns {"status":"ok"}
if termination signal was successfully sent to backend.
Requires auth headers (see Authentication) and Content-Type: application/json
header.
Get a backend's logs
GET /v2/backend/{backend_id}/logs/stream
Streams application logs from the given backend using a standard Server-Sent Events format.
Example response
data: > node-hello-world@0.0.1 start
data: > node src/server.js
data:
data: Example app listening on port 8080
Requires auth headers (see Authentication).
Stream a backend's metrics
GET /v2/backend/{backend_id}/metrics/stream
Streams metrics for the given backend using a standard Server-Sent Events format.
Example response
data:{"backend_id":"abcde","cpu_used":10000000,"mem_available":1234567890,"mem_limit":1234567890,"mem_used":12345678,"sys_cpu":2000000000}
Requires auth headers (see Authentication).
Services
Create a service
POST /v2/account/{account}/service
Request body:
{ name: string }
Returns { "status": "ok" }
if successful.
Requires auth headers (see Authentication) and Content-Type: application/json
header.
Get a list of services
GET /v2/account/{account}/services
Returns a list of the user’s services.
Example response
{ "services": ["hello-world", "my-service"] }
Requires auth headers (see Authentication).
Get a service
GET /v2/service/{account}/{service}
Returns an existing service.
Example response
{
"account_name": "taylor",
"created_at": "2024-01-02T01:23:45.678Z",
"environments": [
{
"cluster": "p.jamsocket.net",
"created_at": "2024-01-02T01:23:45.678Z",
"image_tag": "latest",
"last_spawned_at": "2024-01-05T01:23:45.678Z",
"name": "default"
}
],
"image_name": "registry.jamsocket.com/taylor/my-service",
"last_image_digest": "sha256:a8bd741c8d4dd3afe4517f5fad29c150319cb411ed6bc3647346b2c4042771c5",
"last_image_upload_time": "2024-01-02T01:34:56.789Z",
"last_spawned_at": "2024-01-05T01:23:45.678Z",
"name": "my-service"
}
Requires auth headers (see Authentication).
Delete a service
POST /v2/service/{account}/{service}/delete
Returns { "status": "ok" }
if successful.
Requires auth headers (see Authentication).
Get a service's images
GET /v2/service/{account}/{service}/images
Returns a list of images that have been pushed for a given service. Images may include git_commit
metadata if the image was pushed with the Jamsocket Deploy Github Action or the Jamsocket CLI push
command's --include-git-commit
.
Example response
{
"images": [
{
"digest": "sha256:1234741c8d4dd3afe4517f5fad29c150319cb411ed6bc3647346b2c4042771c5",
"git_commit": {
"branch": "main",
"hash": "12345bbee92bb759732341eaddf4ef7dfc80be5b",
"message": "my commit message",
"repository": "my-github-user/my-github-repo"
},
"repository": "taylor/my-service",
"tag": "latest",
"upload_time": "2024-01-02T03:45:56Z"
}
]
}
Requires auth headers (see Authentication).
Update the image a service spawns with
POST /v2/service/{account}/{service}/update
Provide an image tag or image digest for a service to use by default when spawning new backend containers. This configuration is ignored when a connect request contains a specific image to spawn (see spawn.tag
field in connect request).
Request body:
{
image_tag: string
}
Returns { "status": "ok" }
if successful.
Requires auth headers (see Authentication) and Content-Type: application/json
header.
CORS
Endpoints that support CORS currently allow all origins to read the response.
Backend Containers
- Backends must listen on the port provided by the
PORT
env var (8080
) in order for Jamsocket to detect when the backend is ready and for Jamsocket to proxy outside requests to the backend. - Currently Jamsocket will only allow HTTP requests and Sockets connections to be proxied to the backend.
- All backends will have the following reserved env vars passed to them. Env vars with these names passed by the user when spawning will be overridden by the platform-provided values.
PORT
(always8080
) - this is the port that session backend requests will be proxied to. You shoud run a server in your session backend on this port.SESSION_BACKEND_ID
- a short, unique alphanumeric ID for your backend. This appears in the dashboard and can be used with the Jamsocket CLI. (Note: this is sometimes called the backend's "name".)SESSION_BACKEND_KEY
- this is the key (previously known as the "lock") your backend was spawned with. (Learn more about keys in our keys explainer.)SESSION_BACKEND_FENCING_TOKEN
- this is a number that increases every time the key is assigned. It can be used as a fencing token (opens in a new tab). Most applications will not need to use this.
Working directly with the Jamsocket Container Registry
It is recommended to use either (1) the Jamsocket Github Action or (2) the Jamsocket CLI push
command to push images to the Jamsocket Container Registry.
It is possible to push to and pull from the Jamsocket Container Registry directly. The registry is hosted at registry.jamsocket.com
, and images are expected to follow the naming scheme [ACCOUNT]/[SERVICE]
. For example, taylor/hello-world
.
When logging into the container registry with docker login
, use the account name as the username and an access token as the password. You can generate an access token at app.jamsocket.com/settings (opens in a new tab).