Project: Flagsmith (Observability and Analysis / Feature Flagging)
File: rest.md

description: Manage your Feature Flags and Remote Config in your REST APIs. sidebar_label: REST sidebar_position: 2 :::tip Some API actions require object UUIDs/IDs to be referenced. You can enable the from your account settings page which will help you access these variables. ::: :::info Our Admin API has a that you need to be aware of. ::: Our API is split in two : The `Public SDK API` that serves Flags to your client applications. This API does not require secret keys and is open by design. The `Private Admin API` that allows you to do things like programatically create and toggle flags. Interacting with this API requires a . You can view the API via Swagger at or get OpenAPI as or . We have a that you can use to play around with the API and get a feel for how it works. ](https://app.getpostman.com/run-collection/14712118-a638325a-f1f4-4570-8b4d-fd2841218dfa?action=collection%2Ffork&collection-url=entityId%3D14712118-a638325a-f1f4-4570-8b4d-fd2841218dfa%26entityType%3Dcollection%26workspaceId%3D452554eb-f581-4754-b5b8-0deabdce9f4b#?env%5BFlagsmith%20Environment%5D=W3sia2V5IjoiRmxhZ3NtaXRoIEVudmlyb25tZW50IEtleSIsInZhbHVlIjoiOEt6RVRkRGVNWTd4a3FrU2tZM0dzZyIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYmFzZVVybCIsInZhbHVlIjoiaHR0cHM6Ly9hcGkuZmxhZ3NtaXRoLmNvbS9hcGkvdjEvIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJJZGVudGl0eSIsInZhbHVlIjoicG9zdG1hbl91c2VyXzEyMyIsImVuYWJsZWQiOnRydWV9XQ==) You can also access the API directly with tools like or , or with clients for languages that we do not currently have SDKs for. Publicly accessible API calls need to have an environment key supplied with each request. This is provided as an HTTP header, with the name `X-Environment-Key` and the value of the Environment Key that you can find within the Flagsmith administrative area. For SaaS customers, the URL to hit for this API is . You can also do things like create new flags, environments, toggle flags or indeed anything that is possible from the administrative front end via the API. To authenticate, you can use the API Token associated with your Organisation. This can be found in the `Organisation` page from the top navigation panel. You need to create a token and then provide it as an HTTP header: ```bash Authorization: Api-Key <API TOKEN FROM ORGANISATION PAGE> ``` For example, to create a new Environment: ```bash curl 'https://api.flagsmith.com/api/v1/environments/' \ -H 'content-type: application/json' \ -H 'authorization: Api-Key <API TOKEN FROM ORGANISATION PAGE>' \ --data-binary '{"name":"New Environment","project":"<Project ID>"}' ``` You can find a complete list of endpoints via the Swagger REST API at . For SaaS customers, the URL to hit for this API is `https://api.flagsmith.com/`. These are the two main endpoints that you need to consume the SDK aspect of the API. ```bash curl 'https://edge.api.flagsmith.com/api/v1/flags/' -H 'X-Environment-Key: <Your Env Key>' ``` This command will perform the entire SDK Identity workflow in a single call: Lazily create an Identity Setting Traits for the Identity Receiving the Flags for that Identity ```bash curl --request POST 'https://edge.api.flagsmith.com/api/v1/identities/' \ --header 'X-Environment-Key: <Your Env Key>' \ --header 'Content-Type: application/json' \ --data-raw '{ "identifier":"identifier_5", "traits": [ { "traitkey": "mytrait_key", "trait_value": 123.5 }, { "traitkey": "myother_key", "trait_value": true } ] }' ``` You can enable the JSON view in your Account Settings

This will then give you access to relevant object meta data in the Flag area of the dashboard. Below are some examples for achieving certain actions with the REST API, using python. ```python import os from requests import Session APIURL = os.environ.get("APIURL", "https://api.flagsmith.com/api/v1") # update this if self-hosting PROJECTID = os.environ["PROJECTID"] # obtain this from the URL on your dashboard TOKEN = os.environ["API_TOKEN"] # obtain this from the account page in your dashboard FEATURENAME = os.environ["FEATURENAME"] # name of the feature to create session = Session() session.headers.update({"Authorization": f"Token {TOKEN}"}) createfeatureurl = f"{APIURL}/projects/{PROJECTID}/features/" data = {"name": FEATURE_NAME} response = session.post(createfeatureurl, json=data) ``` ```python import json import os import requests TOKEN = os.environ.get("API_TOKEN") # obtained from Account section in dashboard ENVKEY = os.environ.get("ENVKEY") # obtained from environment settings in dashboard BASE_URL = "https://api.flagsmith.com/api/v1" # update this if self hosting FEATURESTATESURL = f"{BASEURL}/environments/{ENVKEY}/featurestates" FEATURENAME = os.environ.get("FEATURENAME") session = requests.Session() session.headers.update( {"Authorization": f"Token {TOKEN}", "Content-Type": "application/json"} ) getfeaturestates_response = session.get( f"{FEATURESTATESURL}/?featurename={FEATURENAME}" ) featurestateid = getfeaturestates_response.json()["id"] data = {"enabled": True, "featurestatevalue": "new value"} # `featurestatevalue` can be str, int or bool updatefeaturestate_response = session.patch( f"{FEATURESTATESURL}/{featurestateid}/", data=json.dumps(data) ) ``` ```python import os from requests import Session APIURL = os.environ.get("APIURL", "https://api.flagsmith.com/api/v1") # update this if self-hosting SEGMENTNAME = os.environ["SEGMENTNAME"] # define the name of the segment here PROJECTID = os.environ["PROJECTID"] # obtain this from the URL on your dashboard TOKEN = os.environ["API_TOKEN"] # obtain this from the account page in your dashboard FEATUREID = os.environ.get("FEATUREID") # obtain this from the URL on your dashboard when viewing a feature ISFEATURESPECIFIC = os.environ.get("ISFEATURESPECIFIC", default=False) == "True" # set this to True to create a feature specific segment ENVIRONMENTID = os.environ["ENVIRONMENTID"] # must (currently) be obtained by inspecting the request to /api/v1/environments in the network console ENABLEFORSEGMENT = os.environ.get("ENABLEFORSEGMENT", default=False) == "True" VALUEFORSEGMENT = os.environ.get("VALUEFORSEGMENT") SEGMENT_DEFINITION = { "name": SEGMENT_NAME, "feature": FEATUREID if ISFEATURE_SPECIFIC else None, "project": PROJECT_ID, "rules": [ { "type": "ALL", "rules": [ # add extra rules here to build up 'AND' logic { "type": "ANY", "conditions": [ # add extra conditions here to build up 'OR' logic { "property": "my_trait", # specify a trait key that you want to match on, e.g. organisationId "operator": "EQUAL", # specify the operator you want to use (one of EQUAL, NOTEQUAL, GREATERTHAN, LESSTHAN, GREATERTHANINCLUSIVE, LESSTHANINCLUSIVE, CONTAINS, NOTCONTAINS, REGEX, PERCENTAGESPLIT, ISSET, ISNOTSET) "value": "my-value" # the value to match against, e.g. 103 } ] } ] } ] } session = Session() session.headers.update({"Authorization": f"Token {TOKEN}"}) createsegmenturl = f"{APIURL}/projects/{PROJECTID}/segments/" createsegmentresponse = session.post(createsegmenturl, json=SEGMENT_DEFINITION) assert createsegmentresponse.status_code == 201 segmentid = createsegment_response.json()["id"] if not any(key in os.environ for key in ("ENABLEFORSEGMENT", "VALUEFORSEGMENT")): print("Segment created! Not creating an override as no state / value defined.") exit(0) createfeaturesegmenturl = f"{APIURL}/features/feature-segments/" featuresegmentdata = { "feature": FEATURE_ID, "segment": segment_id, "environment": ENVIRONMENT_ID } createfeaturesegmentresponse = session.post(createfeaturesegmenturl, json=featuresegmentdata) assert createfeaturesegmentresponse.statuscode == 201 featuresegmentid =

createsegmentoverrideurl = f"{APIURL}/features/featurestates/" featurestatedata = { "feature": FEATURE_ID, "featuresegment": featuresegment_id, "environment": ENVIRONMENT_ID, "enabled": ENABLEFORSEGMENT, "featurestatevalue": { "type": "unicode", "stringvalue": VALUEFOR_SEGMENT } } createfeaturestateresponse = session.post(createsegmentoverrideurl, json=featurestatedata) assert createfeaturestateresponse.statuscode == 201 ``` ```python import os from requests import Session APIURL = os.environ.get("APIURL", "https://api.flagsmith.com/api/v1") # update this if self-hosting PROJECTID = os.environ["PROJECTID"] # obtain this from the URL on your dashboard TOKEN = os.environ["API_TOKEN"] # obtain this from the account page in your dashboard SEGMENTID = os.environ.get("SEGMENTID") # obtain this from the URL on your dashboard when viewing a segment SEGMENTRULESDEFINITION = { "rules": [ { "type": "ALL", "rules": [ { "type": "ANY", "conditions": [ # add as many conditions here to build up a segment { "property": "my_trait", # specify a trait key that you want to match on, e.g. organisationId "operator": "EQUAL", # specify the operator you want to use (one of EQUAL, NOTEQUAL, GREATERTHAN, LESSTHAN, GREATERTHANINCLUSIVE, LESSTHANINCLUSIVE, CONTAINS, NOTCONTAINS, REGEX, PERCENTAGESPLIT, ISSET, ISNOTSET) "value": "my-value" # the value to match against, e.g. 103 } ] } ] } ] } session = Session() session.headers.update({"Authorization": f"Token {TOKEN}"}) updatesegmenturl = f"{APIURL}/projects/{PROJECTID}/segments/{SEGMENT_ID}/" session.patch(updatesegmenturl, json=SEGMENTRULESDEFINITION) ``` Sometimes it can be useful to iterate over your Identities to check things like Segment overrides. ```python import os import requests TOKEN = os.environ.get("API_TOKEN") # obtained from Account section in dashboard ENVKEY = os.environ.get("ENVKEY") # obtained from Environment settings in dashboard BASE_URL = "https://api.flagsmith.com/api/v1" # update this if self hosting IDENTITIESPAGEURL = f"{BASEURL}/environments/{ENVKEY}/edge-identities/?page_size=20" session = requests.Session() session.headers.update( {"Authorization": f"Token {TOKEN}", "Content-Type": "application/json"} ) pageofidentities = session.get(f"{IDENTITIESPAGEURL}") print(pageofidentities.json()) for identity in pageofidentities.json()['results']: print(str(identity)) IDENTITYUUID = identity['identityuuid'] IDENTITYURL = f"{BASEURL}/environments/{ENVKEY}/edge-identities/{IDENTITYUUID}/edge-featurestates/all/" identitydata = session.get(f"{IDENTITYURL}") print(identity_data.json()) ``` ```python import os import requests TOKEN = os.environ.get("API_TOKEN") # obtained from Account section in dashboard ENVKEY = os.environ.get("ENVKEY") # obtained from Environment settings in dashboard IDENTITYUUDI = os.environ["IDENTITYUUDI"] # must (currently) be obtained by inspecting the request to /api/v1/environments/{ENVKEY}/edge-identities/{IDENTITYUUDI} in the network console BASE_URL = "https://edge.api.flagsmith.com/api/v1" # update this if self hosting session = requests.Session() session.headers.update( {"Authorization": f"Token {TOKEN}", "Content-Type": "application/json"} ) deleteedgeidentityurl = f"{BASEURL}/environments/{ENVKEY}/edge-identities/{IDENTITYUUDI}/" deleteedgeidentityresponse = session.delete(deleteedgeidentityurl) assert deleteedgeidentityresponse.statuscode == 204 ``` ```python import os import requests TOKEN = os.environ.get("API_TOKEN") # obtained from Account section in dashboard ENVKEY = os.environ.get("ENVKEY") # obtained from Environment settings in dashboard IDENTITYID = os.environ["IDENTITYID"] # obtain this from the URL on your dashboard when viewing an identity BASE_URL = "https://api.flagsmith.com/api/v1" # update this if self hosting session = requests.Session() session.headers.update( {"Authorization": f"Token {TOKEN}", "Content-Type": "application/json"} ) deleteidentityurl = f"{BASEURL}/environments/{ENVKEY}/identities/{IDENTITY_ID}/" deleteidentityresponse = session.delete(deleteidentityurl) assert deleteidentityresponse.status_code == 204 ``` You can achieve this with a `POST` to the `identities` endpoint: ```bash curl -X "POST" "https://edge.api.flagsmith.com/api/v1/identities/?identifier=<identity_id>" \ -H 'X-Environment-Key: <Your Environment Key>' \ -H 'Content-Type: application/json; charset=utf-8' \ -d $'{ "traits": "traits": [ { "traitkey": "thiskey", "traitvalue": "thisvalue" }, { "traitkey": "thiskey2", "traitvalue": "thisvalue2" } ], "identifier": "<identity_id>" }' ```