HTTP API v2

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:

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.

Spawn Config (fields for the spawn option config)

Executable Config (fields for the spawn.executable option config)

Resource Limits Config (fields for the spawn.executable.resource_limits option config)

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

{
  "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

Example response

{
  "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/"
}

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

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_reason - a string indicating the reason for the termination, possible values include:

The terminated status may include the following extra metadata:

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"}

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"
    }
  ]
}

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"
      }
    }
  ]
}

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"
      }
    }
  ]
}

Terminate a backend

POST /v2/backend/{backend_id}/terminate

Sends a SIGTERM 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.

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

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}

Services

Create a service

POST /v2/account/{account}/service

Request body:

{ name: string }

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

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"] }

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"
}

Delete a service

POST /v2/service/{account}/{service}/delete

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

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"
    }
  ]
}

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.

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. Most applications will not need to use this.

Working directly with 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.