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

# Health Monitoring

> Integration health states and how Seyaha responds to connectivity issues.

Seyaha periodically probes your OCTO endpoint to verify connectivity and authentication.
The result is stored in the integration's `health` object.

## Health states

```
HEALTHY ──(failures start)──▶ DEGRADED ──(threshold reached)──▶ DOWN
   ▲                               │                                │
   └───────────(recovers)──────────┘◀──────(probe succeeds)────────┘
```

| Status     | Meaning                                        | Activity syncs                          |
| ---------- | ---------------------------------------------- | --------------------------------------- |
| `HEALTHY`  | All recent probes succeeded                    | Running normally                        |
| `DEGRADED` | Some recent probes failed — monitoring closely | Still running                           |
| `DOWN`     | Consecutive failure threshold exceeded         | **Paused** — activities marked inactive |

<Note>
  When an integration recovers from `DOWN` to `HEALTHY`, Seyaha automatically triggers
  a full sync and restores all affected activities to active status.
</Note>

## Checking health status

Partners can query their own integration; admins can query any:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.seyaha.net/api/v1/partner-integrations/$INTEGRATION_ID/health" \
    -H "Authorization: Bearer $PARTNER_JWT"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    `https://api.seyaha.net/api/v1/partner-integrations/${integrationId}/health`,
    { headers: { 'Authorization': `Bearer ${partnerJwt}` } }
  );
  const { data } = await res.json();
  console.log(data.status, data.last_probe_at);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": 1,
  "data": {
    "status": "HEALTHY",
    "last_probe_at": "2026-06-23T08:00:00.000Z"
  }
}
```

## Full health fields (via sync-log or admin list)

The full `health` object (returned in the complete integration document) includes:

| Field                  | Type                          | Description                           |
| ---------------------- | ----------------------------- | ------------------------------------- |
| `status`               | `HEALTHY \| DEGRADED \| DOWN` | Current state                         |
| `last_probe_at`        | date                          | When the last probe ran               |
| `last_success_at`      | date                          | When the last successful probe ran    |
| `consecutive_failures` | integer                       | Rolling count of failed probes        |
| `degraded_since`       | date                          | When the integration entered DEGRADED |
| `down_since`           | date                          | When the integration entered DOWN     |

## Troubleshooting

If your integration enters DEGRADED or DOWN:

1. Check that `base_url` is reachable from the internet (not just localhost or VPN)
2. Verify `auth_key` is still valid and hasn't expired
3. Ensure `GET {base_url}/products` returns a 200 — probe failures on any non-200 response
4. Call `POST /me/test-connection` for an on-demand diagnostic

If you update `auth_key` after a rotation, call `PATCH /me` to push the new credential:

```bash cURL theme={null}
curl -X PATCH https://api.seyaha.net/api/v1/partner-integrations/me \
  -H "Authorization: Bearer $PARTNER_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "auth_key": "new_rotated_key" }'
```