OrbitsDocs
esc
    Open Orbits
    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

    • keystringrequired
    • descriptionstringrequired
    • typestringrequired

      One of boolean, string, number.

    • environmentsobjectrequired
      Show 3 child fields
      • productionFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • previewFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • developmentFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
    • created_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • updated_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • created_atstringrequired
    • updated_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.

    GET/v1/teams/{team}/projects/{project}/flags
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Query parameters

    • qstring

      At most 100 characters.

    • typestring

      One of boolean, string, number.

    Response 200

    The flags.
    • itemsarray of Flagrequired
      Show 8 child fields
      • keystringrequired
      • descriptionstringrequired
      • typestringrequired

        One of boolean, string, number.

      • environmentsobjectrequired
        Show 3 child fields
        • productionFlagEnvironmentrequired
          Show 4 child fields
          • onbooleanrequired

            A boolean flag's switch; always true for the others.

          • rolloutintegerrequired

            From 1 to 100.

          • valuestring | number or nullrequired

            A string or number flag's value; null for a boolean.

          • rulesarray of FlagRulerequired
            Show 6 child fields
            • idstringrequired
            • attributestringrequired
            • operatorstringrequired

              One of equals, not_equals, one_of, ends_with, starts_with, contains.

            • valuesarray of stringrequired
            • serveboolean | string | numberrequired
            • labelstringrequired
        • previewFlagEnvironmentrequired
          Show 4 child fields
          • onbooleanrequired

            A boolean flag's switch; always true for the others.

          • rolloutintegerrequired

            From 1 to 100.

          • valuestring | number or nullrequired

            A string or number flag's value; null for a boolean.

          • rulesarray of FlagRulerequired
            Show 6 child fields
            • idstringrequired
            • attributestringrequired
            • operatorstringrequired

              One of equals, not_equals, one_of, ends_with, starts_with, contains.

            • valuesarray of stringrequired
            • serveboolean | string | numberrequired
            • labelstringrequired
        • developmentFlagEnvironmentrequired
          Show 4 child fields
          • onbooleanrequired

            A boolean flag's switch; always true for the others.

          • rolloutintegerrequired

            From 1 to 100.

          • valuestring | number or nullrequired

            A string or number flag's value; null for a boolean.

          • rulesarray of FlagRulerequired
            Show 6 child fields
            • idstringrequired
            • attributestringrequired
            • operatorstringrequired

              One of equals, not_equals, one_of, ends_with, starts_with, contains.

            • valuesarray of stringrequired
            • serveboolean | string | numberrequired
            • labelstringrequired
      • created_byFlagPersonrequired
        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • updated_byFlagPersonrequired
        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • created_atstringrequired
      • updated_atstringrequired
    • totalintegerrequired

      Every 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"
    Response 200
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/flags
    Full tokenNeeds Idempotency-KeyReturns201Created

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • keystringrequired

      At most 48 characters.

    • descriptionstring

      At most 120 characters.

    • typestringrequired

      One of boolean, string, number.

    • environmentsobject
      Show 3 child fields
      • productionobject
        Show 2 child fields
        • onboolean

          A boolean flag's switch.

        • valuestring | number

          A string or number flag's value.

      • previewobject
        Show 2 child fields
        • onboolean

          A boolean flag's switch.

        • valuestring | number

          A string or number flag's value.

      • developmentobject
        Show 2 child fields
        • onboolean

          A boolean flag's switch.

        • valuestring | number

          A string or number flag's value.

    Response 201

    The new flag.
    • keystringrequired
    • descriptionstringrequired
    • typestringrequired

      One of boolean, string, number.

    • environmentsobjectrequired
      Show 3 child fields
      • productionFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • previewFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • developmentFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
    • created_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • updated_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • created_atstringrequired
    • updated_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"
      }'
    Response 201
    {
      "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.

    GET/v1/teams/{team}/projects/{project}/flag-keys
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Response 200

    The keys.
    • productionstringrequired
    • previewstringrequired
    • developmentstringrequired

    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"
    Response 200
    {
      "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.

    GET/v1/teams/{team}/projects/{project}/flags/{flag}
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • flagstringrequired

    Response 200

    The flag.
    • keystringrequired
    • descriptionstringrequired
    • typestringrequired

      One of boolean, string, number.

    • environmentsobjectrequired
      Show 3 child fields
      • productionFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • previewFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • developmentFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
    • created_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • updated_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • created_atstringrequired
    • updated_atstringrequired
    • historyarray of objectrequired
      Show 4 child fields
      • idstringrequired
      • byFlagPersonrequired
        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • textstringrequired
      • atstringrequired
    • seenobjectrequired
      Show 3 child fields
      • productionFlagSeenrequired
        Show 2 child fields
        • peopleintegerrequired
        • checksintegerrequired
      • previewFlagSeenrequired
        Show 2 child fields
        • peopleintegerrequired
        • checksintegerrequired
      • developmentFlagSeenrequired
        Show 2 child fields
        • peopleintegerrequired
        • checksintegerrequired

    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"
    Response 200
    {
      "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.

    PATCH/v1/teams/{team}/projects/{project}/flags/{flag}
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • flagstringrequired

    Body

    application/json
    • descriptionstring

      At most 120 characters.

    Response 200

    The flag.
    • keystringrequired
    • descriptionstringrequired
    • typestringrequired

      One of boolean, string, number.

    • environmentsobjectrequired
      Show 3 child fields
      • productionFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • previewFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • developmentFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
    • created_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • updated_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • created_atstringrequired
    • updated_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"
      }'
    Response 200
    {
      "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.

    DELETE/v1/teams/{team}/projects/{project}/flags/{flag}
    Full tokenReturns204No Content

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project 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"
    HTTP/1.1 204 No Content

    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.

    PUT/v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • flagstringrequired
    • environmentstringrequired

      One of production, preview, development.

    Body

    application/json
    • onboolean
    • rolloutinteger

      From 1 to 100.

    • valuestring | number

    Response 200

    The flag.
    • keystringrequired
    • descriptionstringrequired
    • typestringrequired

      One of boolean, string, number.

    • environmentsobjectrequired
      Show 3 child fields
      • productionFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • previewFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • developmentFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
    • created_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • updated_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • created_atstringrequired
    • updated_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"
      }'
    Response 200
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules
    Full tokenNeeds Idempotency-KeyReturns201Created

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • flagstringrequired
    • environmentstringrequired

      One of production, preview, development.

    Body

    application/json
    • attributestringrequired

      At most 64 characters.

    • operatorstringrequired

      One of equals, not_equals, one_of, ends_with, starts_with, contains.

    • valuesarray of stringrequired

      At most 50 items.

    • serveboolean | string | numberrequired

    Response 201

    The flag.
    • keystringrequired
    • descriptionstringrequired
    • typestringrequired

      One of boolean, string, number.

    • environmentsobjectrequired
      Show 3 child fields
      • productionFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • previewFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • developmentFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
    • created_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • updated_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • created_atstringrequired
    • updated_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
      }'
    Response 201
    {
      "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.

    PATCH/v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • flagstringrequired
    • environmentstringrequired

      One of production, preview, development.

    • rulestringrequired

    Body

    application/json
    • serveboolean | string | numberrequired

    Response 200

    The flag.
    • keystringrequired
    • descriptionstringrequired
    • typestringrequired

      One of boolean, string, number.

    • environmentsobjectrequired
      Show 3 child fields
      • productionFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • previewFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
      • developmentFlagEnvironmentrequired
        Show 4 child fields
        • onbooleanrequired

          A boolean flag's switch; always true for the others.

        • rolloutintegerrequired

          From 1 to 100.

        • valuestring | number or nullrequired

          A string or number flag's value; null for a boolean.

        • rulesarray of FlagRulerequired
          Show 6 child fields
          • idstringrequired
          • attributestringrequired
          • operatorstringrequired

            One of equals, not_equals, one_of, ends_with, starts_with, contains.

          • valuesarray of stringrequired
          • serveboolean | string | numberrequired
          • labelstringrequired
    • created_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • updated_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • created_atstringrequired
    • updated_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
      }'
    Response 200
    {
      "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.

    DELETE/v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}
    Full tokenReturns204No Content

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • flagstringrequired
    • environmentstringrequired

      One 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"
    HTTP/1.1 204 No Content

    Was this page helpful?

    Updated