HTTP API

All API access is over HTTPS and accessed from https://api.jamsocket.com.

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:

Authorization: Bearer <token>

Check authentication credentials

GET /auth

Returns {"status":"ok"} if auth headers are valid. Otherwise returns a 401 status code.

Requires auth headers (see Authentication)

Related CLI commands: jamsocket login, jamsocket logout

Services

Get service image

GET /user/:username/service/:service/image

Returns the image name for a given service.

Example response

{"status":"ok","imageName":"jamcr.io/taylor/my-service"}

Requires auth headers (see Authentication)

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,
  tag?: string,
  port?: number,
  env?: {
    [env_var: string]: string
  }
}

Note: environment variables pass in env may not be one of the reserved env vars PORT, JAMSOCKET_NAME, JAMSOCKET_URL, or JAMSOCKET_SERVICE.

Returns the newly-spawned backend’s name, url, status_url, and ready_url.

name - the backend’s ID
url - the public hostname 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)
require_bearer_token - if set to true, the result will include a bearer_token field containing a random string. This must be passed along with HTTP requests to the backend in order to access it. See backend-authentication for more information.

Example response

{
  "url": "https://2njmz.jamsocket.run",
  "name": "2njmz",
  "ready_url": "https://api.jamsocket.com/ready/2njmz/",
  "status_url": "https://api.jamsocket.com/backend/2njmz/status"
}

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

Related CLI commands: jamsocket spawn

Spawn tokens

Create a spawn token

POST /user/:username/service/:service/token

Generates a token that may be used to spawn backends for the provided service and with the options passed in the request body. This may be used to spawn backends from a browser client.

Request body:

{
  grace_period_seconds?: number,
  tag?: string,
  port?: number
}

Returns a spawn token.

Example response

{"token":"swEwvVzvG1B0ym6AmQnDflhmBqUAtM"}

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

Related CLI commands: jamsocket token create

Spawn a service with a token

POST /token/:token/spawn

Spawns the service with the options tied to the given spawn token. Optionally takes env vars in the request body.

Request body:

{
  env?: {
    [env_var]: string
  }
}

Note: spawning with a token does not require authentication. As a result, a token-based spawn may only pass environment variables the start with JAMSOCKET_. This is to prevent untrusted clients from setting arbitrary environment variables.

Returns the same response as a regular spawn. See spawn endpoint for more information.

Supports CORS

Requires Content-Type: application/json header.

Related CLI commands: jamsocket token spawn

Revoke a spawn token

DELETE /token/:token

Revokes an existing spawn token. A revoked token can no longer be used to spawn backends.

Returns {"status":"ok"} if token was successfully revoked.

Requires auth headers (see Authentication)

Related CLI commands: jamsocket token revoke

Backends

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: 
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:

data:{"state":"Ready","time":"2022-04-13T18:00:10.985294Z"}

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 a port
Ready - the backend is listening on the expected port
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

{"state":"Ready","time":"2022-04-13T18:00:21.719786Z"}

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

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 in order for Jamsocket to detect when the backend is ready and for Jamsocket to proxy outside requests to the backend. By default, PORT is 8080, but you may provide a port to use when spawning backends or creating spawn tokens.
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
- JAMSOCKET_NAME
- JAMSOCKET_URL
- JAMSOCKET_SERVICE
Backends that are spawned via token may be passed env vars that start with JAMSOCKET_. Token-based spawns are not authenticated and may be triggered by untrusted clients. Backend logic should treat env vars that start with JAMSOCKET_ as unsanitized user input.

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 new.jamcr.io.

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.