Platform
API v2

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.

OptionDescription
keywhen 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.
userwhen 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.)
authwhen 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.)
spawnmay 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)

OptionDescription
tagwhen 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.
clusterthe cluster to spawn the session backend to. (Only relevant for Jamsocket customers who have multiple clusters.)
lifetime_limit_secondsthe maximum amount of time (in seconds) the backend is allowed to run. Jamsocket will terminate the backend if this threshold is reached.
max_idle_secondsthe 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.)
executablean 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)

OptionDescription
mountmay 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.
enva 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_limitsa 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)

OptionDescription
memory_limit_bytesa 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_percentthe percentage of the cpu_period window's cycles that the session backend is allowed to use.
cpu_periodthe 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_limitthe 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

connect-request-example
{
  "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

FieldDescription
backend_idthe backend’s ID (sometimes called the backend's "name")
urlthe connection url used to route requests to the spawned backend
tokenthe token included in the connection URL
secret_tokenan 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_urla browser-friendly URL that displays a loading page and which redirects to the backend’s url once the backend has a ready status
status_urla Jamsocket API endpoint that returns the backend’s most recent status (see the /backend/{backend_id}/status endpoint)
statusthe 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
spawnedis 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

connect-response-example
{
  "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

StatusDescription
scheduledthe backend has been created and scheduled to a VM
loadingthe image is being fetched
startingthe image has been fetched and is being started
waitingthe image has been started but a server has not been detected on port 8080
readythe backend is listening on port 8080
terminatingthe backend has been sent a SIGINT
hard-terminatedthe backend is being forcibly stopped
terminatedthe 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 KindDescription
softthe backend was sent a SIGINT signal (a terminating status is always a soft termination)
hardthe 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 ReasonDescription
sweptthe backend was swept automatically after max_idle_seconds or lifetime_limit_seconds
externala termination signal was sent by the Jamsocket platform or via the API
startup_timeouta timeout occurred while waiting for the backend to become ready
key_expiredan error in the Jamsocket platform prevented the VM from renewing the backend's key
lostthe 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:

FieldDescription
termination_kindsame as above, but may also be null if the backend exited or failed on its own
termination_reasonsame as above, but may also be null if the backend exited or failed on its own
exit_errorindicates 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 (always 8080) - 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).

Built by Jamsocket.