ShipSwitch
Create an account

Integrate ShipSwitch in your code

Your application asks ShipSwitch whether a flag is on for a user, over HTTPS. Any language that can make an HTTP request works: there is nothing to install.

In three steps

From nothing to a flag read by your code:

  1. Create a project and a flag in the dashboard. A new project comes with a development, a staging and a production environment.
  2. Create an API key in the environment you want to read, and give it to your application as an environment variable.
  3. Ask for the flag where your code branches, with a default value in case ShipSwitch cannot be reached.

The examples below exist in cURL, JavaScript, Python, PHP, Go and Java. For any other language, translate the cURL call: it is one GET request with one header.

SDKs for TypeScript, Python and PHP, with a local cache and a fallback to the last known values, are being prepared for npm, PyPI and Packagist. Until they are published, use the HTTP API shown here.

Get an API key

Open a project, then Environments, choose an environment and create a key. Each key belongs to one environment: use a different key in development and in production, and the same code reads the right flags everywhere.

  • Client keys (ss_client_…) read flag values. They are the ones your application needs.
  • Management keys (ss_mgmt_…) can also change flags. Keep them on servers and in your CI, never in an application you ship.

A key is shown once, when it is created. Store it in your secret manager; if it leaks, rotate it from the same screen and the old one stops working immediately.

Read a flag

Ask for one flag by its key. The user is described in the query string. The answer holds the value served to that user: true or false for a boolean flag, a string, a number or a JSON document for the other types.

curl "https://shipswitch.io/api/v1/client/flags/new-checkout?userId=user_123&plan=premium" \
  -H "Authorization: Bearer $SHIPSWITCH_KEY"

# {"key":"new-checkout","value":true}

A flag that does not exist answers 404: every example falls back to its default value in that case.

Describe the user

What you send about the user is the context. ShipSwitch uses it for two things:

  • Percentage rollouts use userId to always put the same user on the same side. Without userId, a flag opened to less than 100% is off for that request.
  • Targeting rules compare the other attributes with what you configured: plan equals "premium", country is in a list, version is greater than a number.

Send any stable identifier as userId: an account id, or an anonymous id you keep in a cookie for visitors who are not signed in.

The context is used to compute the answer and is not stored. Do not send sensitive data: an identifier and a few technical attributes are enough. Up to 50 attributes per request.

Read every flag at once

To read several flags for one user, such as when a page loads, ask for all of them in one request.

POST /client/evaluate
curl -X POST "https://shipswitch.io/api/v1/client/evaluate" \
  -H "Authorization: Bearer $SHIPSWITCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context": {"userId": "user_123", "plan": "premium", "country": "FR"}}'

# {"flags": {"new-checkout": true, "max-items": 50, "banner": {"text": "Hello"}}}

Add "keys": ["new-checkout", "max-items"] to the body to get only those.

Flags that do not exist are left out of the answer: use your own default for them.

Good practices

A flag service must never be the reason your application is down.

  • Always have a default value, and use it when the request fails or times out.
  • Set a short timeout, around two seconds.
  • Cache the answers for a few seconds (30 is a good start) instead of asking on every request: a changed flag is then seen within that delay.
  • Read your flags on the server when you can. A client key in a browser or mobile application is visible to its users, who can then read your flag values.
  • Use one key per environment and per application, so that a key can be rotated without touching the others.

Be told when a flag changes

With a cache, a changed flag is seen when the cache expires. To see it at once, keep a connection open to the change stream: ShipSwitch sends a line each time a flag of the environment is modified.

GET /client/stream
curl -N "https://shipswitch.io/api/v1/client/stream" \
  -H "Authorization: Bearer $SHIPSWITCH_KEY"

event: ready
data: {}

event: change
data: {}

The stream says that something changed, not what: values depend on the user, so ask for them again when a change event arrives. A comment line is sent now and then to keep the connection alive; if it drops, open it again and fetch your flags once, in case a change was missed.

The TypeScript SDK does all of this with realtime: true.

Report errors to the autopilot

During an autopilot rollout, ShipSwitch turns the flag off by itself when too many of the users who have it hit errors. It learns about those errors from your application.

When something fails in the code behind a flag, report it with the flag key and the same userId you used to read the flag.

POST /client/errors
curl -X POST "https://shipswitch.io/api/v1/client/errors" \
  -H "Authorization: Bearer $SHIPSWITCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"flagKey": "new-checkout", "context": {"userId": "user_123"}}'

# 204 No Content

Reports only count for flags under an autopilot rollout, and only for users who have the flag on; the rest is ignored, so you can leave the call in place.

Change flags from a script

With a management key, a script or a CI job can read the configuration of every flag of its environment and change it: turn a flag on after a deploy, or widen a rollout.

/manage/flags
# Read the flags of the key's environment
curl "https://shipswitch.io/api/v1/manage/flags" \
  -H "Authorization: Bearer $SHIPSWITCH_MANAGEMENT_KEY"

# Turn a flag on for 25% of users
curl -X PUT "https://shipswitch.io/api/v1/manage/flags/new-checkout" \
  -H "Authorization: Bearer $SHIPSWITCH_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "rolloutPercentage": 25}'

