Table of contents

Settings API

The Settings API provides a way to read and write global settings

Listing Settings

GET /api/data/settings

You will receive a 200 response similar to the following:

[
    {
        "name": "General",
        "groups": [
            {
                "name": "General Settings",
                "settings": [
                    {
                        "id": "company_name",
                        "description": "Your company's name",
                        "value": "",
                        "type": "string",
                        "required_scope": ""
                    }
                ]
            }
        ]
    }
]
  • [].name - (string) - The name of the category
  • [].groups[].name - (string) - The name of the setting group
  • [].groups[].settings[].id - (string) - The ID of the setting
  • [].groups[].settings[].description - (string) - A human readable description of what the setting is/does
  • [].groups[].settings[].value - (string) - The current value of the setting
  • [].groups[].settings[].type - (string) - The type of value represented by the setting. Can be one of: string, number, bool
  • [].groups[].settings[].required_scope - (string) - The scope required to view the value of the setting

NOTE: the settings will be filtered by the scopes applied to the requesting user.

Listing a specific setting

GET /api/data/settings/{id}
  • {id} - (string) The ID of the setting to lookup

The response will be 200, with the setting object:

{
    "id": "company_name",
    "description": "Your company's name",
    "value": "",
    "type": "string",
    "required_scope": ""
}
  • id - (string) - The ID of the setting
  • description - (string) - A human readable description of what the setting is/does
  • value - (string) - The current value of the setting
  • type - (string) - The type of value represented by the setting. Can be one of: string, number, bool
  • required_scope - (string) - The scope required to view the value of the setting

NOTE: A 403 will be returned if the user making the request does not have the required_scope to read the setting.

Updating a setting

Updating a setting

PATCH /api/data/settings/{id}
  • {id} - (string) The ID of the setting to lookup

Request body:

{
    "value": "some new value"
}

The response will be 200, with the setting object:

{
    "id": "company_name",
    "description": "Your company's name",
    "value": "some new value",
    "type": "string",
    "required_scope": ""
}
  • id - (string) - The ID of the setting
  • description - (string) - A human readable description of what the setting is/does
  • value - (string) - The current value of the setting
  • type - (string) - The type of value represented by the setting. Can be one of: string, number, bool
  • required_scope - (string) - The scope required to view the value of the setting

NOTE: A 403 will be returned if the user making the request does not have the required_scope to read the setting

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.