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:
- Create a project and a flag in the dashboard. A new project comes with a development, a staging and a production environment.
- Create an API key in the environment you want to read, and give it to your application as an environment variable.
- 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.
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.
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.
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 ContentReports 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.
# 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
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.
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:
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.
| GET /client/flags/{key} | Value of one flag for the user in the query string |
|---|---|
| GET /client/flags | Values of every flag for the user in the query string |
| POST /client/evaluate | Values of every flag, or of the listed keys, for the user in the body |
| GET /client/stream | Server-sent events: one at each change of the environment |
| POST /client/errors | Reports an error met by a user of a flag |
| GET /manage/flags | Configuration of every flag (management key) |
| PUT /manage/flags/{key} | Changes the configuration of a flag (management key) |
| 200, 204 | The request succeeded |
|---|---|
| 400 | The body or the query string is not valid |
| 401 | The key is missing, unknown or revoked |
| 403 | A client key was used where a management key is needed |
| 404 | The flag does not exist in this project |
| 429 | Too 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.