Last Updated: October 16, 2026

The SGS API

The SGS API lets you tag the nodes on your SGS server, then route requests to nodes that carry a given tag. A typical use is to test each node against a site, tag the nodes that pass, and send that site’s traffic only to those nodes. You develop, run, and maintain any such connectivity tests yourself.

The SGS API is in limited release and is only available on some SGS servers. Contact your account manager to enable it.

The API is served on port 7443 of your SGS server (https://{sgsName}.salad.com:7443). Tag-based routing is available for HTTP CONNECT requests.

Routing requests to tagged nodes

Requesting a tag

Add the X-Sgs-Tag proxy header to your HTTP CONNECT request:

X-Sgs-Tag: {yourTag}

Tag names are case-sensitive. internal-site-a and Internal-Site-A are different tags.

How node selection works

For each request, SGS checks the following in order and uses the first one that matches:

X-Sgs-Machine-Id header. The request is pinned to that exact node (see Targeting a specific node).
X-Sgs-Tag header. SGS chooses from the nodes that are currently connected and have the tag.
Normal routing. If no connected node has the tag, SGS routes the request normally.

This means a tag never blocks traffic. If no connected node has the requested tag (for example, because a test was misconfigured and every node failed it), requests “fail open” to normal routing instead of failing.

Targeting a specific node

The X-Sgs-Machine-Id proxy header sends a request to a specific node. This is mainly useful for testing nodes one at a time.

If the node is not currently connected to your SGS server (it is offline, or it has been quarantined), the request fails immediately with 503 Service Unavailable. SGS does not fall back to another node.
If the node accepts the request but cannot reach the destination, SGS may retry the request on a different node.

A 503 on a pinned request usually just means the node is offline right now. It does not mean the node failed your test.

Authentication

Every API request requires your Salad-provided JWT:

curl https://{sgsName}.salad.com:7443/nodes \
  -H "Authorization: Bearer YOUR_SALAD_JWT"

Requests with a missing, invalid, or unauthorized token receive 401 Unauthorized. Your JWT was shared with your team during initial integration. If you need one, contact your account manager.

Endpoints

List all nodes

GET /nodes

Returns the nodes SGS has a record of, along with their tags.

This list includes nodes that are not currently connected. SGS keeps a node’s tags when it disconnects, so a node that comes back later still has the tags you gave it. The API does not currently tell you which nodes are online. If a node returns 503 when you target it with X-Sgs-Machine-Id, treat it as offline and test it again later.

Example response

{
  "nodes": [
    {
      "machine_id": "5ebfa363-6e0b-4db1-b9be-70ed4995d0b1",
      "tags": {
        "internal-site-a": 1,
        "internal-site-b": 1
      },
      "updated_at": "2026-05-04T05:41:05Z"
    }
  ]
}

machine_id: the node’s Salad machine ID.
tags: the node’s tags and their values. A node with no tags has an empty object.
updated_at: a UTC timestamp.

Retrieve a node

GET /nodes/{machineId}

Returns a single node in the same format as an entry in the nodes list.

Retrieve a node’s tags

GET /nodes/{machineId}/tags

Returns only the node’s tags.

Example response

{
  "internal-site-a": 1,
  "internal-site-b": 1
}

Update a node’s tags

PATCH /nodes/{machineId}/tags

Adds, changes, or removes tags on a node. The request body is a JSON object of tag names and values. Tags you leave out of the request are not changed.

Any value other than 0 adds the tag, or updates it if the node already has it.
A value of 0 removes the tag.

Use values from 0 to 1. Today, routing only checks whether a node has a tag, so 0.5 and 1 behave the same. Values between 0 and 1 are reserved for future weighted load balancing.

Use a prefix such as internal- for your tag names so they don’t collide with the capability names used by Salad’s Destination Health Checks.

Example request

{
  "internal-site-a": 1,
  "internal-site-b": 0,
  "internal-site-c": 1
}

This adds or keeps internal-site-a and internal-site-c, and removes internal-site-b.

Example response

The response contains the node’s full set of tags after the update:

{
  "internal-site-a": 1,
  "internal-site-c": 1
}

Remove all tags

DELETE /nodes/{machineId}/tags

Removes every tag from the node.

Errors

Errors return a JSON body with the HTTP status code and its name:

{
  "code": 404,
  "status": "Not Found"
}

Status	Cause
`400 Bad Request`	The `PATCH` body is not a JSON object of tag names and numeric values
`401 Unauthorized`	The JWT is missing, invalid, or not authorized for this SGS server
`404 Not Found`	`PATCH` was sent for a machine ID that SGS has no record of

Common workflows

Qualifying nodes for a new site

List all nodes and get their machine IDs:

curl https://{sgsName}.salad.com:7443/nodes \
  -H "Authorization: Bearer YOUR_SALAD_JWT" | jq -r '.nodes[].machine_id'

For each machine ID, test the node against the target site by pinning the request to it. Don’t add an X-Sgs-Tag header while testing.
curl --proxy-header "X-Sgs-Machine-Id: {machineId}" \ -x "https://{sessionId}:{password}@{sgsName}.salad.com:8443" \ https://target-site.com
If the proxy returns 503, the node is usually offline. Skip it and leave its tags as they are.

Tag the nodes that passed, using a unique tag name such as internal-target-site. Set the tag to 0 on nodes that failed:

curl -X PATCH https://{sgsName}.salad.com:7443/nodes/{machineId}/tags \
  -H "Authorization: Bearer YOUR_SALAD_JWT" \
  -H "Content-Type: application/json" \
  -d '{"internal-target-site": 1}'

Check that the tags were updated:

curl https://{sgsName}.salad.com:7443/nodes/{machineId}/tags \
  -H "Authorization: Bearer YOUR_SALAD_JWT"

Route the site’s traffic to the tagged nodes by adding the proxy header X-Sgs-Tag: internal-target-site to your requests.
Nodes connect and disconnect over time, and their ability to reach a site can change. Repeat steps 1–4 regularly, at least every 2–3 hours. Nodes that are offline during a pass keep their existing tags, and SGS only routes to tagged nodes that are connected.

Explanation

Tutorials

Reference

SGS API

The SGS API

Routing requests to tagged nodes

Requesting a tag

How node selection works

Targeting a specific node

Authentication

Endpoints

List all nodes

Example response

Retrieve a node

Retrieve a node’s tags

Example response

Update a node’s tags

Example request

Example response

Remove all tags

Errors

Common workflows

Qualifying nodes for a new site

​The SGS API

​Routing requests to tagged nodes

​Requesting a tag

​How node selection works

​Targeting a specific node

​Authentication

​Endpoints

​List all nodes

​Example response

​Retrieve a node

​Retrieve a node’s tags

​Example response

​Update a node’s tags

​Example request

​Example response

​Remove all tags

​Errors

​Common workflows

​Qualifying nodes for a new site

The SGS API

Routing requests to tagged nodes

Requesting a tag

How node selection works

Targeting a specific node

Authentication

Endpoints

List all nodes

Example response

Retrieve a node

Retrieve a node’s tags

Example response

Update a node’s tags

Example request

Example response

Remove all tags

Errors

Common workflows

Qualifying nodes for a new site