Feature Flags

Feature flags are the core entity in GroundControl

Data model

  • Name
    id
    Type
    string
    Description
    The unique identifier of the flag
  • Name
    projectId
    Type
    string
    Description
    The unique identifier of the project
  • Name
    name
    Type
    string
    Description
    The name of the flag
  • Name
    description
    Type
    string
    Description
    The description of the flag
  • Name
    status
    Type
    `enabled` | `disabled` | `conditional`
    Description
    The status of the flag
  • Name
    percentageActors
    Type
    integer
    Description
    The percentage of actors this flag is enabled for
  • Name
    percentageCalls
    Type
    integer
    Description
    The percentage of calls this flag is enabled for
  • Name
    createdAt
    Type
    string
    Description
    The date the flag was created
  • Name
    updatedAt
    Type
    string
    Description
    The date the flag was last updated
  • Name
    latestCheckedAt
    Type
    string
    Description
    The date the flag was last checked
  • Name
    statusChangedAt
    Type
    string
    Description
    The date the flag's status was last changed

Endpoints

GET/projects/{projectId}/flags

List the flags in a project

List flags of a project

Path parameters

  • Name
    projectId
    Type
    string
    Description
    Required The project id

Query parameters

  • Name
    before
    Type
    string
    Description
    Show results before this cursor
  • Name
    after
    Type
    string
    Description
    Show results after this cursor
  • Name
    name
    Type
    string
    Description
    Search by name
  • Name
    q
    Type
    string
    Description
    Search by name and description

Request

GET
/projects/{projectId}/flags
const options = {method: 'GET', headers: {Authorization: 'Bearer YOUR_API_KEY'}};

