API reference · In your appFlags
Feature flags
Create and change a project's feature flags, their environments and targeting rules.
A flag has a value per environment and, in each, rules that pick a value for some visitors. Your app reads flags with @useorbits/flags, using the environment's key that deployments get as ORBITS_FLAGS. See Feature flags.
The flag object
Fields
keystringrequireddescriptionstringrequiredtypestringrequiredOne of
boolean,string,number.environmentsobjectrequiredShow 3 child fieldsHide child fields
productionFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
previewFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
developmentFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
created_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
updated_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
created_atstringrequiredupdated_atstringrequired
A project's feature flags
The Flags page: every flag, newest first, with each environment's setting. q matches the key or description, type narrows to one type; total counts them all, for "3 of 5 flags".
Permissions: Any team member. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Query parameters
qstringAt most 100 characters.
typestringOne of
boolean,string,number.
Response 200
The flags.itemsarray of FlagrequiredShow 8 child fieldsHide child fields
keystringrequireddescriptionstringrequiredtypestringrequiredOne of
boolean,string,number.environmentsobjectrequiredShow 3 child fieldsHide child fields
productionFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
previewFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
developmentFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
created_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
updated_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
created_atstringrequiredupdated_atstringrequired
totalintegerrequiredEvery flag in the project, whatever the filters.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"items": [
{
"key": "new-checkout",
"description": "description",
"type": "boolean",
"environments": {
"production": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": null,
"attribute": null,
"operator": null,
"values": null,
"serve": null,
"label": null
}
]
},
"preview": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": null,
"attribute": null,
"operator": null,
"values": null,
"serve": null,
"label": null
}
]
},
"development": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": null,
"attribute": null,
"operator": null,
"values": null,
"serve": null,
"label": null
}
]
}
},
"created_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"updated_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z"
}
],
"total": 1
}Create a flag
A boolean flag starts off in each environment unless environments.<name>.on says otherwise, at 100% rollout and with no rules. A string or number flag needs environments.<name>.value for all three. Keys are lowercase letters, digits and single dashes, unique in the project.
Permissions: Owners, admins and members. Viewers get 403.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonkeystringrequiredAt most 48 characters.
descriptionstringAt most 120 characters.
typestringrequiredOne of
boolean,string,number.environmentsobjectShow 3 child fieldsHide child fields
productionobjectShow 2 child fieldsHide child fields
onbooleanA boolean flag's switch.
valuestring | numberA string or number flag's value.
previewobjectShow 2 child fieldsHide child fields
onbooleanA boolean flag's switch.
valuestring | numberA string or number flag's value.
developmentobjectShow 2 child fieldsHide child fields
onbooleanA boolean flag's switch.
valuestring | numberA string or number flag's value.
Response 201
The new flag.keystringrequireddescriptionstringrequiredtypestringrequiredOne of
boolean,string,number.environmentsobjectrequiredShow 3 child fieldsHide child fields
productionFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
previewFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
developmentFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
created_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
updated_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
created_atstringrequiredupdated_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"key": "new-checkout",
"type": "boolean"
}'{
"key": "new-checkout",
"description": "description",
"type": "boolean",
"environments": {
"production": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"preview": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"development": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
}
},
"created_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"updated_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z"
}Each environment's ORBITS_FLAGS key
Deployments get their environment's key as ORBITS_FLAGS (and the API's address as ORBITS_API_URL) without asking. These are for code that runs elsewhere: put development's in .env.local to read Development's flags locally. A key reads its environment's flags and reports checks, nothing else.
Permissions: Owners, admins and members. Viewers get 403.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Response 200
The keys.productionstringrequiredpreviewstringrequireddevelopmentstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flag-keys" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"production": "ofl_cHJqXzE6cHJvZHVjdGlvbg.k3W…",
"preview": "preview",
"development": "development"
}A flag, its history and who it was checked for
The flag's page. history is newest first, 50 at most, each line written as the page says it. seen is each environment's last 24 hours as the SDK reported them: people the ids it was checked for, checks every check, with or without one.
Permissions: Any team member.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.flagstringrequired
Response 200
The flag.keystringrequireddescriptionstringrequiredtypestringrequiredOne of
boolean,string,number.environmentsobjectrequiredShow 3 child fieldsHide child fields
productionFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
previewFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
developmentFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
created_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
updated_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
created_atstringrequiredupdated_atstringrequiredhistoryarray of objectrequiredShow 4 child fieldsHide child fields
idstringrequiredbyFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
textstringrequiredatstringrequired
seenobjectrequiredShow 3 child fieldsHide child fields
productionFlagSeenrequiredShow 2 child fieldsHide child fields
peopleintegerrequiredchecksintegerrequired
previewFlagSeenrequiredShow 2 child fieldsHide child fields
peopleintegerrequiredchecksintegerrequired
developmentFlagSeenrequiredShow 2 child fieldsHide child fields
peopleintegerrequiredchecksintegerrequired
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"key": "new-checkout",
"description": "description",
"type": "boolean",
"environments": {
"production": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": null,
"values": [
null
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"preview": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": null,
"values": [
null
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"development": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": null,
"values": [
null
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
}
},
"created_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"updated_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z",
"history": [
{
"id": "id",
"by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"text": "Set Preview rollout to 10%",
"at": "2026-11-10T09:30:00Z"
}
],
"seen": {
"production": {
"people": 1,
"checks": 1
},
"preview": {
"people": 1,
"checks": 1
},
"development": {
"people": 1,
"checks": 1
}
}
}Change a flag's description
The key and type never change; make another flag for that.
Permissions: Owners, admins and members.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.flagstringrequired
Body
application/jsondescriptionstringAt most 120 characters.
Response 200
The flag.keystringrequireddescriptionstringrequiredtypestringrequiredOne of
boolean,string,number.environmentsobjectrequiredShow 3 child fieldsHide child fields
productionFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
previewFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
developmentFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
created_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
updated_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
created_atstringrequiredupdated_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"description": "description"
}'{
"key": "new-checkout",
"description": "description",
"type": "boolean",
"environments": {
"production": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"preview": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"development": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
}
},
"created_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"updated_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z"
}Delete a flag
The SDK stops getting it on its next refresh, and code checking it gets the default it passed.
Permissions: Owners, admins and members.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.flagstringrequired
Response 204
Deleted. No body.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout" \
-H "Authorization: Bearer $ORBITS_TOKEN"Switch a flag, set its rollout or its value in one environment
A boolean flag takes on and rollout (1–100, the share of ids it's on for); a string or number flag takes value. Fields left out stay as they are. Deployments see the change within seconds, without a redeploy.
Permissions: Owners, admins and members.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.flagstringrequiredenvironmentstringrequiredOne of
production,preview,development.
Body
application/jsononbooleanrolloutintegerFrom 1 to 100.
valuestring | number
Response 200
The flag.keystringrequireddescriptionstringrequiredtypestringrequiredOne of
boolean,string,number.environmentsobjectrequiredShow 3 child fieldsHide child fields
productionFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
previewFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
developmentFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
created_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
updated_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
created_atstringrequiredupdated_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X PUT "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"on": false,
"rollout": 1,
"value": "value"
}'{
"key": "new-checkout",
"description": "description",
"type": "boolean",
"environments": {
"production": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"preview": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"development": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
}
},
"created_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"updated_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z"
}Add a targeting rule
Rules are checked in order before the environment's switch: the first that matches decides, serve being on or off for a boolean flag and the value for the others. attribute names what the app passes to flag() (email, id, plan, user.country); one_of takes several values, every other operator one; comparisons ignore case, and an attribute the app didn't pass matches nothing. 20 rules at most.
Permissions: Owners, admins and members.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.flagstringrequiredenvironmentstringrequiredOne of
production,preview,development.
Body
application/jsonattributestringrequiredAt most 64 characters.
operatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredAt most 50 items.
serveboolean | string | numberrequired
Response 201
The flag.keystringrequireddescriptionstringrequiredtypestringrequiredOne of
boolean,string,number.environmentsobjectrequiredShow 3 child fieldsHide child fields
productionFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
previewFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
developmentFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
created_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
updated_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
created_atstringrequiredupdated_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production/rules" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"attribute": "email",
"operator": "equals",
"values": [
"@kudi.ng"
],
"serve": false
}'{
"key": "new-checkout",
"description": "description",
"type": "boolean",
"environments": {
"production": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"preview": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"development": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
}
},
"created_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"updated_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z"
}Change what a rule serves
Permissions: Owners, admins and members.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.flagstringrequiredenvironmentstringrequiredOne of
production,preview,development.rulestringrequired
Body
application/jsonserveboolean | string | numberrequired
Response 200
The flag.keystringrequireddescriptionstringrequiredtypestringrequiredOne of
boolean,string,number.environmentsobjectrequiredShow 3 child fieldsHide child fields
productionFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
previewFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
developmentFlagEnvironmentrequiredShow 4 child fieldsHide child fields
onbooleanrequiredA boolean flag's switch; always true for the others.
rolloutintegerrequiredFrom 1 to 100.
valuestring | number or nullrequiredA string or number flag's value; null for a boolean.
rulesarray of FlagRulerequiredShow 6 child fieldsHide child fields
idstringrequiredattributestringrequiredoperatorstringrequiredOne of
equals,not_equals,one_of,ends_with,starts_with,contains.valuesarray of stringrequiredserveboolean | string | numberrequiredlabelstringrequired
created_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
updated_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
created_atstringrequiredupdated_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production/rules/rule_1" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"serve": false
}'{
"key": "new-checkout",
"description": "description",
"type": "boolean",
"environments": {
"production": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"preview": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
},
"development": {
"on": false,
"rollout": 1,
"value": null,
"rules": [
{
"id": "id",
"attribute": "email",
"operator": "equals",
"values": [
"values"
],
"serve": false,
"label": "Email ends with @kudi.ng"
}
]
}
},
"created_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"updated_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z"
}Remove a rule
Permissions: Owners, admins and members.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.flagstringrequiredenvironmentstringrequiredOne of
production,preview,development.rulestringrequired
Response 204
Removed. No body.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production/rules/rule_1" \
-H "Authorization: Bearer $ORBITS_TOKEN"