> 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/items.md).
# Items
These methods let you find items for your search filters and events, and monitor their states. They return all items, including those that this API does not yet support in depth, and items added by customisations. However because they do not have deep knowledge of item types they can only give you the most basic fields.
### Searching for items
Use the search methods when you are building a filter for an event search or a status subscription and need the ID of an item or an item type, or when you are creating an event and need an href to use as the event source.
To find an item, pass a substring of its name to the link at `features.items.items.href` in the results of a call to `/api`. If you are sure of its name, place the name inside `"` quotes, and it will use a full string match. Both types of search are case-insensitive.
To limit the search to items of a particular type, first get the ID of the type you are after using the link at `features.items.itemTypes.href` in the results of `GET /api`. Add that ID as the `type` parameter to the call above. You can specify multiple item types if, for example, you are interested in all the different kinds of doors.
For example, if you were after a list of divisions, following the instructions above on the current versions of Command Centre would produce the URL `/api/items?type=15`.
### Status subscriptions
The item-specific APIs monitor only one item at a time, and are therefore not suitable for watching large collections. If you have CC version 8.30 or later, you should use the status subscription methods instead. We have tested subscriptions of 1000 items without noticing undue strain on the server. While the calls do not impose an upper bound on that we suggest keeping a watchful eye on the performance of the overall system if you go much higher.
The basic process for monitoring item states is:
1. Get all the IDs of the items you wish to monitor. You can do that using this API's own search with a `name`, `division`, or `type` parameter. If you're searching by division you'll need a division ID which (slightly recursively) is best found by using the same search function filtering for just divisions. If you're searching by type you'll need a type ID.
2. POST to create a subscription. Your program should get the URL from `items.updates.href` in the results of `GET /api`.
3. Take the current state of your items from the results of that call. If that's all you need, terrific. But if you want to monitor their state, continue.
4. GET the `next.href` link that came in the results. The call will block until one of your monitored items changes state. When it returns, the results will be in the same format as the result of the POST, including the `next` link.
5. Goto 4.
### Licensing
Every REST licence enables the items controller: RESTEvents, RESTCreateEvents, RESTCardholders, RESTStatus, and RESTOverrides.
## Search items
> This returns a batch of items matching the applied filters. By default, each page will\
> contain up to 1000 items although this can be changed by setting the \`top\`\
> parameter in the request URL.\
> \
> You will only receive items for which the REST operator has the necessary privilege. To\
> view PDFs, for example, the operator must have the 'View Personal Data Definitions'\
> privilege.\
> \
> If more items are available, the response will contain a \`next\` link. Following\
> that will return the next batch of items.\
> \
> Items will be in ID order unless you change it with \`sort\`.\
> \
> Do not code this URL into your application. Take it from \`items.items.href\` in the results\
> of \`GET /api\`.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Items","description":"\nThese methods let you find items for your search filters and events, and monitor their states.\nThey return all items, including those that this API does not yet support in depth, and items\nadded by customisations. However because they do not have deep knowledge of item types they can\nonly give you the most basic fields.\n\n## Searching for items\n\nUse the search methods when you are building a filter for an [event\nsearch](events#get-api-events) or a [status\nsubscription](events#post-api-items-updates) and need the ID of an item or an item type, or\nwhen you are [creating an event](events#post-api-events) and need an href to use as the\nevent source.\n\nTo find an item, pass a substring of its name to the link at `features.items.items.href` in the\nresults of a call to `/api`. If you are sure of its name, place the name inside `\"` quotes, and\nit will use a full string match. Both types of search are case-insensitive.\n\nTo limit the search to items of a particular type, first get the ID of the type you\nare after using the link at `features.items.itemTypes.href` in the results of `GET /api`.\nAdd that ID as the `type` parameter to the call above. You can specify multiple item\ntypes if, for example, you are interested in all the different kinds of doors.\n\nFor example, if you were after a list of divisions, following the instructions above on the\ncurrent versions of Command Centre would produce the URL `/api/items?type=15`.\n\n## Status subscriptions\n\nThe item-specific APIs monitor only one item at a time, and are therefore not\nsuitable for watching large collections. If you have CC version 8.30 or later, you should use\nthe status subscription methods instead. We have tested subscriptions of 1000 items without\nnoticing undue strain on the server. While the calls do not impose an upper bound on that we\nsuggest keeping a watchful eye on the performance of the overall system if you go much higher.\n\nThe basic process for monitoring item states is:\n\n 1. Get all the IDs of the items you wish to monitor. You can do that using this API's own\n [search](items#get-api-items) with a `name`, `division`, or `type` parameter. If you're\n searching by division you'll need a division ID which (slightly recursively) is best found by\n using the same search function filtering for just divisions. If you're searching by type\n you'll need a [type ID](items#get-api-items-types).\n\n 1. [POST](items#post-api-items-updates) to create a subscription. Your program should\n get the URL from `items.updates.href` in the results of `GET /api`.\n\n 1. Take the current state of your items from the results of that call. If that's all you\n need, terrific. But if you want to monitor their state, continue.\n\n 1. [GET](items#get-api-items-updates) the\n `next.href` link that came in the results. The call will block until one of your\n monitored items changes state. When it returns, the results will be in the same format as the\n result of the POST, including the `next` link.\n\n 1. Goto 4.\n\n## Licensing\n\nEvery REST licence enables the items controller: RESTEvents, RESTCreateEvents, RESTCardholders,\nRESTStatus, and RESTOverrides.\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":{"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"},"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"}},"schemas":{"ItemSearch":{"title":"Item search","type":"object","description":"Calls to `/api/items` return this object.","properties":{"results":{"description":"A list of item objects, each containing the alphanumeric ID of the item, its name, and its type.","type":"array","items":{"$ref":"#/components/schemas/ItemSummary"}},"next":{"type":"object","description":"An href to the next page of results. Missing if there are no more results.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"ItemSummary":{"title":"Item summary","type":"object","description":"`/api/items` returns an array of these. Because it can contain an item of any type, it only\ncontains some fields that are common to all item types.\n\n`description` and `shortName` arrived in 9.60.\n","properties":{"id":{"type":"string","description":"Use this ID in the `source` filter when requesting events to limit events to those with\nthat source. Card events such as 'access granted', for example, have a door as their\nsource.\n"},"name":{"type":"string"},"shortName":{"type":"string","maxLength":16,"description":"Short names are not displayed by default. You must ask for them using the\n'fields' parameter:\n\n`?fields=shortname,...`.\n"},"description":{"type":"string","description":"In 9.60 and later."},"type":{"type":"object","description":"The `type` object contains the ID and name of the item's type.","properties":{"id":{"type":"string","description":"Use this ID in the `type` filter when requesting items if you wish to restrict the\nresults to items of a certain type.\n"},"name":{"type":"string","description":"A human-readable name of the item's type, suitable for display.\n\nThis string is translated using the installation's language pack, and Gallagher\nreserves the right to change item type names in new versions, so you should not do\nanything with this string except show it to a person.\n"},"canonicalTypeName":{"description":"An unchanging, alphanumeric, short, and hopefully descriptive identifier for the item type.\n\nThe set of possible values will grow as time passes but the strings themselves, unless\nhighlighted as temporary, will never change. You can count on an access zone always having\na canonical type name of 'accesszone', for example.\n\nAdded in 9.00.\n","type":"string"}}},"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"},"notes":{"type":"string","description":"Because of their potential size, notes are only available by request. Use the 'fields'\nparameter:\n\n`?fields=defaults,notes,...`\n"},"href":{"type":"string","description":"Reserved for internal use. Its value changed in version 9.10."}}}}},"paths":{"/api/items":{"get":{"tags":["Items"],"summary":"Search items","description":"This returns a batch of items matching the applied filters. By default, each page will\ncontain up to 1000 items although this can be changed by setting the `top`\nparameter in the request URL.\n\nYou will only receive items for which the REST operator has the necessary privilege. To\nview PDFs, for example, the operator must have the 'View Personal Data Definitions'\nprivilege.\n\nIf more items are available, the response will contain a `next` link. Following\nthat will return the next batch of items.\n\nItems will be in ID order unless you change it with `sort`.\n\nDo not code this URL into your application. Take it from `items.items.href` in the results\nof `GET /api`.\n","parameters":[{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/division"},{"$ref":"#/components/parameters/directDivision"},{"name":"type","in":"query","description":"Only returns items that are of a type with this ID. In versions up to 8.30 you could only\nspecify one, but in 8.40 and later this can be a comma-separated list.\n\nServers older than 9.70 will ignore invalid IDs. If they are all invalid it will act as\nthough the filter was absent and return all items.\n\nIn 9.70 and later it will warn about invalid IDs and fail the whole request if none is\nvalid.\n","schema":{"type":"string"}},{"name":"top","in":"query","description":"Sets the maximum number of items to return per page.","schema":{"minimum":1,"type":"integer","default":1000}},{"$ref":"#/components/parameters/sort"},{"name":"fields","in":"query","description":"Return these fields in the search results. The values you can list are the same as the field\nnames in the details page. Using it you can return everything on the summary page that you\nwould find on the details page. Separate values with commas.\n\nUse the special value `defaults` to return the fields you would have received had you not given\nthe parameter at all. Obviously only do that if you have more to add.\n\nThe string must not contain any spaces. Just alphanumerics, underscores, commas, and dots.\n\n`description` and `shortName` arrived in 9.60.\n\nTreat the string matches as case-sensitive.\n","schema":{"type":"string","enum":["href","id","name","type","division","serverDisplayName","notes","description","shortName"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemSearch"}}}},"403":{"description":"The site does not have a REST licence."}}}}}}
```
## Get details of an item
> This returns some basic fields for one item. It returns the same information as the \[item\
> search]\(items#get-api-items) plus the item's division.\
> \
> Added in 8.40.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Items","description":"\nThese methods let you find items for your search filters and events, and monitor their states.\nThey return all items, including those that this API does not yet support in depth, and items\nadded by customisations. However because they do not have deep knowledge of item types they can\nonly give you the most basic fields.\n\n## Searching for items\n\nUse the search methods when you are building a filter for an [event\nsearch](events#get-api-events) or a [status\nsubscription](events#post-api-items-updates) and need the ID of an item or an item type, or\nwhen you are [creating an event](events#post-api-events) and need an href to use as the\nevent source.\n\nTo find an item, pass a substring of its name to the link at `features.items.items.href` in the\nresults of a call to `/api`. If you are sure of its name, place the name inside `\"` quotes, and\nit will use a full string match. Both types of search are case-insensitive.\n\nTo limit the search to items of a particular type, first get the ID of the type you\nare after using the link at `features.items.itemTypes.href` in the results of `GET /api`.\nAdd that ID as the `type` parameter to the call above. You can specify multiple item\ntypes if, for example, you are interested in all the different kinds of doors.\n\nFor example, if you were after a list of divisions, following the instructions above on the\ncurrent versions of Command Centre would produce the URL `/api/items?type=15`.\n\n## Status subscriptions\n\nThe item-specific APIs monitor only one item at a time, and are therefore not\nsuitable for watching large collections. If you have CC version 8.30 or later, you should use\nthe status subscription methods instead. We have tested subscriptions of 1000 items without\nnoticing undue strain on the server. While the calls do not impose an upper bound on that we\nsuggest keeping a watchful eye on the performance of the overall system if you go much higher.\n\nThe basic process for monitoring item states is:\n\n 1. Get all the IDs of the items you wish to monitor. You can do that using this API's own\n [search](items#get-api-items) with a `name`, `division`, or `type` parameter. If you're\n searching by division you'll need a division ID which (slightly recursively) is best found by\n using the same search function filtering for just divisions. If you're searching by type\n you'll need a [type ID](items#get-api-items-types).\n\n 1. [POST](items#post-api-items-updates) to create a subscription. Your program should\n get the URL from `items.updates.href` in the results of `GET /api`.\n\n 1. Take the current state of your items from the results of that call. If that's all you\n need, terrific. But if you want to monitor their state, continue.\n\n 1. [GET](items#get-api-items-updates) the\n `next.href` link that came in the results. The call will block until one of your\n monitored items changes state. When it returns, the results will be in the same format as the\n result of the POST, including the `next` link.\n\n 1. Goto 4.\n\n## Licensing\n\nEvery REST licence enables the items controller: RESTEvents, RESTCreateEvents, RESTCardholders,\nRESTStatus, and RESTOverrides.\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":{"ItemDetail":{"title":"Item detail","type":"object","description":"A call to `/api/items/{id}` (added in 8.40) returns one of these. It adds the item's division\nto the summary object.\n","allOf":[{"$ref":"#/components/schemas/ItemSummary"},{"type":"object","properties":{"division":{"type":"object","properties":{"id":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}}}}]},"ItemSummary":{"title":"Item summary","type":"object","description":"`/api/items` returns an array of these. Because it can contain an item of any type, it only\ncontains some fields that are common to all item types.\n\n`description` and `shortName` arrived in 9.60.\n","properties":{"id":{"type":"string","description":"Use this ID in the `source` filter when requesting events to limit events to those with\nthat source. Card events such as 'access granted', for example, have a door as their\nsource.\n"},"name":{"type":"string"},"shortName":{"type":"string","maxLength":16,"description":"Short names are not displayed by default. You must ask for them using the\n'fields' parameter:\n\n`?fields=shortname,...`.\n"},"description":{"type":"string","description":"In 9.60 and later."},"type":{"type":"object","description":"The `type` object contains the ID and name of the item's type.","properties":{"id":{"type":"string","description":"Use this ID in the `type` filter when requesting items if you wish to restrict the\nresults to items of a certain type.\n"},"name":{"type":"string","description":"A human-readable name of the item's type, suitable for display.\n\nThis string is translated using the installation's language pack, and Gallagher\nreserves the right to change item type names in new versions, so you should not do\nanything with this string except show it to a person.\n"},"canonicalTypeName":{"description":"An unchanging, alphanumeric, short, and hopefully descriptive identifier for the item type.\n\nThe set of possible values will grow as time passes but the strings themselves, unless\nhighlighted as temporary, will never change. You can count on an access zone always having\na canonical type name of 'accesszone', for example.\n\nAdded in 9.00.\n","type":"string"}}},"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"},"notes":{"type":"string","description":"Because of their potential size, notes are only available by request. Use the 'fields'\nparameter:\n\n`?fields=defaults,notes,...`\n"},"href":{"type":"string","description":"Reserved for internal use. Its value changed in version 9.10."}}}}},"paths":{"/api/items/{id}":{"get":{"tags":["Items"],"summary":"Get details of an item","description":"This returns some basic fields for one item. It returns the same information as the [item\nsearch](items#get-api-items) plus the item's division.\n\nAdded in 8.40.\n","parameters":[{"name":"id","in":"path","description":"The ID of the item.","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","description":"Return these fields. The values you can list are the same as the field\nnames in the details page. Using it you can return everything on the summary page that you\nwould find on the details page. Separate values with commas.\n\nUse the special value `defaults` to return the fields you would have received had you not given\nthe parameter at all. Obviously only do that if you have more to add.\n\nThe string must not contain any spaces. Just alphanumerics, underscores, commas, and dots.\n\n`description` and `shortName` arrived in 9.60.\n\nTreat the string matches as case-sensitive.\n","schema":{"type":"string","enum":["href","id","name","type","division","serverDisplayName","notes","description","shortName"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemDetail"}}}},"404":{"description":"That is not the href of an item. At least not one that your operator has the privilege\nto view.\n"}}}}}}
```
## List item types
> Retrieves the list of all item types in the Command Centre system. There are about 200.\
> This is useful for obtaining type IDs to use in item search filters and (in 9.00) the\
> canonical item type names.\
> \
> Note that some item types have a blank name. These types are vestigial: disregard them.\
> \
> Do not code this URL into your application. Take it from \`items.itemTypes.href\` in the\
> results of \`GET /api\`.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Items","description":"\nThese methods let you find items for your search filters and events, and monitor their states.\nThey return all items, including those that this API does not yet support in depth, and items\nadded by customisations. However because they do not have deep knowledge of item types they can\nonly give you the most basic fields.\n\n## Searching for items\n\nUse the search methods when you are building a filter for an [event\nsearch](events#get-api-events) or a [status\nsubscription](events#post-api-items-updates) and need the ID of an item or an item type, or\nwhen you are [creating an event](events#post-api-events) and need an href to use as the\nevent source.\n\nTo find an item, pass a substring of its name to the link at `features.items.items.href` in the\nresults of a call to `/api`. If you are sure of its name, place the name inside `\"` quotes, and\nit will use a full string match. Both types of search are case-insensitive.\n\nTo limit the search to items of a particular type, first get the ID of the type you\nare after using the link at `features.items.itemTypes.href` in the results of `GET /api`.\nAdd that ID as the `type` parameter to the call above. You can specify multiple item\ntypes if, for example, you are interested in all the different kinds of doors.\n\nFor example, if you were after a list of divisions, following the instructions above on the\ncurrent versions of Command Centre would produce the URL `/api/items?type=15`.\n\n## Status subscriptions\n\nThe item-specific APIs monitor only one item at a time, and are therefore not\nsuitable for watching large collections. If you have CC version 8.30 or later, you should use\nthe status subscription methods instead. We have tested subscriptions of 1000 items without\nnoticing undue strain on the server. While the calls do not impose an upper bound on that we\nsuggest keeping a watchful eye on the performance of the overall system if you go much higher.\n\nThe basic process for monitoring item states is:\n\n 1. Get all the IDs of the items you wish to monitor. You can do that using this API's own\n [search](items#get-api-items) with a `name`, `division`, or `type` parameter. If you're\n searching by division you'll need a division ID which (slightly recursively) is best found by\n using the same search function filtering for just divisions. If you're searching by type\n you'll need a [type ID](items#get-api-items-types).\n\n 1. [POST](items#post-api-items-updates) to create a subscription. Your program should\n get the URL from `items.updates.href` in the results of `GET /api`.\n\n 1. Take the current state of your items from the results of that call. If that's all you\n need, terrific. But if you want to monitor their state, continue.\n\n 1. [GET](items#get-api-items-updates) the\n `next.href` link that came in the results. The call will block until one of your\n monitored items changes state. When it returns, the results will be in the same format as the\n result of the POST, including the `next` link.\n\n 1. Goto 4.\n\n## Licensing\n\nEvery REST licence enables the items controller: RESTEvents, RESTCreateEvents, RESTCardholders,\nRESTStatus, and RESTOverrides.\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":{"ItemTypes":{"title":"Item types","type":"object","description":"Calls to `/api/items/types` return this object, an array of item types.","properties":{"itemTypes":{"description":"A list of item types.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The alphanumeric ID of the item type. Use this ID in the `type` filter when requesting items."},"name":{"type":"string","description":"The human-readable name of the item type. These strings will change over time as\nGallagher expands its product line, and can change with the server's language\nsettings, so take care if using them for anything except display.\n"},"canonicalTypeName":{"description":"An unchanging, alphanumeric, short, and hopefully descriptive identifier for the item type.\n\nThe set of possible values will grow as time passes but the strings themselves, unless\nhighlighted as temporary, will never change. You can count on an access zone always having\na canonical type name of 'accesszone', for example.\n\nAdded in 9.00.\n","type":"string"}}}}}}}},"paths":{"/api/items/types":{"get":{"tags":["Items"],"summary":"List item types","description":"Retrieves the list of all item types in the Command Centre system. There are about 200.\nThis is useful for obtaining type IDs to use in item search filters and (in 9.00) the\ncanonical item type names.\n\nNote that some item types have a blank name. These types are vestigial: disregard them.\n\nDo not code this URL into your application. Take it from `items.itemTypes.href` in the\nresults of `GET /api`.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemTypes"}}}},"403":{"description":"The site does not have a REST licence."}}}}}}
```
## Retrieve status updates
> Collects status updates from a subscription created using the \[/api/items/updates\
> POST]\(items#post-api-items-updates).\
> \
> This is a long poll, so if there are no updates waiting when you make the call it will block\
> until some arrive or a timeout passes (about 50 seconds).\
> \
> If you receive a 404 from this call it means that more than 30 seconds passed between the\
> server sending you the link and you GETting it, or the server restarted. In either case it\
> will have dropped your subscription: you will need to create a new one with a fresh POST.\
> \
> Therefore your loop can be:\
> \
> 1\. Create a subscription with a \[POST]\(items#post-api-items-updates).\
> 2\. Process the statuses in the results, if there are any.\
> 3\. Wait a second or two to avoid tight loops.\
> 4\. GET the link from the results. It may take up to a minute to respond.\
> 5\. If 404, go to 1.\
> 6\. Go to 2.\
> \
> ...plus the necessary exception handling, of course.\
> \
> Added in 8.30.\
> \
> Note that in versions prior to 9.50 the first time you make this GET request it will return\
> all the activity that came back from the POST. There are other cases where the GET might\
> return no updates or updates you have seen already (when some aspect of an item changes that\
> your operator does not have the privilege to view, or an override is sent, for example).\
> While these two behaviours are not harmful they are also not particularly helpful, so in\
> 9.50 the first GET will not return the same array as the POST: it will only send the\
> changes that happened after the POST, waiting if necessary.\
> \
> This change makes it much quicker to create subscriptions containing large numbers of items.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Items","description":"\nThese methods let you find items for your search filters and events, and monitor their states.\nThey return all items, including those that this API does not yet support in depth, and items\nadded by customisations. However because they do not have deep knowledge of item types they can\nonly give you the most basic fields.\n\n## Searching for items\n\nUse the search methods when you are building a filter for an [event\nsearch](events#get-api-events) or a [status\nsubscription](events#post-api-items-updates) and need the ID of an item or an item type, or\nwhen you are [creating an event](events#post-api-events) and need an href to use as the\nevent source.\n\nTo find an item, pass a substring of its name to the link at `features.items.items.href` in the\nresults of a call to `/api`. If you are sure of its name, place the name inside `\"` quotes, and\nit will use a full string match. Both types of search are case-insensitive.\n\nTo limit the search to items of a particular type, first get the ID of the type you\nare after using the link at `features.items.itemTypes.href` in the results of `GET /api`.\nAdd that ID as the `type` parameter to the call above. You can specify multiple item\ntypes if, for example, you are interested in all the different kinds of doors.\n\nFor example, if you were after a list of divisions, following the instructions above on the\ncurrent versions of Command Centre would produce the URL `/api/items?type=15`.\n\n## Status subscriptions\n\nThe item-specific APIs monitor only one item at a time, and are therefore not\nsuitable for watching large collections. If you have CC version 8.30 or later, you should use\nthe status subscription methods instead. We have tested subscriptions of 1000 items without\nnoticing undue strain on the server. While the calls do not impose an upper bound on that we\nsuggest keeping a watchful eye on the performance of the overall system if you go much higher.\n\nThe basic process for monitoring item states is:\n\n 1. Get all the IDs of the items you wish to monitor. You can do that using this API's own\n [search](items#get-api-items) with a `name`, `division`, or `type` parameter. If you're\n searching by division you'll need a division ID which (slightly recursively) is best found by\n using the same search function filtering for just divisions. If you're searching by type\n you'll need a [type ID](items#get-api-items-types).\n\n 1. [POST](items#post-api-items-updates) to create a subscription. Your program should\n get the URL from `items.updates.href` in the results of `GET /api`.\n\n 1. Take the current state of your items from the results of that call. If that's all you\n need, terrific. But if you want to monitor their state, continue.\n\n 1. [GET](items#get-api-items-updates) the\n `next.href` link that came in the results. The call will block until one of your\n monitored items changes state. When it returns, the results will be in the same format as the\n result of the POST, including the `next` link.\n\n 1. Goto 4.\n\n## Licensing\n\nEvery REST licence enables the items controller: RESTEvents, RESTCreateEvents, RESTCardholders,\nRESTStatus, and RESTOverrides.\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":{"ItemUpdate":{"title":"Item update","type":"object","description":"POSTs and GETs to `/api/items/updates` return this object. It contains an array of updates\nand a `next` link to collect more.\n\nAdded in 8.30.\n","properties":{"updates":{"description":"A list of items and their statuses.\n\nPrior to v9.50 the first two calls—the POST and the first GET—contain all the items in\nyour subscription (provided they are the types of item that have statuses). This is\nunnecessary and incurs a significant performance penalty, so in 9.50 that changed. The\nresults of the POST will contain all the items in your subscription, as before, but the\nfirst GET will not return them all a second time. Use [this\nalgorithm](items#get-api-items-updates).\n\nOn\nsubsequent GETs it will only contain the items that received status updates since your\nprevious call. Note that an item will be in this array if it received any status update\nat all, even if the status flags did not change. Prepare to receive updates that do not\ncontain novel data.\n\nThis array is not paginated: it could contain every one of the items you put in your\nPOST.\n\nAfter about 50 seconds the call will time out and return an empty array and a `next`\nlink. When that happens, follow the `next` link just as you would have if there had\nbeen changes. Do not re-use the URL that returned you the empty array, because that\nwill cause the server to start looking for status changes a point 50 seconds earlier\nthan necessary. The results will be the same, but the server will have done more work\nto generate them.\n","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The item's ID, from the list you sent in the POST that created this subscription.\n"},"statusFlags":{"type":"array","items":{"type":"string"},"description":"An array of string enumerations (flags) that describe the item's condition in a\nreliable, machine-readable way.\n\nThe item types that the REST API supports (such as fence zones and inputs) have a\nfull set of status flags, described in their own sections of this documentation.\nTo see the values that this enumeration can take, search for headings with 'status\nflags' in their name in those sections.\n\nItems that the REST API does not support yet (such as readers) will return error\nflags if they are in an unusual state, or nothing if they are online and reporting\nnormally. Therefore an empty array is a good sign.\n"},"statusText":{"type":"string","description":"The state of the item in a multi-line string taken from the server's language pack.\n"},"status":{"type":"string","description":"A one-line version of the status, with details removed if necessary to keep it short.\n"}}}},"next":{"description":"A link to GET more status updates. Do not wait longer than thirty seconds between\nreceiving this link and using it or your subscription will expire and you will need to\nsubmit another POST to create a new one.\n"}}}}},"paths":{"/api/items/updates":{"get":{"tags":["Items"],"summary":"Retrieve status updates","description":"Collects status updates from a subscription created using the [/api/items/updates\nPOST](items#post-api-items-updates).\n\nThis is a long poll, so if there are no updates waiting when you make the call it will block\nuntil some arrive or a timeout passes (about 50 seconds).\n\nIf you receive a 404 from this call it means that more than 30 seconds passed between the\nserver sending you the link and you GETting it, or the server restarted. In either case it\nwill have dropped your subscription: you will need to create a new one with a fresh POST.\n\nTherefore your loop can be:\n\n1. Create a subscription with a [POST](items#post-api-items-updates).\n2. Process the statuses in the results, if there are any.\n3. Wait a second or two to avoid tight loops.\n4. GET the link from the results. It may take up to a minute to respond.\n5. If 404, go to 1.\n6. Go to 2.\n\n...plus the necessary exception handling, of course.\n\nAdded in 8.30.\n\nNote that in versions prior to 9.50 the first time you make this GET request it will return\nall the activity that came back from the POST. There are other cases where the GET might\nreturn no updates or updates you have seen already (when some aspect of an item changes that\nyour operator does not have the privilege to view, or an override is sent, for example).\nWhile these two behaviours are not harmful they are also not particularly helpful, so in\n9.50 the first GET will not return the same array as the POST: it will only send the\nchanges that happened after the POST, waiting if necessary.\n\nThis change makes it much quicker to create subscriptions containing large numbers of items.\n","parameters":[{"name":"bookmark","in":"query","description":"Identifies your subscription and your position in the change list. You should\nnot set this parameter: it will be in the link that the server sends back to\nyou.\n","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemUpdate"}}}},"403":{"description":"The site does not have a REST licence."},"404":{"description":"The subscription does not exist, which probably means you waited too long between calls.\n"}}}}}}
```
## Subscribe to status updates
> Creates a subscription to status changes. You POST a list of item IDs and the server\
> returns the status flags of those items plus a link. When you GET that link some time\
> later the server will return the items that changed state between the two calls.\
> \
> If you do not GET the link within thirty seconds of the POST returning, the server will drop\
> your subscription and free up the resources it had allocated to servicing it. If that\
> happens you will need to send this POST again to create a new subscription.\
> \
> Your operator must have view privileges on every item in the subscription otherwise you will\
> receive a 4xx.\
> \
> The subscription notices changes in state, not in configuration, so an operator modifying an\
> item will not cause anything to come out of this API unless the change in configuration also\
> causes a change in state.\
> \
> Because this call returns the status of items, this call requires the RESTStatus licence.\
> \
> Added in 8.30. 9.30 corrected the 401 response to a 403.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Items","description":"\nThese methods let you find items for your search filters and events, and monitor their states.\nThey return all items, including those that this API does not yet support in depth, and items\nadded by customisations. However because they do not have deep knowledge of item types they can\nonly give you the most basic fields.\n\n## Searching for items\n\nUse the search methods when you are building a filter for an [event\nsearch](events#get-api-events) or a [status\nsubscription](events#post-api-items-updates) and need the ID of an item or an item type, or\nwhen you are [creating an event](events#post-api-events) and need an href to use as the\nevent source.\n\nTo find an item, pass a substring of its name to the link at `features.items.items.href` in the\nresults of a call to `/api`. If you are sure of its name, place the name inside `\"` quotes, and\nit will use a full string match. Both types of search are case-insensitive.\n\nTo limit the search to items of a particular type, first get the ID of the type you\nare after using the link at `features.items.itemTypes.href` in the results of `GET /api`.\nAdd that ID as the `type` parameter to the call above. You can specify multiple item\ntypes if, for example, you are interested in all the different kinds of doors.\n\nFor example, if you were after a list of divisions, following the instructions above on the\ncurrent versions of Command Centre would produce the URL `/api/items?type=15`.\n\n## Status subscriptions\n\nThe item-specific APIs monitor only one item at a time, and are therefore not\nsuitable for watching large collections. If you have CC version 8.30 or later, you should use\nthe status subscription methods instead. We have tested subscriptions of 1000 items without\nnoticing undue strain on the server. While the calls do not impose an upper bound on that we\nsuggest keeping a watchful eye on the performance of the overall system if you go much higher.\n\nThe basic process for monitoring item states is:\n\n 1. Get all the IDs of the items you wish to monitor. You can do that using this API's own\n [search](items#get-api-items) with a `name`, `division`, or `type` parameter. If you're\n searching by division you'll need a division ID which (slightly recursively) is best found by\n using the same search function filtering for just divisions. If you're searching by type\n you'll need a [type ID](items#get-api-items-types).\n\n 1. [POST](items#post-api-items-updates) to create a subscription. Your program should\n get the URL from `items.updates.href` in the results of `GET /api`.\n\n 1. Take the current state of your items from the results of that call. If that's all you\n need, terrific. But if you want to monitor their state, continue.\n\n 1. [GET](items#get-api-items-updates) the\n `next.href` link that came in the results. The call will block until one of your\n monitored items changes state. When it returns, the results will be in the same format as the\n result of the POST, including the `next` link.\n\n 1. Goto 4.\n\n## Licensing\n\nEvery REST licence enables the items controller: RESTEvents, RESTCreateEvents, RESTCardholders,\nRESTStatus, and RESTOverrides.\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":{"ItemUpdate":{"title":"Item update","type":"object","description":"POSTs and GETs to `/api/items/updates` return this object. It contains an array of updates\nand a `next` link to collect more.\n\nAdded in 8.30.\n","properties":{"updates":{"description":"A list of items and their statuses.\n\nPrior to v9.50 the first two calls—the POST and the first GET—contain all the items in\nyour subscription (provided they are the types of item that have statuses). This is\nunnecessary and incurs a significant performance penalty, so in 9.50 that changed. The\nresults of the POST will contain all the items in your subscription, as before, but the\nfirst GET will not return them all a second time. Use [this\nalgorithm](items#get-api-items-updates).\n\nOn\nsubsequent GETs it will only contain the items that received status updates since your\nprevious call. Note that an item will be in this array if it received any status update\nat all, even if the status flags did not change. Prepare to receive updates that do not\ncontain novel data.\n\nThis array is not paginated: it could contain every one of the items you put in your\nPOST.\n\nAfter about 50 seconds the call will time out and return an empty array and a `next`\nlink. When that happens, follow the `next` link just as you would have if there had\nbeen changes. Do not re-use the URL that returned you the empty array, because that\nwill cause the server to start looking for status changes a point 50 seconds earlier\nthan necessary. The results will be the same, but the server will have done more work\nto generate them.\n","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The item's ID, from the list you sent in the POST that created this subscription.\n"},"statusFlags":{"type":"array","items":{"type":"string"},"description":"An array of string enumerations (flags) that describe the item's condition in a\nreliable, machine-readable way.\n\nThe item types that the REST API supports (such as fence zones and inputs) have a\nfull set of status flags, described in their own sections of this documentation.\nTo see the values that this enumeration can take, search for headings with 'status\nflags' in their name in those sections.\n\nItems that the REST API does not support yet (such as readers) will return error\nflags if they are in an unusual state, or nothing if they are online and reporting\nnormally. Therefore an empty array is a good sign.\n"},"statusText":{"type":"string","description":"The state of the item in a multi-line string taken from the server's language pack.\n"},"status":{"type":"string","description":"A one-line version of the status, with details removed if necessary to keep it short.\n"}}}},"next":{"description":"A link to GET more status updates. Do not wait longer than thirty seconds between\nreceiving this link and using it or your subscription will expire and you will need to\nsubmit another POST to create a new one.\n"}}}}},"paths":{"/api/items/updates":{"post":{"tags":["Items"],"summary":"Subscribe to status updates","description":"Creates a subscription to status changes. You POST a list of item IDs and the server\nreturns the status flags of those items plus a link. When you GET that link some time\nlater the server will return the items that changed state between the two calls.\n\nIf you do not GET the link within thirty seconds of the POST returning, the server will drop\nyour subscription and free up the resources it had allocated to servicing it. If that\nhappens you will need to send this POST again to create a new subscription.\n\nYour operator must have view privileges on every item in the subscription otherwise you will\nreceive a 4xx.\n\nThe subscription notices changes in state, not in configuration, so an operator modifying an\nitem will not cause anything to come out of this API unless the change in configuration also\ncauses a change in state.\n\nBecause this call returns the status of items, this call requires the RESTStatus licence.\n\nAdded in 8.30. 9.30 corrected the 401 response to a 403.\n","requestBody":{"description":"The body of the POST needs to contain a list of item IDs in an array called `itemIds`.\nEven though they look like small integers, these IDs are actually strings so don't\nforget the quotes.\n","content":{"application/json":{"schema":{"type":"object","description":"Contains a list of item IDs (short alphanums). Send it in the body of a\n[POST](items#post-api-items-updates) to create a subscription to status\nupdates to the items with these IDs.\n","required":["itemIds"],"properties":{"itemIds":{"type":"array","items":{"type":"string"}}}}}},"required":false},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemUpdate"}}}},"400":{"description":"The server could not parse the request body. Check your JSON."},"401":{"description":"In versions prior to 9.30 it means the operator does not have the privilege to view the\nmonitored items.\n"},"403":{"description":"The site does not have the RESTStatus licence or, in 9.30 and later, the operator does\nnot have view privileges on all the monitored items.\n\nIn the latter case, if the server is 9.60 or later, the body of the 403 will contain the\nlist of item IDs that the operator is permitted to monitor.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"apiMessages":{"type":"array","items":{"type":"string"}},"details":{"type":"object","properties":{"allowedItemIds":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}}
```
---
# 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/items.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.