API Reference


All API access is over HTTPS and accessed from


Create service

POST /user/:username/service

Request body:

{ name: string }

Returns { "status": "ok" } if successful.


Requires auth headers (see Authentication) and Content-Type: application/json header.


Related CLI commands: jamsocket service create

Get a list of services

GET /user/:username/services

Returns a list of the user’s services.

Example response

{ "services": ["hello-world", "my-service"] }

Requires auth headers (see Authentication)


Related CLI commands: jamsocket service list

Spawn a service

POST /user/:username/service/:service/spawn

Request body:

  grace_period_seconds?: number,
  lock?: string,
  service_environment?: string,
  env?: {
    [env_var: string]: string


  1. A service_environment is the name of the Service Environment you'd like to spawn to. Learn more about Service Environments here.
  2. Environment variables passed in env may not be one of the reserved env vars PORT, SESSION_BACKEND_ID, SESSION_BACKEND_KEY, SESSION_BACKEND_FENCING_TOKEN, or JAMSOCKET_SERVICE. Learn more about the environment variables we pass into all backend containers here.

Returns the following values:

  • name - the backend’s ID
  • url - the connection url used to route requests to the spawned backend
  • 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 Loading but may be another status if the backend returned was already running due to spawning with a lock
  • 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 lock (read more about spawning with locks)

Example response

  "url": "",
  "name": "8nyg2",
  "ready_url": "",
  "status_url": "",
  "spawned": true,
  "status": "Loading"

Requires auth headers (see Authentication) and Content-Type: application/json header.


Related CLI commands: jamsocket spawn


Get a backend's logs

GET /backend/:backend_id/logs

Streams application logs from the given backend.

Example response

data: > node-hello-world@0.0.1 start
data: > node src/server.js
data: Example app listening on port 8080

Requires auth headers (see Authentication) and Accept: text/event-stream header.


Related CLI commands: jamsocket logs

Get a backend's status stream

GET /backend/:backend_id/status/stream

Response is a stream where each line looks like:


Backend statuses

  • Loading - the backend has been created, and the image is being fetched

  • Starting - the image has been fetched and is running but is not yet listening on port 8080

  • Ready - the backend is listening on port 8080

  • Swept - the backend was terminated by Jamsocket because all connections were closed for the grace period

  • Exited - the backend exited on its own with a zero status

  • ErrorLoading - a failure occurred while loading the image

  • ErrorStarting - a failure occurred while starting the backend

  • TimedOutBeforeReady - a timeout occurred while waiting for the backend to become Ready

  • Failed - the backend exited on its own with a non-zero status

  • Terminated - the backend was terminated externally

  • Lost - the backend stopped running but its status wasn't updated due to a Jamsocket error


Supports CORS


Requires Accept: text/event-stream header.

Get a backend's current status

GET /backend/:backend_id/status

Same as /backend/:backend_id/status/stream except returns only the most recent status.

Example response


Supports CORS

Backend ready page

GET /backend/:backend_id/ready

Serves a webpage that shows a loading screen for newly-spawned backends. The page listens for the backend’s Ready event, after which it does a client-side redirect to the backend’s url.

Terminate a backend

POST /backend/:backend_id/terminate

Terminate a backend. In most cases, you do not need to call this; backends will be terminated automatically after a period with no open connections (see grace_period_seconds in the spawn request.)

Returns {"status":"ok"} if termination request was successfully sent to backend.


Requires auth headers (see Authentication)


Related CLI commands: jamsocket terminate


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)

Working directly with the Jamsocket Container Registry

It is generally recommended that you use the Jamsocket CLI to push images to the Jamsocket Container Registry. However, it is possible to push to and pull from the container registry directly.

The registry is hosted at

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 (opens in a new tab).

Jamsocket is built by Drifting in Space.