> 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/doors.md).
# Doors
These methods give you read access to basic data about Doors in the Command Centre database, and let you open them.
The first use case below introduces the main entry point. It is a paginated search interface that gives you any number of doors, each containing the fields you ask for in the query (including, for example, the URLs to open them).
### Half-cycle doors and the lock override
Doors with half-cycle locks differ from regular doors in that once unlocked with an 'open' override or a card badge, they stay unlocked until physically opened then closed, or re-locked with a 'lock' override (added in 9.40). These doors normally require a physical key to open in addition to the electronic unlock. They are popular in correctional facilities.
### Door status flags
If the door is online, its `statusFlags` field will contain one or more of these flags:
* `forced` means the door was opened or unlocked while secure.
* `openTooLong` means the door has been open for longer than its configured DOTL time.
* `tamper` means one of the door's inputs is in a tampered state. The usual cause of that is a resistance moving outside nominal range, meaning the input has been cut or shorted.
* `open` means the door has a sensor for detecting its openness and it is reporting as such.
* `closed` is the inverse. The door is closed or has no open sensor.
* `locked` means the door is locked. It reflects the state of the door's unlock sensor, if it has one. Otherwise it reflects the state of the door's unlock output, if it has that. Without an unlock output, a door is not capable of access control.
* `unlocked` means 'locked' is not set.
* `secure` means the door's normal state is closed and locked.
* `free` is the opposite of 'secure': nobody needs to badge to open it.
`secure` and `free` do not change when the door opens. They are about whether the door is enforcing access control, not about the current state of the door hardware.
When allowing passage, a door normally moves from closed and locked to closed and unlocked, to open and unlocked (extremely briefly), then to open and locked while someone is walking through it, then back to closed and locked. It will be secure throughout.
#### Door flag rules
* If and only if the door is online, exactly one of 'closed' or 'open' will appear, and one of 'locked' or 'unlocked', and one of 'secure' or 'free'.
So, to establish if the door is in a normal state, look for 'closed' or 'open'. If neither is present, your door is in an error state.
### Use cases
#### Listing Doors
1. `GET /api`.
2. Follow the link at `features.doors.doors.href`, appending a search term such as `name=substring` to filter the selection if you have a lot of doors, and `fields` to tell the server what to return about each. The next section covers those query parameters.
3. Process the results, following the `next` link until there isn't one.
#### Overriding a door open
1. Find the href for the door using the process above.
2. GET it.
3. POST to the `open` ↪ URL in the `commands` structure of the results.
#### Finding a door's status
1. Find the href for the door using the process above, and GET it.
2. Follow the `updates` href from that page.
3. Use the flag rules above to interpret the status flags you receive.
4. Follow the `next` link to stay up to date.
### Licensing
All the POSTs that override items require RESTOverrides.
If you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough information to let you find the item you want to override but they do not return its status. In 8.50 and older, the GET will fail without RESTStatus.
The RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well as override it, you will need both.
## Search doors
> This returns a summary of the doors matching your search criteria.\
> \
> The result will contain no more than 100 or 1000 doors (depending on your version), or as\
> many as you asked for; you should follow the \`next\` link, if it is\
> present, to collect the next batch.\
> \
> If your result set is empty it means your operator does not have the privilege to view any\
> doors, such as 'View Site', 'Edit Site', or 'Override - Open Door'. Perhaps there are no\
> doors in the divisions in which your operator has privileges, or your operator has no\
> privileges at all.\
> \
> When you have loaded them all there will be no \`next\` link.\
> \
> Do not code this URL into your application. Take it from the 'href' field in the\
> \`features.doors.doors\` section of \`/api\`.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Doors","description":"These methods give you read access to basic data about Doors in the Command Centre\ndatabase, and let you open them.\n\nThe first use case below introduces the main entry point. It is a paginated search interface\nthat gives you any number of doors, each containing the fields you ask for in the query\n(including, for example, the URLs to open them).\n\n## Half-cycle doors and the lock override\n\nDoors with half-cycle locks differ from regular doors in that once unlocked with an 'open'\noverride or a card badge, they stay unlocked until physically opened then closed, or re-locked\nwith a 'lock' override (added in 9.40). These doors normally require a physical key to open in\naddition to the electronic unlock. They are popular in correctional facilities.\n\n## Door status flags\n\nIf the door is online, its `statusFlags` field will contain one or more of these flags:\n\n- `forced` means the door was opened or unlocked while secure.\n- `openTooLong` means the door has been open for longer than its configured DOTL time.\n- `tamper` means one of the door's inputs is in a tampered state. The usual cause of that is a\n resistance moving outside nominal range, meaning the input has been cut or shorted.\n- `open` means the door has a sensor for detecting its openness and it is reporting as such.\n- `closed` is the inverse. The door is closed or has no open sensor.\n- `locked` means the door is locked. It reflects the state of the door's unlock sensor, if it has\n one. Otherwise it reflects the state of the door's unlock output, if it has that. Without an\n unlock output, a door is not capable of access control.\n- `unlocked` means 'locked' is not set.\n- `secure` means the door's normal state is closed and locked.\n- `free` is the opposite of 'secure': nobody needs to badge to open it.\n\n`secure` and `free` do not change when the door opens. They are about whether the door is\nenforcing access control, not about the current state of the door hardware.\n\nWhen allowing passage, a door normally moves from closed and locked to closed and unlocked, to\nopen and unlocked (extremely briefly), then to open and locked while someone is walking through\nit, then back to closed and locked. It will be secure throughout.\n\n### Door flag rules\n\n- If and only if the door is online, exactly one of 'closed' or 'open' will appear, and one of\n 'locked' or 'unlocked', and one of 'secure' or 'free'.\n\nSo, to establish if the door is in a normal state, look for 'closed' or 'open'. If neither is\npresent, your door is in an error state.\n\n## Use cases\n\n### Listing Doors\n1. `GET /api`.\n2. Follow the link at `features.doors.doors.href`, appending a search term such as\n `name=substring` to filter the selection if you have a lot of doors, and `fields` to tell the\n server what to return about each. The next section covers those query parameters.\n3. Process the results, following the `next` link until there isn't one.\n\n### Overriding a door open\n1. Find the href for the door using the process above.\n2. GET it.\n3. POST to the `open` [↪](doors#post-api-doors-id-open) URL in the `commands` structure\n of the [results](models#doordetail).\n\n### Finding a door's status\n1. Find the href for the door using the process above, and GET it.\n3. Follow the `updates` href from that page.\n4. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status. In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both."}],"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":{"DoorSearch":{"title":"Door search","description":"An array of door summaries, and a `next` link for more.","properties":{"results":{"type":"array","description":"An array of door summaries.","items":{"$ref":"#/components/schemas/DoorSummary"}},"next":{"type":"object","description":"The link to the next page. Absent if you have retrieved them all.","properties":{"href":{"type":"string","format":"uri-reference"}}}}},"DoorSummary":{"title":"Door summary","description":"`/api/doors` returns an array of these. It is a subset of what you get from a\ndoor's detail page at `/api/doors/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [door detail](models#doordetail) object for this door.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server. This is the ID to use in the\n`source` parameter of [event filters](events#get-api-events)\nwhen you are interested in events originating at this door.\n"},"name":{"type":"string"}}}},"responses":{"403nolicence":{"description":"A server running 8.50 or earlier is missing the RESTStatus licence. A server running 8.60\nor later is missing both the RESTStatus and RESTOverrides licences. One of those is enough\nfor this API call in 8.60 and later.\n"}}},"paths":{"/api/doors":{"get":{"tags":["Doors"],"summary":"Search doors","description":"This returns a summary of the doors matching your search criteria.\n\nThe result will contain no more than 100 or 1000 doors (depending on your version), or as\nmany as you asked for; you should follow the `next` link, if it is\npresent, to collect the next batch.\n\nIf your result set is empty it means your operator does not have the privilege to view any\ndoors, such as 'View Site', 'Edit Site', or 'Override - Open Door'. Perhaps there are no\ndoors in the divisions in which your operator has privileges, or your operator has no\nprivileges at all.\n\nWhen you have loaded them all there will be no `next` link.\n\nDo not code this URL into your application. Take it from the 'href' field in the\n`features.doors.doors` 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"},{"name":"fields","description":"This instructs the server to return only these fields in the search results. The values you can list are the same as the field\nnames in the details page. Using this 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\nTreat the string matches as case-sensitive.\n\nIn v8.00 you will receive the href and internal ID even if you did not ask for them. In 8.10\nand later you will only get what you asked for. If you are going to send the `fields`\nparameter and need the href or ID, be explicit.\n","schema":{"type":"string","enum":["href","id","name","shortName","description","division","commands","connectedController","entryAccessZone","exitAccessZone","statusFlags","statusText","status","notes","updates","defaults"]},"in":"query","explode":false,"style":"form","required":false},{"$ref":"#/components/parameters/pos"},{"$ref":"#/components/parameters/skip"}],"responses":{"200":{"description":"Success. See the note in the description about privileges if your result set is empty.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoorSearch"}}}},"403":{"$ref":"#/components/responses/403nolicence"}}}}}}
```
## Get details of a door
> This returns the detail of one door.\
> \
> Follow the 'href' field in a \[door summary]\(models#doorsummary) to get here.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Doors","description":"These methods give you read access to basic data about Doors in the Command Centre\ndatabase, and let you open them.\n\nThe first use case below introduces the main entry point. It is a paginated search interface\nthat gives you any number of doors, each containing the fields you ask for in the query\n(including, for example, the URLs to open them).\n\n## Half-cycle doors and the lock override\n\nDoors with half-cycle locks differ from regular doors in that once unlocked with an 'open'\noverride or a card badge, they stay unlocked until physically opened then closed, or re-locked\nwith a 'lock' override (added in 9.40). These doors normally require a physical key to open in\naddition to the electronic unlock. They are popular in correctional facilities.\n\n## Door status flags\n\nIf the door is online, its `statusFlags` field will contain one or more of these flags:\n\n- `forced` means the door was opened or unlocked while secure.\n- `openTooLong` means the door has been open for longer than its configured DOTL time.\n- `tamper` means one of the door's inputs is in a tampered state. The usual cause of that is a\n resistance moving outside nominal range, meaning the input has been cut or shorted.\n- `open` means the door has a sensor for detecting its openness and it is reporting as such.\n- `closed` is the inverse. The door is closed or has no open sensor.\n- `locked` means the door is locked. It reflects the state of the door's unlock sensor, if it has\n one. Otherwise it reflects the state of the door's unlock output, if it has that. Without an\n unlock output, a door is not capable of access control.\n- `unlocked` means 'locked' is not set.\n- `secure` means the door's normal state is closed and locked.\n- `free` is the opposite of 'secure': nobody needs to badge to open it.\n\n`secure` and `free` do not change when the door opens. They are about whether the door is\nenforcing access control, not about the current state of the door hardware.\n\nWhen allowing passage, a door normally moves from closed and locked to closed and unlocked, to\nopen and unlocked (extremely briefly), then to open and locked while someone is walking through\nit, then back to closed and locked. It will be secure throughout.\n\n### Door flag rules\n\n- If and only if the door is online, exactly one of 'closed' or 'open' will appear, and one of\n 'locked' or 'unlocked', and one of 'secure' or 'free'.\n\nSo, to establish if the door is in a normal state, look for 'closed' or 'open'. If neither is\npresent, your door is in an error state.\n\n## Use cases\n\n### Listing Doors\n1. `GET /api`.\n2. Follow the link at `features.doors.doors.href`, appending a search term such as\n `name=substring` to filter the selection if you have a lot of doors, and `fields` to tell the\n server what to return about each. The next section covers those query parameters.\n3. Process the results, following the `next` link until there isn't one.\n\n### Overriding a door open\n1. Find the href for the door using the process above.\n2. GET it.\n3. POST to the `open` [↪](doors#post-api-doors-id-open) URL in the `commands` structure\n of the [results](models#doordetail).\n\n### Finding a door's status\n1. Find the href for the door using the process above, and GET it.\n3. Follow the `updates` href from that page.\n4. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status. In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both."}],"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":{"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An internal identifier."}},"schemas":{"DoorDetail":{"title":"Door detail","description":"[/api/doors/{id}](doors#get-api-doors-id-) returns one of these.\n","allOf":[{"$ref":"#/components/schemas/DoorSummary"},{"type":"object","properties":{"description":{"type":"string"},"division":{"type":"object","description":"The division containing this door."},"entryAccessZone":{"type":"object","description":"The name and href of the access zone to which this door allows entry.\n","properties":{"name":{"type":"string"},"href":{"description":"This is the address of the [access zone's\ndetail](models#accesszonedetail) page (which includes a link back here in\nits `doors` array).\n","type":"string","format":"uri-reference"}}},"exitAccessZone":{"type":"object","description":"The name and href of the access zone to which this door allows entry in the reverse\ndirection (from its exit reader).\n\nIt will not appear by default. You need to ask for it with `fields=exitAccessZone`.\n\nNew to 8.50.\n","properties":{"name":{"type":"string"},"href":{"description":"This is the address of the [access zone's\ndetail](models#accesszonedetail) page (which includes a link back here in\nits `doors` array).\n","type":"string","format":"uri-reference"}}},"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"},"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"},"updates":{"type":"object","description":"Follow the URL in the href inside this block to receive the item's current status, then follow\nthe `next` link in the results to long poll for changes to that status.\n\nThis method only monitors one item at a time. To monitor the status of many items, use the\n[status-monitoring routes](#?route=post-/api/items/updates).\n\nUpdate pages take the same `fields` parameter as summary and details pages. You should use\nthat to request all the fields you need in the update.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"statusFlags":{"type":"array","items":{"type":"string"},"description":"The search and details pages do not return status flags by default, because an item's status\nis unknown until something is monitoring it. If you want status flags on the search and\ndetails pages you must ask for them using the `fields` parameter, but our advice is to monitor\nthem using [status subscriptions](items#status-subscriptions) if you are running 8.30 or\nlater, otherwise the item's `updates` link. See the [item status](item-status) section\nfor a full description of how to stay up to date with item status, and this item's\nintroduction in the Operations section for what flags this item might return and what they\nmean.\n"},"commands":{"type":"object","description":"An array of commands, each represented by a block containing an href that accepts a\nPOST to send an override.\n\nIf your operator is privileged to override the door's entry zone, and the zone only\nhas one door, there will be 17 more links: four each of the four access zone modes,\nplus 'cancel'. Each zone mode has four variants: with or without PINs, and with or\nwithout an end time.\n\nThis block will only contain the links that your operator is privileged to perform.\nExamples of the privileges you need are in the documentation for the POSTs.\n\nThe zone overrides are not repeated here.\n","properties":{"open":{"type":"object","properties":{"href":{"description":"[POST](doors#post-api-doors-id-open) to this to open this door.","type":"string","format":"uri-reference"}}},"lock":{"type":"object","properties":{"href":{"description":"[POST](doors#post-api-doors-id-lock) to this to lock this door.","type":"string","format":"uri-reference"}}}}},"connectedController":{"type":"object","description":"This block describes this door's hardware controller.\n\nRetrieving it takes a little more time than the other fields so only ask for it if you\nneed it, if your doors are legion.\n","properties":{"name":{"type":"string"},"href":{"type":"string","format":"uri-reference","description":"This is the REST API's identifier for the hardware controller. It is only an\nidentifier, not a usable URL, because in 9.50 there is no interface for hardware\ncontrollers. GETting the URL will return a 404.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server. This is the ID to use in the `source`\nparameter of [event filters](events#get-api-events) and in the body of [status\nsubscriptions](items#status-subscriptions) when you are interested in events originating at this item.\n"}}}}}]},"DoorSummary":{"title":"Door summary","description":"`/api/doors` returns an array of these. It is a subset of what you get from a\ndoor's detail page at `/api/doors/{id}` (linked as the href in this object).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to a [door detail](models#doordetail) object for this door.\n"},"id":{"type":"string","description":"An alphanumeric identifier, unique to the server. This is the ID to use in the\n`source` parameter of [event filters](events#get-api-events)\nwhen you are interested in events originating at this door.\n"},"name":{"type":"string"}}}},"responses":{"403nolicence":{"description":"A server running 8.50 or earlier is missing the RESTStatus licence. A server running 8.60\nor later is missing both the RESTStatus and RESTOverrides licences. One of those is enough\nfor this API call in 8.60 and later.\n"},"404door":{"description":"The request's URL does not represent a door, or the operator does not have a privilege on\nthe door's division that allows viewing them, such as 'View Site', 'Edit Site', or 'Override\n- Open Door'.\n"}}},"paths":{"/api/doors/{id}":{"get":{"tags":["Doors"],"summary":"Get details of a door","description":"This returns the detail of one door.\n\nFollow the 'href' field in a [door summary](models#doorsummary) to get here.\n","parameters":[{"$ref":"#/components/parameters/id"},{"name":"fields","description":"This instructs the server to return only these fields in the details page instead of the default set. The values you can list\nare the same as the field names you would see in the results. Use it to cut back on the size\nof the response. Separate values with commas.\n\nTreat the string matches as case-sensitive.\n\nIn v8.00 you will receive the href and internal ID even if you did not ask for them. In 8.10\nand later you will only get what you asked for. If you are going to send the `fields`\nparameter and need the href or ID, be explicit.\n","schema":{"type":"string","enum":["href","id","name","shortName","description","division","commands","connectedController","entryAccessZone","exitAccessZone","statusFlags","statusText","status","notes","updates","defaults"]},"in":"query","explode":false,"style":"form","required":false}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoorDetail"}}}},"403":{"$ref":"#/components/responses/403nolicence"},"404":{"$ref":"#/components/responses/404door"}}}}}}
```
## Lock a door
> Sends an override to lock a half-cycle door that is in the unlocked state, rather than\
> letting it wait to open and close.\
> \
> Follow the \`commands.lock.href\` field in a \[door]\(models#doordetail) to get here.\
> \
> Added in 9.40.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Doors","description":"These methods give you read access to basic data about Doors in the Command Centre\ndatabase, and let you open them.\n\nThe first use case below introduces the main entry point. It is a paginated search interface\nthat gives you any number of doors, each containing the fields you ask for in the query\n(including, for example, the URLs to open them).\n\n## Half-cycle doors and the lock override\n\nDoors with half-cycle locks differ from regular doors in that once unlocked with an 'open'\noverride or a card badge, they stay unlocked until physically opened then closed, or re-locked\nwith a 'lock' override (added in 9.40). These doors normally require a physical key to open in\naddition to the electronic unlock. They are popular in correctional facilities.\n\n## Door status flags\n\nIf the door is online, its `statusFlags` field will contain one or more of these flags:\n\n- `forced` means the door was opened or unlocked while secure.\n- `openTooLong` means the door has been open for longer than its configured DOTL time.\n- `tamper` means one of the door's inputs is in a tampered state. The usual cause of that is a\n resistance moving outside nominal range, meaning the input has been cut or shorted.\n- `open` means the door has a sensor for detecting its openness and it is reporting as such.\n- `closed` is the inverse. The door is closed or has no open sensor.\n- `locked` means the door is locked. It reflects the state of the door's unlock sensor, if it has\n one. Otherwise it reflects the state of the door's unlock output, if it has that. Without an\n unlock output, a door is not capable of access control.\n- `unlocked` means 'locked' is not set.\n- `secure` means the door's normal state is closed and locked.\n- `free` is the opposite of 'secure': nobody needs to badge to open it.\n\n`secure` and `free` do not change when the door opens. They are about whether the door is\nenforcing access control, not about the current state of the door hardware.\n\nWhen allowing passage, a door normally moves from closed and locked to closed and unlocked, to\nopen and unlocked (extremely briefly), then to open and locked while someone is walking through\nit, then back to closed and locked. It will be secure throughout.\n\n### Door flag rules\n\n- If and only if the door is online, exactly one of 'closed' or 'open' will appear, and one of\n 'locked' or 'unlocked', and one of 'secure' or 'free'.\n\nSo, to establish if the door is in a normal state, look for 'closed' or 'open'. If neither is\npresent, your door is in an error state.\n\n## Use cases\n\n### Listing Doors\n1. `GET /api`.\n2. Follow the link at `features.doors.doors.href`, appending a search term such as\n `name=substring` to filter the selection if you have a lot of doors, and `fields` to tell the\n server what to return about each. The next section covers those query parameters.\n3. Process the results, following the `next` link until there isn't one.\n\n### Overriding a door open\n1. Find the href for the door using the process above.\n2. GET it.\n3. POST to the `open` [↪](doors#post-api-doors-id-open) URL in the `commands` structure\n of the [results](models#doordetail).\n\n### Finding a door's status\n1. Find the href for the door using the process above, and GET it.\n3. Follow the `updates` href from that page.\n4. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status. In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both."}],"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":{"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An internal identifier."},"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator. The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70. Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"responses":{"403dooroverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding doors (such as\n'Override - Open Door').\n"}}},"paths":{"/api/doors/{id}/lock":{"post":{"tags":["Doors"],"summary":"Lock a door","description":"Sends an override to lock a half-cycle door that is in the unlocked state, rather than\nletting it wait to open and close.\n\nFollow the `commands.lock.href` field in a [door](models#doordetail) to get here.\n\nAdded in 9.40.\n","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/requested_by"}],"responses":{"204":{"description":"Success."},"403":{"$ref":"#/components/responses/403dooroverride"}}}}}}
```
## Open a door
> Sends an override to unlock a door.\
> \
> Follow the \`commands.open.href\` field in a \[door]\(models#doordetail) to get here.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Doors","description":"These methods give you read access to basic data about Doors in the Command Centre\ndatabase, and let you open them.\n\nThe first use case below introduces the main entry point. It is a paginated search interface\nthat gives you any number of doors, each containing the fields you ask for in the query\n(including, for example, the URLs to open them).\n\n## Half-cycle doors and the lock override\n\nDoors with half-cycle locks differ from regular doors in that once unlocked with an 'open'\noverride or a card badge, they stay unlocked until physically opened then closed, or re-locked\nwith a 'lock' override (added in 9.40). These doors normally require a physical key to open in\naddition to the electronic unlock. They are popular in correctional facilities.\n\n## Door status flags\n\nIf the door is online, its `statusFlags` field will contain one or more of these flags:\n\n- `forced` means the door was opened or unlocked while secure.\n- `openTooLong` means the door has been open for longer than its configured DOTL time.\n- `tamper` means one of the door's inputs is in a tampered state. The usual cause of that is a\n resistance moving outside nominal range, meaning the input has been cut or shorted.\n- `open` means the door has a sensor for detecting its openness and it is reporting as such.\n- `closed` is the inverse. The door is closed or has no open sensor.\n- `locked` means the door is locked. It reflects the state of the door's unlock sensor, if it has\n one. Otherwise it reflects the state of the door's unlock output, if it has that. Without an\n unlock output, a door is not capable of access control.\n- `unlocked` means 'locked' is not set.\n- `secure` means the door's normal state is closed and locked.\n- `free` is the opposite of 'secure': nobody needs to badge to open it.\n\n`secure` and `free` do not change when the door opens. They are about whether the door is\nenforcing access control, not about the current state of the door hardware.\n\nWhen allowing passage, a door normally moves from closed and locked to closed and unlocked, to\nopen and unlocked (extremely briefly), then to open and locked while someone is walking through\nit, then back to closed and locked. It will be secure throughout.\n\n### Door flag rules\n\n- If and only if the door is online, exactly one of 'closed' or 'open' will appear, and one of\n 'locked' or 'unlocked', and one of 'secure' or 'free'.\n\nSo, to establish if the door is in a normal state, look for 'closed' or 'open'. If neither is\npresent, your door is in an error state.\n\n## Use cases\n\n### Listing Doors\n1. `GET /api`.\n2. Follow the link at `features.doors.doors.href`, appending a search term such as\n `name=substring` to filter the selection if you have a lot of doors, and `fields` to tell the\n server what to return about each. The next section covers those query parameters.\n3. Process the results, following the `next` link until there isn't one.\n\n### Overriding a door open\n1. Find the href for the door using the process above.\n2. GET it.\n3. POST to the `open` [↪](doors#post-api-doors-id-open) URL in the `commands` structure\n of the [results](models#doordetail).\n\n### Finding a door's status\n1. Find the href for the door using the process above, and GET it.\n3. Follow the `updates` href from that page.\n4. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status. In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both."}],"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":{"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An internal identifier."},"requested_by":{"name":"requested_by","in":"query","required":false,"schema":{"type":"string"},"description":"Attributes this override to the cardholder with this ID rather than the REST operator.\nPrivilege checks will use the operator as normal, but event monitors and reports will state\nthat the person responsible for the override was the attributed cardholder, not the REST\noperator. The REST operator will appear in a special mention in the event's details.\n\nFirst available in 8.70. Versions older than 8.70 will ignore the parameter, leaving the\noverride attributed to the REST operator.\n"}},"responses":{"403dooroverride":{"description":"The site does not have the RESTOverrides licence (in which case the body of the result will\nsay so), or the operator does not have a privilege that allows overriding doors (such as\n'Override - Open Door').\n"}}},"paths":{"/api/doors/{id}/open":{"post":{"tags":["Doors"],"summary":"Open a door","description":"Sends an override to unlock a door.\n\nFollow the `commands.open.href` field in a [door](models#doordetail) to get here.\n","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/requested_by"}],"responses":{"204":{"description":"Success."},"403":{"$ref":"#/components/responses/403dooroverride"}}}}}}
```
## Monitor a door
> See the \[item status topic]\(item-status) for how to use the updates APIs.\
> \
> Note that this API call is good for watching one item only; if you want to monitor several,\
> you are better off with a \[status subscription]\(items#status-subscriptions).\
> \
> Follow the 'updates' field in a door \[summary]\(models#doorsummary) or\
> \[details]\(models#doordetail) page to get here.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Doors","description":"These methods give you read access to basic data about Doors in the Command Centre\ndatabase, and let you open them.\n\nThe first use case below introduces the main entry point. It is a paginated search interface\nthat gives you any number of doors, each containing the fields you ask for in the query\n(including, for example, the URLs to open them).\n\n## Half-cycle doors and the lock override\n\nDoors with half-cycle locks differ from regular doors in that once unlocked with an 'open'\noverride or a card badge, they stay unlocked until physically opened then closed, or re-locked\nwith a 'lock' override (added in 9.40). These doors normally require a physical key to open in\naddition to the electronic unlock. They are popular in correctional facilities.\n\n## Door status flags\n\nIf the door is online, its `statusFlags` field will contain one or more of these flags:\n\n- `forced` means the door was opened or unlocked while secure.\n- `openTooLong` means the door has been open for longer than its configured DOTL time.\n- `tamper` means one of the door's inputs is in a tampered state. The usual cause of that is a\n resistance moving outside nominal range, meaning the input has been cut or shorted.\n- `open` means the door has a sensor for detecting its openness and it is reporting as such.\n- `closed` is the inverse. The door is closed or has no open sensor.\n- `locked` means the door is locked. It reflects the state of the door's unlock sensor, if it has\n one. Otherwise it reflects the state of the door's unlock output, if it has that. Without an\n unlock output, a door is not capable of access control.\n- `unlocked` means 'locked' is not set.\n- `secure` means the door's normal state is closed and locked.\n- `free` is the opposite of 'secure': nobody needs to badge to open it.\n\n`secure` and `free` do not change when the door opens. They are about whether the door is\nenforcing access control, not about the current state of the door hardware.\n\nWhen allowing passage, a door normally moves from closed and locked to closed and unlocked, to\nopen and unlocked (extremely briefly), then to open and locked while someone is walking through\nit, then back to closed and locked. It will be secure throughout.\n\n### Door flag rules\n\n- If and only if the door is online, exactly one of 'closed' or 'open' will appear, and one of\n 'locked' or 'unlocked', and one of 'secure' or 'free'.\n\nSo, to establish if the door is in a normal state, look for 'closed' or 'open'. If neither is\npresent, your door is in an error state.\n\n## Use cases\n\n### Listing Doors\n1. `GET /api`.\n2. Follow the link at `features.doors.doors.href`, appending a search term such as\n `name=substring` to filter the selection if you have a lot of doors, and `fields` to tell the\n server what to return about each. The next section covers those query parameters.\n3. Process the results, following the `next` link until there isn't one.\n\n### Overriding a door open\n1. Find the href for the door using the process above.\n2. GET it.\n3. POST to the `open` [↪](doors#post-api-doors-id-open) URL in the `commands` structure\n of the [results](models#doordetail).\n\n### Finding a door's status\n1. Find the href for the door using the process above, and GET it.\n3. Follow the `updates` href from that page.\n4. Use the flag rules above to interpret the status flags you receive.\n5. Follow the `next` link to stay up to date.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status. In\n8.50 and older, the GET will fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both."}],"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":{"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An internal identifier."},"updates_fields":{"name":"fields","in":"query","required":false,"style":"form","explode":false,"description":"This instructs the server to return these fields in the update, instead of the default set.\nYou will not hear about updates to fields you do not list.\n","schema":{"type":"string","enum":["status","statusText","statusFlags"]}}},"responses":{"403nolicence":{"description":"A server running 8.50 or earlier is missing the RESTStatus licence. A server running 8.60\nor later is missing both the RESTStatus and RESTOverrides licences. One of those is enough\nfor this API call in 8.60 and later.\n"},"404door":{"description":"The request's URL does not represent a door, or the operator does not have a privilege on\nthe door's division that allows viewing them, such as 'View Site', 'Edit Site', or 'Override\n- Open Door'.\n"}}},"paths":{"/api/doors/{id}/updates":{"get":{"tags":["Doors"],"summary":"Monitor a door","description":"See the [item status topic](item-status) for how to use the updates APIs.\n\nNote that this API call is good for watching one item only; if you want to monitor several,\nyou are better off with a [status subscription](items#status-subscriptions).\n\nFollow the 'updates' field in a door [summary](models#doorsummary) or\n[details](models#doordetail) page to get here.\n","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/updates_fields"}],"responses":{"200":{"description":"Success. See the [introduction](doors) for a description of the three status\nfields.\n","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"$ref":"#/components/responses/403nolicence"},"404":{"$ref":"#/components/responses/404door"}}}}}}
```
---
# 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/doors.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.