> For the complete documentation index, see [llms.txt](https://help.security.gallagher.com/knowledge-hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.security.gallagher.com/knowledge-hub/developer/rest-api/roles.md).
# Roles
The roles API gives you basic information about Command Centre's role items so that you can use them to form relationships between cardholders.
A role defines a relationship between two cardholders. One cardholder can perform a role for many others but can have it performed for them by only one other. For example, a person can be a supervisor for many people but has only one of his or her own.
When you use REST to look up or update a cardholder, you will work on the 'has a' relationships, not the 'is a' relationships. In other words, when a role represents a connection between a person and their supervisor, the API lets you change a cardholder's supervisor but not who the cardholder supervises.
API routes that allow creating, modifying, and deleting roles are in development.
### Use case: searching for a role by name and assigning a relationship
1. `GET /api`
2. Follow the link at `features.roles.roles.href` ↪ after adding search terms such as `name="supervisor"`.
3. Find the href of the role with which you want to link your two cardholders.
4. Find the href of the cardholder who will perform this role (the supervisor).
5. Find the href of the cardholder for whom he or she will perform this role (the supervised).
6. PATCH the second cardholder (the supervised) with the href of the first cardholder (the supervisor) and the href of the role.
### Licensing
Reading role items is enabled by the RESTCardholders licence.
## Search
> This returns the roles you are privileged to view.\
> \
> The result will contain no more than 100 or 1000 objects depending on your version; you\
> should follow the \`next\` link, if it is present, to collect more, or use the \`top\` parameter\
> to get more per page. Roles are small, so a limit of 1000 is sensible.\
> \
> When you have loaded all the roles there will no \`next\` link.\
> \
> \[Do not code this URL]\(forward-compatibility-hateoas) into your application. Take\
> it from the href in the \`features.roles.roles\` section of \`/api\`.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Roles","description":"\nThe roles API gives you basic information about Command Centre's role items so that you can use\nthem to form relationships between cardholders.\n\nA role defines a relationship between two cardholders. One cardholder can perform a role for\nmany others but can have it performed for them by only one other. For example, a person can be\na supervisor for many people but has only one of his or her own.\n\nWhen you use REST to look up or update a cardholder, you will work on the 'has a' relationships,\nnot the 'is a' relationships. In other words, when a role represents a connection between a\nperson and their supervisor, the API lets you change a cardholder's supervisor but not who the\ncardholder supervises.\n\nAPI routes that allow creating, modifying, and deleting roles are in development.\n\n## Use case: searching for a role by name and assigning a relationship\n\n1. `GET /api`\n1. Follow the link at `features.roles.roles.href` [↪](roles#get-api-roles) after adding\n search terms such as `name=\"supervisor\"`.\n1. Find the href of the role with which you want to link your two cardholders.\n1. Find the href of the cardholder who will perform this role (the supervisor).\n1. Find the href of the cardholder for whom he or she will perform this role (the supervised).\n1. [PATCH](cardholders#patch-api-cardholders-id-) the second cardholder (the supervised)\n with the href of the first cardholder (the supervisor) and the href of the role.\n\n## Licensing\n\nReading role items is enabled by the RESTCardholders licence.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"sort":{"name":"sort","in":"query","schema":{"type":"string","enum":["id","name","-id","-name"]},"required":false,"description":"Changes the sort field between database ID and name.\n\nIf you prefix `id` or `name` with a minus sign (ASCII 45), the sort order is reversed.\n\nThere are two very strong reasons to sort by ID:\n\n1. Sorting by name carries a risk of missing or duplicating objects if your result set spans\n multiple pages and another operator is editing the database while your REST client is\n enumerating them. This is known as \"page drift.\" Sorting by ID does not carry that risk.\n2. Following a `next` link is _dramatically_ quicker when sorting by ID.\n\nWe _strongly_ recommend sorting by ID. In case you were still in doubt, we will do that by\ndefault in a future version of Command Centre.\n\nThe server silently ignores anything except the options listed here.\n"},"top":{"name":"top","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Limits the results to no more than this many items per page.\n\nOlder versions of Command Centre returned 100 items per page in the absence of this parameter. That is acceptable for GUI\napplications that will only display the first page, but for integrations that intend to\nproceed through the entire database it causes a lot of chatter.\n\n8.70 and later versions will default to 1000 items per request. This is about where a graph\nof throughput versus page size begins to level out.\n"},"name":{"name":"name","in":"query","schema":{"type":"string"},"description":"Limits the returned items to those with a name that matches this string. Without surrounding\nquotes or a percent sign or underscore, it is a substring match; surround the parameter with\ndouble quotes `\"...\"` for an exact match. Without quotes, a percent sign `%` will match any\nsubstring and an underscore will match any single character.\n\nThe search is always case-insensitive. Results are undefined if you do a substring search for\nthe empty string (`name=`). You will receive no items if you search for those with no name\n(`name=\"\"`), as all items must have a name.\n\nSearch parameters are ANDed together.\n"},"division":{"name":"division","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Limits the returned items to those that are in these divisions.\n\nThat includes all the items in those divisions' child divisions, because Command Centre treats\nitems as though they are also in their division's parent, and its parent, and so on up to the\nroot division.\n\nSeparate the IDs of the divisions in you are interested with commas. Item IDs are short\nalphanumeric strings, not URLs.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n"},"directDivision":{"name":"directDivision","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Restricts items to those whose division is in this list.\n\nUnlike `division=`, it does not follow ancestry. That means it will limit the search to items\nthat are directly assigned to the divisions you list, whereas `division` (without the\n`direct`) will also include items that are assigned to their descendants.\n\nList the IDs of the divisions you are interested in separated by commas. Item IDs are short\nalphanumeric strings, not URLs.\n\nBecause this is the first query parameter we added that contains a capital letter, this will\nbe the first time you have had to think about case sensitivity. `directDivision` works,\n`directdivision` does not.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n\nAdded in 9.20.\n"},"description":{"name":"description","in":"query","required":false,"schema":{"type":"string"},"description":"Limits the returned items to those with a description that matches this string. By default it\nis a substring match; surround it with double quotes `\"...\"` for an exact match. A `_` will\nmatch any single character, and a `%` will match any substring. With or without quotes,\nhaving either of these wildcards in the string will anchor it at both ends as though you had\nsurrounded it with `\"`.\n\nThe search is always case-insensitive. Results are undefined if you search for the empty\nstring (`description=` or `description=\"\"`).\n\nSearch parameters are ANDed together.\n"},"pos":{"name":"pos","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use. You may see it in URLs you receive from the server, but you must never add it yourself."},"skip":{"name":"skip","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use. Do not add it to your queries."}},"schemas":{"Role":{"description":"`/api/roles` returns an array of these. Each element gives you enough about a role to\nidentify it and use it in a cardholder PATCH: its href, name, description, and (if you ask\nfor them using the `fields` parameter) notes.\n\nIn 9.10 or later you can send one of these in a POST to create a new role, or in a PATCH to\nmodify an existing one.\n","properties":{"name":{"type":"string"},"href":{"readOnly":true,"type":"string","format":"uri-reference","description":"This is the string to use when creating a relationship between cardholders using this\nrole.\n"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server. This field is missing from items that are held on\nthe machine that served the API request. Added in 8.40.\n\nThis is a read-only field. The server will ignore it if you send it.\n"},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this role. Required in a POST, optional in a PATCH.\n"},"enableCompetencyExpiryWarnings":{"type":"boolean","description":"Controls whether CC sends notifications to a person holding this role when their staff's\ncompetencies are about to expire.\n"},"enableCardExpiryWarnings":{"type":"boolean","description":"Controls whether CC sends notifications to a person holding this role when their staff's\ncards are about to expire.\n"}}}}},"paths":{"/api/roles":{"get":{"tags":["Roles"],"summary":"Search","description":"This returns the roles you are privileged to view.\n\nThe result will contain no more than 100 or 1000 objects depending on your version; you\nshould follow the `next` link, if it is present, to collect more, or use the `top` parameter\nto get more per page. Roles are small, so a limit of 1000 is sensible.\n\nWhen you have loaded all the roles there will no `next` link.\n\n[Do not code this URL](forward-compatibility-hateoas) into your application. Take\nit from the href in the `features.roles.roles` section of `/api`.\n","parameters":[{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/top"},{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/division"},{"$ref":"#/components/parameters/directDivision"},{"$ref":"#/components/parameters/description"},{"$ref":"#/components/parameters/pos"},{"$ref":"#/components/parameters/skip"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"description":"An array of roles, and a `next` link for more.\n","type":"object","properties":{"results":{"type":"array","description":"An array of roles.","items":{"$ref":"#/components/schemas/Role"}},"next":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}},"description":"The link to the next page of results. Absent if you have retrieved them all."}}}}}},"403":{"description":"The site does not have the RESTCardholders licence."}}}}}}
```
## Create \[coming]
> Creates a new role.\
> \
> \[Do not code this URL]\(forward-compatibility-hateoas) into your application. Take\
> it from the \`href\` field in the \`features.roles.roles.href\` field of \`GET /api\`.\
> \
> When successful it returns a location header containing the address of the new role.\
> \
> Note that you can only create one per POST.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Roles","description":"\nThe roles API gives you basic information about Command Centre's role items so that you can use\nthem to form relationships between cardholders.\n\nA role defines a relationship between two cardholders. One cardholder can perform a role for\nmany others but can have it performed for them by only one other. For example, a person can be\na supervisor for many people but has only one of his or her own.\n\nWhen you use REST to look up or update a cardholder, you will work on the 'has a' relationships,\nnot the 'is a' relationships. In other words, when a role represents a connection between a\nperson and their supervisor, the API lets you change a cardholder's supervisor but not who the\ncardholder supervises.\n\nAPI routes that allow creating, modifying, and deleting roles are in development.\n\n## Use case: searching for a role by name and assigning a relationship\n\n1. `GET /api`\n1. Follow the link at `features.roles.roles.href` [↪](roles#get-api-roles) after adding\n search terms such as `name=\"supervisor\"`.\n1. Find the href of the role with which you want to link your two cardholders.\n1. Find the href of the cardholder who will perform this role (the supervisor).\n1. Find the href of the cardholder for whom he or she will perform this role (the supervised).\n1. [PATCH](cardholders#patch-api-cardholders-id-) the second cardholder (the supervised)\n with the href of the first cardholder (the supervisor) and the href of the role.\n\n## Licensing\n\nReading role items is enabled by the RESTCardholders licence.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"schemas":{"Role":{"description":"`/api/roles` returns an array of these. Each element gives you enough about a role to\nidentify it and use it in a cardholder PATCH: its href, name, description, and (if you ask\nfor them using the `fields` parameter) notes.\n\nIn 9.10 or later you can send one of these in a POST to create a new role, or in a PATCH to\nmodify an existing one.\n","properties":{"name":{"type":"string"},"href":{"readOnly":true,"type":"string","format":"uri-reference","description":"This is the string to use when creating a relationship between cardholders using this\nrole.\n"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server. This field is missing from items that are held on\nthe machine that served the API request. Added in 8.40.\n\nThis is a read-only field. The server will ignore it if you send it.\n"},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this role. Required in a POST, optional in a PATCH.\n"},"enableCompetencyExpiryWarnings":{"type":"boolean","description":"Controls whether CC sends notifications to a person holding this role when their staff's\ncompetencies are about to expire.\n"},"enableCardExpiryWarnings":{"type":"boolean","description":"Controls whether CC sends notifications to a person holding this role when their staff's\ncards are about to expire.\n"}}}}},"paths":{"/api/roles":{"post":{"tags":["Roles"],"summary":"Create [coming]","description":"Creates a new role.\n\n[Do not code this URL](forward-compatibility-hateoas) into your application. Take\nit from the `href` field in the `features.roles.roles.href` field of `GET /api`.\n\nWhen successful it returns a location header containing the address of the new role.\n\nNote that you can only create one per POST.\n","requestBody":{"description":"This example shows the fields that you can set when creating a role.\nThere are no mandatory fields when PATCHing a role, but you must specify a division when\ncreating one.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role"}}},"required":true},"responses":{"201":{"description":"Success.","headers":{"location":{"schema":{"type":"string","format":"uri-reference"},"description":"The href of the new role."}}},"400":{"description":"The body of the POST did not describe a valid role.\n\nIf you see 'Invalid Role JSON object', the server could not parse the JSON in\nthe body of your POST. Remember to quote all strings, especially those that contain @\nsymbols.\n"},"403":{"description":"The operator does not have a privilege that allows creating roles.\n"}}}}}}
```
## Remove \[coming]
> This call removes a role item from Command Centre. Take its URL from a cardholder or a role\
> search rather than \[building it yourself]\(forward-compatibility-hateoas).
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Roles","description":"\nThe roles API gives you basic information about Command Centre's role items so that you can use\nthem to form relationships between cardholders.\n\nA role defines a relationship between two cardholders. One cardholder can perform a role for\nmany others but can have it performed for them by only one other. For example, a person can be\na supervisor for many people but has only one of his or her own.\n\nWhen you use REST to look up or update a cardholder, you will work on the 'has a' relationships,\nnot the 'is a' relationships. In other words, when a role represents a connection between a\nperson and their supervisor, the API lets you change a cardholder's supervisor but not who the\ncardholder supervises.\n\nAPI routes that allow creating, modifying, and deleting roles are in development.\n\n## Use case: searching for a role by name and assigning a relationship\n\n1. `GET /api`\n1. Follow the link at `features.roles.roles.href` [↪](roles#get-api-roles) after adding\n search terms such as `name=\"supervisor\"`.\n1. Find the href of the role with which you want to link your two cardholders.\n1. Find the href of the cardholder who will perform this role (the supervisor).\n1. Find the href of the cardholder for whom he or she will perform this role (the supervised).\n1. [PATCH](cardholders#patch-api-cardholders-id-) the second cardholder (the supervised)\n with the href of the first cardholder (the supervisor) and the href of the role.\n\n## Licensing\n\nReading role items is enabled by the RESTCardholders licence.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}}},"paths":{"/api/roles/{id}":{"delete":{"tags":["Roles"],"summary":"Remove [coming]","description":"This call removes a role item from Command Centre. Take its URL from a cardholder or a role\nsearch rather than [building it yourself](forward-compatibility-hateoas).\n","responses":{"200":{"description":"Success."},"204":{"description":"Success."},"400":{"description":"Deleting failed. This happens when the role is in use. The usual reason is that\ncardholders are still connected by the role you are attempting to remove.\n"},"403":{"description":"The operator has the permission to view the item but not delete it.\n"},"404":{"description":"That is not the URL of a role, or the operator is not privileged to view it.\n"}}}}}}
```
## Update \[coming]
> This is the call you use to update a role. Take its URL from a cardholder or a role search\
> rather than \[building it yourself]\(forward-compatibility-hateoas).\
> \
> The PATCH expects a document in the same format as the \[role detail]\(models#role).
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Roles","description":"\nThe roles API gives you basic information about Command Centre's role items so that you can use\nthem to form relationships between cardholders.\n\nA role defines a relationship between two cardholders. One cardholder can perform a role for\nmany others but can have it performed for them by only one other. For example, a person can be\na supervisor for many people but has only one of his or her own.\n\nWhen you use REST to look up or update a cardholder, you will work on the 'has a' relationships,\nnot the 'is a' relationships. In other words, when a role represents a connection between a\nperson and their supervisor, the API lets you change a cardholder's supervisor but not who the\ncardholder supervises.\n\nAPI routes that allow creating, modifying, and deleting roles are in development.\n\n## Use case: searching for a role by name and assigning a relationship\n\n1. `GET /api`\n1. Follow the link at `features.roles.roles.href` [↪](roles#get-api-roles) after adding\n search terms such as `name=\"supervisor\"`.\n1. Find the href of the role with which you want to link your two cardholders.\n1. Find the href of the cardholder who will perform this role (the supervisor).\n1. Find the href of the cardholder for whom he or she will perform this role (the supervised).\n1. [PATCH](cardholders#patch-api-cardholders-id-) the second cardholder (the supervised)\n with the href of the first cardholder (the supervisor) and the href of the role.\n\n## Licensing\n\nReading role items is enabled by the RESTCardholders licence.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"schemas":{"Role":{"description":"`/api/roles` returns an array of these. Each element gives you enough about a role to\nidentify it and use it in a cardholder PATCH: its href, name, description, and (if you ask\nfor them using the `fields` parameter) notes.\n\nIn 9.10 or later you can send one of these in a POST to create a new role, or in a PATCH to\nmodify an existing one.\n","properties":{"name":{"type":"string"},"href":{"readOnly":true,"type":"string","format":"uri-reference","description":"This is the string to use when creating a relationship between cardholders using this\nrole.\n"},"serverDisplayName":{"readOnly":true,"type":"string","description":"If you are running a multi-server installation and this item is homed on a remote server, this\nfield will contain the name of that server. This field is missing from items that are held on\nthe machine that served the API request. Added in 8.40.\n\nThis is a read-only field. The server will ignore it if you send it.\n"},"description":{"type":"string"},"division":{"type":"object","description":"The division containing this role. Required in a POST, optional in a PATCH.\n"},"enableCompetencyExpiryWarnings":{"type":"boolean","description":"Controls whether CC sends notifications to a person holding this role when their staff's\ncompetencies are about to expire.\n"},"enableCardExpiryWarnings":{"type":"boolean","description":"Controls whether CC sends notifications to a person holding this role when their staff's\ncards are about to expire.\n"}}}}},"paths":{"/api/roles/{id}":{"patch":{"tags":["Roles"],"summary":"Update [coming]","description":"This is the call you use to update a role. Take its URL from a cardholder or a role search\nrather than [building it yourself](forward-compatibility-hateoas).\n\nThe PATCH expects a document in the same format as the [role detail](models#role).\n","requestBody":{"description":"There are no mandatory fields when PATCHing a role, but you must specify a division when\ncreating one.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Role"}}},"required":true},"responses":{"200":{"description":"Success. Future versions will return feedback from the server about your PATCH.\n"},"204":{"description":"Success."},"400":{"description":"The body of the PATCH did not describe a valid role. Roles have many rules,\neasily enforced in a graphical interface but less so in an API. See the body of the\nresponse for help on what went wrong.\n"},"403":{"description":"The operator has a privilege that allows viewing the item but not modifying it, or you\ntried to set the division to one you cannot configure, or the server is missing the\nnecessary licence.\n\nYou need the 'Configure Site' privilege on the item you are changing, which means you need\non it on the item's current division. You also need it on the new division, if you are\nchanging that.\n"},"404":{"description":"That is not the URL of a role or your operator does not have the privilege to view\nit. This probably means you have built the URL yourself instead of taking it from the\nresults of a [GET](roles#get-api-roles).\n"},"409":{"description":"The item is locked for editing by another operator. The body of the response will\ntell you which operator is holding the lock.\n"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.security.gallagher.com/knowledge-hub/developer/rest-api/roles.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.