Skip to content

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, SPAWNER_NAME, SPAWNER_URL, or SPAWNER_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)

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

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.

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
    • SPAWNER_NAME
    • SPAWNER_URL
    • SPAWNER_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.

Authenticating with the Jamsocket Container Registry first requires you to generate an access token at app.jamsocket.com/settings. Access tokens contain a period which separates the "public" and "secret" portions of the token. When logging into the container registry with docker login, use the "public" portion (the substring before the period) as the username and the "secret" portion (the substring after the period) as the password. For example, for the token buXNtTekmnWkMR8q.FziyCb5CZiBM4XaglWIbF3emdH5QU3, use buXNtTekmnWkMR8q as the username and FziyCb5CZiBM4XaglWIbF3emdH5QU3 as the password.