> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guardhousehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> REST API for incident reports, live operations, timesheets, staff, customers, sites, and webhooks.

The Guardhouse API gives external systems programmatic access to your incident reports,
live operations, timesheets, staff, customers, sites, and webhook event subscriptions. It is a JSON REST API
over HTTPS, secured with short-lived JWT bearer tokens that you obtain by exchanging an API key.

## Base URLs

Use the base URL for your Guardhouse region:

| Region | Base URL                                 |
| ------ | ---------------------------------------- |
| AU     | `https://gateway-api.guardhousehq.com`   |
| UK     | `https://gateway-api.guardhousehq.co.uk` |

## Authentication

All read endpoints expect a JWT bearer token sent as `Authorization: Bearer <token>`.
Authentication is a two-step flow:

**1. Obtain a token** — POST your API key to `POST /api/external/token/request`:

```http theme={null}
POST /api/external/token/request
Content-Type: application/json

{
  "apiKey": "your-api-key-here"
}
```

A successful response returns an `accessToken` valid for **60 minutes**:

```json theme={null}
{
  "status": { "code": 0, "errorMessage": "" },
  "data": {
    "accessToken": "<jwt>",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  }
}
```

**2. Send the token** — include it as a bearer token on every subsequent request:

```http theme={null}
Authorization: Bearer <accessToken>
```

Re-issue a new token before it expires — there is no refresh mechanism.

### Generating an API key

API keys are generated inside the Guardhouse web app. You need **SuperAdmin** access to do this.

1. Log in to the Guardhouse web app.
2. Go to **Organization → Company Settings**.
3. Open the **Guardhouse API & Integrations** tab.
4. Select the **Guardhouse API** sub-tab.
5. Find the API type you need and click **Generate API Key**:

| API type               | `KeyType`        | Grants access to                                      |
| ---------------------- | ---------------- | ----------------------------------------------------- |
| Developer API          | `developer`      | Webhook subscriptions, staff, and developer endpoints |
| Live Operations API    | `liveops`        | Live Operations endpoint                              |
| Incident Reporting API | `incidentreport` | Incident report endpoints                             |
| Timesheet API          | `timesheet`      | Timesheet endpoints                                   |

The generated key is shown immediately in the field next to the button. Copy and store it securely — it is not shown again after you navigate away.

## Request headers

Every API request requires two headers:

| Header                     | Value                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `Authorization`            | `Bearer <accessToken>` — JWT obtained from `POST /api/external/token/request`                    |
| `external-gh-apim-sub-key` | Guardhouse API Management subscription key — contact Guardhouse Support for the subscription key |

## Scopes and key types

Every API key is issued with a `KeyType` that controls which endpoints it can call:

| `KeyType`        | Endpoints                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| `incidentreport` | All `/api/external/incidentreport*` and `/api/external/incidentreports/*` endpoints                    |
| `liveops`        | Live Operations endpoint                                                                               |
| `developer`      | All `/api/webhook/*` endpoints and all `/api/external/staffs*` endpoints                               |
| `timesheet`      | `/api/external/timesheets`, `/api/external/timesheets/{id}`, and `/api/external/timesheets/{id}/rates` |

All Staff endpoints (`/api/external/staffs*`) require a `developer` API key. The remaining
read endpoints (`/api/external/customers`, `/api/external/sites`) require any authenticated
`Public` key.
All are scoped by your `CompanyId`, `CustomerId`, and `SiteId` claims.

Calling an endpoint with the wrong `KeyType` returns `403 Forbidden`. Keys are also scoped
by `CompanyId`, `CustomerId`, and `SiteId` claims — passing IDs outside that scope is also
rejected with `403`.

## Response envelope

Every JSON endpoint returns the same wrapper:

```json theme={null}
{
  "status": { "code": 0, "errorMessage": "" },
  "data":   { /* endpoint payload */ },
  "count":  null,
  "message": "",
  "errors": []
}
```

Paginated incident-report endpoints add full cursor metadata:

```json theme={null}
{
  "status":            { "code": 0, "errorMessage": "" },
  "data":              [ /* items */ ],
  "recordCount":       100,
  "totalRecordCount":  4823,
  "prevPageEndpoint":  null,
  "prevPageParams":    null,
  "nextPageEndpoint":  "/api/external/incidentreports/getall",
  "nextPageParams":    "direction=next&referenceId=8429"
}
```

The newer paginated endpoints (`/api/external/timesheets`, `/api/external/staffs`,
`/api/external/customers`, `/api/external/sites`) use a slimmer cursor envelope:

```json theme={null}
{
  "status":             { "code": 0, "errorMessage": "" },
  "data":               [ /* items */ ],
  "nextPageParameter":  "direction=next&referenceId=8429",
  "prevPageParameter":  null
}
```

The Live Operations endpoint uses its own envelope with `isSuccess`, numeric `status`,
`statusMessage`, `errorMessages`, and `errorMessagesAsString` fields.

See the [Errors guide](/api-reference/errors) for the meaning of `status.code` and the
shape of the `errors` array.

## Pagination

List endpoints use cursor-based pagination. To page forward:

1. Issue the initial request with `direction=next` (the default).
2. Read the last item's identifier from `data` (typically `incidentReportId`).
3. Pass that value as `referenceId` on the next request, keeping `direction=next`.

To page backward, set `direction=prev` and pass `referenceId` from the first item.

The response's `nextPageParams` and `prevPageParams` give you the exact query string to use
for the next call — you can append them directly to the endpoint URL.

## Rate limits

External and webhook endpoints are limited to **60 requests per minute** per API key.
Requests beyond the limit return `429 Too Many Requests`. The token-issuance endpoints
(`/api/token/*`) are not rate-limited.

## Webhooks

If your `KeyType=developer` key is provisioned, you can register subscribers and event
subscriptions so Guardhouse pushes notifications to your systems when reports or
timesheets change. See the [Webhooks guide](/api-reference/webhooks) for the registration
flow, signature validation, and the supported event catalog.