The body accepts enabled, rolloutPercentage (0 to 100), value and offValue. Send only what changes. Every change appears in the audit log under the name of the key.

Management keys, the autopilot, approvals and notifications are part of the Pro and Business plans.

Show where flags are used in your code

The page of a flag can list the files and lines of your code that mention it. That is what tells you what to delete once a flag is ready to remove. ShipSwitch does not read your repositories: a job of your CI searches the code and sends what it found.

.github/workflows/shipswitch.yml
# .github/workflows/shipswitch.yml
name: ShipSwitch code references
on:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Report where flags are used
        env:
          SHIPSWITCH_MANAGEMENT_KEY: ${{ secrets.SHIPSWITCH_MANAGEMENT_KEY }}
        run: |
          API="https://shipswitch.io/api/v1"
          AUTH="Authorization: Bearer $SHIPSWITCH_MANAGEMENT_KEY"

          # The keys of the project's flags, one per line.
          curl -fsS "$API/manage/flags" -H "$AUTH" | jq -r '.[].key' > keys.txt

          # Every line of the repository that mentions one of them, as a
          # whole word: "new-checkout" is not found in "new-checkout-v2".
          if [ -s keys.txt ]; then
            git grep -n -I -F -f keys.txt -- . ':!keys.txt' > lines.txt || true
          else
            : > lines.txt
          fi
          jq -R -s --rawfile keys keys.txt '
            ($keys | split("\n") | map(select(length > 0))) as $all
            | [split("\n")[] | select(length > 0)
                | capture("^(?<path>[^:]+):(?<line>[0-9]+):(?<text>.*)$") as $found
                | $all[] as $key
                | select($found.text
                    | test("(^|[^A-Za-z0-9_-])" + $key + "($|[^A-Za-z0-9_-])"))
                | {flagKey: $key, path: $found.path, line: ($found.line | tonumber)}]
            | unique' lines.txt > references.json

          jq -n --slurpfile references references.json \
            --arg repository "$GITHUB_REPOSITORY" \
            --arg branch "$GITHUB_REF_NAME" \
            --arg commit "$GITHUB_SHA" \
            --arg link "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/blob/$GITHUB_SHA/{path}#L{line}" \
            '{repository: $repository, branch: $branch, commit: $commit,
              linkTemplate: $link, references: $references[0][:5000]}' \
            | curl -fsS -X PUT "$API/manage/code-references" \
                -H "$AUTH" -H "Content-Type: application/json" -d @-

This workflow does it on GitHub Actions with a management key stored as a secret. It needs nothing but git, curl and jq, so the same lines work on any CI. Each run replaces the previous result for the repository; a flag whose last mention was removed shows as no longer found.

The search looks for flag keys as whole words in tracked files. A key built at run time, such as a concatenated string, is not found.

Notifications and webhooks

ShipSwitch can tell your team, or your own tools, when a flag changes. An admin adds a destination under Organizations, Notifications: a Slack incoming webhook, which gets a sentence in a channel, or any https address, which gets a JSON document.

JSON
POST /your/address
Content-Type: application/json
X-ShipSwitch-Signature: sha256=3f5a...

{
  "id": "0199c1d2-...",
  "event": "flag.enabled",
  "occurredAt": "2026-11-20T21:04:11.512Z",
  "text": "`new-checkout` was turned on in production by Ada (project Web App).",
  "organization": { "id": "...", "name": "Analytical Engines" },
  "project": { "id": "...", "name": "Web App" },
  "actor": { "name": "Ada" },
  "data": { "key": "new-checkout", "environment": "production" }
}

A change is sent once, a moment after it happens, and tried again a few times if your address does not answer with a 2xx status.

Each delivery to an address of yours is signed with the secret shown when the destination was created. Check the signature before trusting the content:

Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

// `rawBody` is the body exactly as received, before any JSON parsing.
function isFromShipSwitch(rawBody, signatureHeader, secret) {
  const expected =
    'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const received = Buffer.from(signatureHeader ?? '');
  return (
    received.length === expected.length &&
    timingSafeEqual(received, Buffer.from(expected))
  );
}

Events: flag.created, flag.deleted, flag.enabled, flag.disabled, flag.configuration_updated, flag.rollout_started, flag.rollout_completed, flag.rollout_rolled_back, flag.rollout_cancelled.

Reference

Base address : https://shipswitch.io/api/v1

Every request carries the key in the Authorization header: Bearer followed by the key.

Endpoints
GET /client/flags/{key}Value of one flag for the user in the query string
GET /client/flagsValues of every flag for the user in the query string
POST /client/evaluateValues of every flag, or of the listed keys, for the user in the body
GET /client/streamServer-sent events: one at each change of the environment
POST /client/errorsReports an error met by a user of a flag
GET /manage/flagsConfiguration of every flag (management key)
PUT /manage/flags/{key}Changes the configuration of a flag (management key)
Status codes
200, 204The request succeeded
400The body or the query string is not valid
401The key is missing, unknown or revoked
403A client key was used where a management key is needed
404The flag does not exist in this project
429Too many requests: wait and try again

The reading endpoints accept 1,200 requests a minute. With a cache of a few seconds you will stay far below.