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

# Health Check

> Unauthenticated liveness and readiness endpoints for monitoring Signa from your side

## Overview

Three unauthenticated endpoints support customer-side uptime monitoring:

| Endpoint            | Purpose                                                     | Typical latency |
| ------------------- | ----------------------------------------------------------- | --------------- |
| `GET /v1/health`    | Liveness alias under the `/v1` prefix.                      | Under 5 ms      |
| `GET /health/live`  | Liveness: the process is up.                                | Under 5 ms      |
| `GET /health/ready` | Readiness: database, cache, and search index are reachable. | 50-200 ms       |

`/v1/health` and `/health/live` are aliases: both return `{ "status": "ok" }` with HTTP 200 whenever the API process is alive. `/health/ready` runs three real dependency checks and returns per-dependency status and latency.

None of the three require an API key or count against any quota or rate limit.

## Suggested poll interval

**60 seconds.** More frequent polling adds noise without improving signal.

## Response: `GET /v1/health` (and `/health/live`)

```json theme={null}
{ "status": "ok" }
```

Always 200 if the process is running. If the process is down you get a connection error or a 5xx from the load balancer instead.

## Response: `GET /health/ready`

<ResponseField name="status" type="string">
  One of:

  * `ok`: all three dependencies reachable.
  * `degraded`: a non-critical dependency (cache or search index) is down. The API still serves most requests; some features (search, rate-limit headers) may error individually.
  * `unhealthy`: the database is unreachable. The API cannot serve most requests. Returns HTTP 503.
  * `shutting_down`: the task is draining for a graceful stop. Returns HTTP 503 so load balancers route around it.
</ResponseField>

<ResponseField name="service" type="string">Always `"core-api"`.</ResponseField>
<ResponseField name="uptime_ms" type="integer">Process uptime in milliseconds.</ResponseField>

<ResponseField name="dependencies" type="object">
  <Expandable title="dependencies">
    <ResponseField name="postgres" type="object">
      <Expandable title="postgres">
        <ResponseField name="status" type="string">`ok` or `error`.</ResponseField>
        <ResponseField name="latency_ms" type="integer">Probe latency in ms (omitted on error).</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="valkey" type="object">
      <Expandable title="valkey">
        <ResponseField name="status" type="string">`ok` or `error`.</ResponseField>
        <ResponseField name="latency_ms" type="integer">Probe latency in ms (omitted on error).</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="opensearch" type="object">
      <Expandable title="opensearch">
        <ResponseField name="status" type="string">`ok` or `error`.</ResponseField>
        <ResponseField name="latency_ms" type="integer">Probe latency in ms (omitted on error).</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## What this endpoint does not cover

`/health/ready` reflects API, database, cache, and search readiness. It does not reflect:

* **Alert delivery.** If your watches stop firing alerts but `/health/ready` is `ok`, that's a sign of a data-sync or evaluation issue, not an API outage. See [Troubleshooting](/guides/monitoring/troubleshooting).
* **A specific office's data freshness** (e.g. USPTO). Poll [`GET /v1/offices`](/api-reference/reference/list-offices) and check each office's last successful sync instead.
* **Your webhook receiver.** That's on your side by definition.

## Examples

<RequestExample>
  ```bash cURL theme={null}
  # Liveness alias under /v1
  curl https://api.signa.so/v1/health
  # -> {"status":"ok"}

  # Readiness: what your monitoring agent should hit every 60s
  curl https://api.signa.so/health/ready
  # -> {"status":"ok","service":"core-api","uptime_ms":12345,"dependencies":{...}}
  ```

  ```ts TypeScript theme={null}
  // No SDK helper for this: these endpoints are unauthenticated, hit them with fetch.
  const res = await fetch('https://api.signa.so/health/ready');
  const ready = await res.json();
  if (ready.status !== 'ok') {
    alert(`Signa API ${ready.status}: postgres=${ready.dependencies.postgres.status}`);
  }
  ```
</RequestExample>

## See also

* [Troubleshooting](/guides/monitoring/troubleshooting): what to check when alerts stop firing despite `/health/ready` being `ok`.
* [List Offices](/api-reference/reference/list-offices): per-office sync freshness.