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,
  lock?: string,
  require_bearer_token?: boolean,
  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 following values:

  • 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)
  • 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)
  • bearer_token - if the request has require_bearer_token: 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",
  "spawned": true
}

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

Related CLI commands: jamsocket spawn

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.
  • 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

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.