fetch('https://api.groundcontrol.sh/projects/P091PL4M90ZWQUZ0/flags', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Response

{
  "data": [
    {
      "id": "F091PL4M90ZWQUZ0",
      "projectId": "P091PL4M90ZWQUZ0",
      "name": "my-flag",
      "description": "This is a flag that does something",
      "status": "conditional",
      "percentageActors": 50,
      "percentageCalls": 50,
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z",
      "latestCheckedAt": "2023-01-01T00:00:00.000Z",
      "statusChangedAt": "2023-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "before": "YWJjZDEyMzQ1Njc4OTB4eXo=",
    "after": "MTIzNGFiY2RlZmdoaWprbG1ubw=="
  }
}
GET/projects/{projectId}/flags/{flagName}/check

Check the status of a flag

Check the status of a feature flag

Path parameters

  • Name
    projectId
    Type
    string
    Description
    Required The project id
  • Name
    flagName
    Type
    string
    Description
    Required The flag name

Query parameters

  • Name
    actorIds
    Type
    array of strings
    Description
    The actor ids
  • Name
    cache
    Type
    number
    Description
    Specifies the time in seconds to use in the cache-control header

Request

GET
/projects/{projectId}/flags/{flagName}/check
const options = {method: 'GET', headers: {Authorization: 'Bearer YOUR_API_KEY'}};

fetch('https://api.groundcontrol.sh/projects/P091PL4M90ZWQUZ0/flags/my-flag/check', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Response

{
  "enabled": false
}
POST/projects/{projectId}/flags/{flagName}

Create a new flag

Create a new feature flag

Path parameters

  • Name
    projectId
    Type
    string
    Description
    Required The project id
  • Name
    flagName
    Type
    string
    Description
    Required The flag name

Request body

  • Name
    description
    Type
    string
    Description
    Feature flag description

Request

POST
/projects/{projectId}/flags/{flagName}
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
  body: '{"description":"example"}'
};

fetch('https://api.groundcontrol.sh/projects/P091PL4M90ZWQUZ0/flags/my-flag', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Response

{
  "id": "F091PL4M90ZWQUZ0",
  "projectId": "P091PL4M90ZWQUZ0",
  "name": "my-flag",
  "description": "This is a flag that does something",
  "status": "conditional",
  "percentageActors": 50,
  "percentageCalls": 50,
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z",
  "latestCheckedAt": "2023-01-01T00:00:00.000Z",
  "statusChangedAt": "2023-01-01T00:00:00.000Z"
}
GET/projects/{projectId}/flags/{flagName}

Retrieve a flag

Get a feature flag

Path parameters

  • Name
    projectId
    Type
    string
    Description
    Required The project id
  • Name
    flagName
    Type
    string
    Description
    Required The flag name

Request

GET
/projects/{projectId}/flags/{flagName}
const options = {method: 'GET', headers: {Authorization: 'Bearer YOUR_API_KEY'}};

fetch('https://api.groundcontrol.sh/projects/P091PL4M90ZWQUZ0/flags/my-flag', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Response

{
  "id": "F091PL4M90ZWQUZ0",
  "projectId": "P091PL4M90ZWQUZ0",
  "name": "my-flag",
  "description": "This is a flag that does something",
  "status": "conditional",
  "percentageActors": 50,
  "percentageCalls": 50,
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z",
  "latestCheckedAt": "2023-01-01T00:00:00.000Z",
  "statusChangedAt": "2023-01-01T00:00:00.000Z"
}
PATCH/projects/{projectId}/flags/{flagName}

Update a flag

Update a feature flag

Path parameters

  • Name
    projectId
    Type
    string
    Description
    Required The project id
  • Name
    flagName
    Type
    string
    Description
    Required The flag name

Request body

  • Name
    description
    Type
    string
    Description
    Feature flag description
  • Name
    status
    Type
    `enabled` | `disabled` | `conditional`
    Description
    Feature flag status
  • Name
    percentageActors
    Type
    `0` | `1` | `2` | `5` | `10` | `25` | `50` | `75` | `100`
    Description
    Percentage of actors
  • Name
    percentageCalls
    Type
    `0` | `1` | `2` | `5` | `10` | `25` | `50` | `75` | `100`
    Description
    Percentage of calls
  • Name
    addActors
    Type
    array of strings
    Description
    Actors to add
  • Name
    removeActors
    Type
    array of strings
    Description
    Actors to remove
  • Name
    addSegments
    Type
    array of strings
    Description
    Segments to add
  • Name
    removeSegments
    Type
    array of strings
    Description
    Segments to remove

Request

PATCH
/projects/{projectId}/flags/{flagName}
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
  body: '{"description":"example","status":"example","percentageActors":"example","percentageCalls":"example","addActors":["example"],"removeActors":["example"],"addSegments":["example"],"removeSegments":["example"]}'
};

fetch('https://api.groundcontrol.sh/projects/P091PL4M90ZWQUZ0/flags/my-flag', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Response

{
  "id": "F091PL4M90ZWQUZ0",
  "projectId": "P091PL4M90ZWQUZ0",
  "name": "my-flag",
  "description": "This is a flag that does something",
  "status": "conditional",
  "percentageActors": 50,
  "percentageCalls": 50,
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z",
  "latestCheckedAt": "2023-01-01T00:00:00.000Z",
  "statusChangedAt": "2023-01-01T00:00:00.000Z"
}
DELETE/projects/{projectId}/flags/{flagName}

Delete a flag

Delete a feature flag

Path parameters

  • Name
    projectId
    Type
    string
    Description
    Required The project id
  • Name
    flagName
    Type
    string
    Description
    Required The flag name

Request

DELETE
/projects/{projectId}/flags/{flagName}
const options = {method: 'DELETE', headers: {Authorization: 'Bearer YOUR_API_KEY'}};

fetch('https://api.groundcontrol.sh/projects/P091PL4M90ZWQUZ0/flags/my-flag', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
GET/projects/{projectId}/actors/{actorId}/flags

List flags for an actor

List flags that are enabled for an actor

Path parameters

  • Name
    projectId
    Type
    string
    Description
    Required The project id
  • Name
    actorId
    Type
    string
    Description
    Required The actor id

Query parameters

  • Name
    before
    Type
    string
    Description
    Show results before this cursor
  • Name
    after
    Type
    string
    Description
    Show results after this cursor

Request

GET
/projects/{projectId}/actors/{actorId}/flags
const options = {method: 'GET', headers: {Authorization: 'Bearer YOUR_API_KEY'}};

fetch('https://api.groundcontrol.sh/projects/P091PL4M90ZWQUZ0/actors/user:1234/flags', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Response

{
  "data": [
    {
      "id": "F091PL4M90ZWQUZ0",
      "projectId": "P091PL4M90ZWQUZ0",
      "name": "my-flag",
      "description": "This is a flag that does something",
      "status": "conditional",
      "percentageActors": 50,
      "percentageCalls": 50,
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z",
      "latestCheckedAt": "2023-01-01T00:00:00.000Z",
      "statusChangedAt": "2023-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "before": "YWJjZDEyMzQ1Njc4OTB4eXo=",
    "after": "MTIzNGFiY2RlZmdoaWprbG1ubw=="
  }
}
GET/projects/{projectId}/segments/{segmentId}/flags

List flags for a segment

List flags that are enabled for a segment

Path parameters

  • Name
    projectId
    Type
    string
    Description
    Required The project id
  • Name
    segmentId
    Type
    string
    Description
    Required The segment id

Query parameters

  • Name
    before
    Type
    string
    Description
    Show results before this cursor
  • Name
    after
    Type
    string
    Description
    Show results after this cursor

Request

GET
/projects/{projectId}/segments/{segmentId}/flags
const options = {method: 'GET', headers: {Authorization: 'Bearer YOUR_API_KEY'}};

fetch('https://api.groundcontrol.sh/projects/P091PL4M90ZWQUZ0/segments/S091PL4M90ZWQUZ0/flags', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Response

{
  "data": [
    {
      "id": "F091PL4M90ZWQUZ0",
      "projectId": "P091PL4M90ZWQUZ0",
      "name": "my-flag",
      "description": "This is a flag that does something",
      "status": "conditional",
      "percentageActors": 50,
      "percentageCalls": 50,
      "createdAt": "2023-01-01T00:00:00.000Z",
      "updatedAt": "2023-01-01T00:00:00.000Z",
      "latestCheckedAt": "2023-01-01T00:00:00.000Z",
      "statusChangedAt": "2023-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "before": "YWJjZDEyMzQ1Njc4OTB4eXo=",
    "after": "MTIzNGFiY2RlZmdoaWprbG1ubw=="
  }
}