> 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/rest-clients.md).
# REST Clients
This lets you operate on the REST Client item that represents your application in Command Centre. You can send a description of the state of your application and raise an alarm if it is in strife.
***This is still in development and may change behaviour before release.***
### REST Client status flags
* `offline` means the item is configured with a keepalive time and it has not seen an API request in that time.
* `faulty` means the item has used the endpoint in this section to declare itself in trouble.
Because this feature is intended for REST integrations needing to indicate their status, this API is the only way to change a REST Client item's status fields. Humans using Gallagher's operational and configuration clients can see it but not change it.
## Set status
> This allows an integration to add a string to the status text of the REST Client item that\
> represents your application. That text is visible on a suitably-configured site plan or a\
> Monitor Site viewer in Gallagher's operational client, or any other client that is watching\
> items.\
> \
> Your integration can also set a flag indicating that it is in a fault condition and requires\
> attention. Doing that will raise an alarm, hopefully provoking a response from an operator.\
> The alarm is stateful, restored only by your integration clearing the flag later when it is\
> back in working order.\
> \
> A client can change its own status, but it can change no other's, and no other client can\
> change its.\
> \
> Your client's operator does not need any privileges for this call.\
> \
> Do not code this URL into your application. Take it from \`me.client.href\` in the results of\
> \`GET /api\`.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"REST Clients","description":"This lets you operate on the REST Client item that represents your application in Command\nCentre. You can send a description of the state of your application and raise an alarm if it is\nin strife.\n\n***This is still in development and may change behaviour before release.***\n\n## REST Client status flags\n\n- `offline` means the item is configured with a keepalive time and it has not seen an API\nrequest in that time.\n\n- `faulty` means the item has used the endpoint in this section to declare itself in trouble.\n\nBecause this feature is intended for REST integrations needing to indicate their status, this\nAPI is the only way to change a REST Client item's status fields. Humans using Gallagher's\noperational and configuration clients can see it but not change it.\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":{"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An internal identifier."}}},"paths":{"/api/items/{id}":{"patch":{"tags":["REST Clients"],"summary":"Set status","description":"This allows an integration to add a string to the status text of the REST Client item that\nrepresents your application. That text is visible on a suitably-configured site plan or a\nMonitor Site viewer in Gallagher's operational client, or any other client that is watching\nitems.\n\nYour integration can also set a flag indicating that it is in a fault condition and requires\nattention. Doing that will raise an alarm, hopefully provoking a response from an operator.\nThe alarm is stateful, restored only by your integration clearing the flag later when it is\nback in working order.\n\nA client can change its own status, but it can change no other's, and no other client can\nchange its.\n\nYour client's operator does not need any privileges for this call.\n\nDo not code this URL into your application. Take it from `me.client.href` in the results of\n`GET /api`.\n","parameters":[{"$ref":"#/components/parameters/id"}],"requestBody":{"description":"The status text and fault condition of your API client.\n\nBoth fields are optional.\n","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hasFault":{"type":"boolean","description":"If true, the server will change the status of this REST Client to include an\nindication that it has a fault, and will raise an active alarm to draw the\noperators' attention. Being active, operators will not be able to process that\nalarm until you restore it by passing false here.\n"},"customStatusText":{"type":"string","maxLength":1024,"description":"The server will include the text you supply here whenever it generates status\ntext for this item.\n\nThis text field works independently of the item's other states and its fault\nflag: you can use it purely for information.\n\nThe integrator is responsible for any personally identifiable information sent\nto Command Centre via the API.\n"}}}}}},"responses":{"200":{"description":"Success. The server has feedback for you in the body of its response.\n"},"204":{"description":"Success."},"400":{"description":"The server could not make sense of your payload. Its response will contain feedback.\n"},"403":{"description":"You PATCHed the URL of a REST Client item, but not _your_ REST Client item.\n"},"404":{"description":"That is not the URL of a REST Client item your operator can see."}}}}}}
```
---
# 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/rest-clients.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.