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

# Health Check

The health check endpoint provides a quick way to verify that the KYC API service is running and responsive.

## Endpoint

```
GET /health
```

## Authentication

No authentication required. This endpoint is publicly accessible for monitoring purposes.

## Description

This endpoint performs a basic liveness check. It's suitable for:

* Service availability monitoring
* Integration health verification
* Uptime monitoring
* Deployment verification

## Request Example

```bash theme={null}
curl https://stg.kyc.legaltalent.ai/health
```

## Response Format

### Success Response

```json theme={null}
{
  "status": "ok",
  "service": "kyc-health",
  "check_type": "liveness",
  "timestamp": "2024-11-22T10:30:00Z",
  "cold_start": false,
  "function_name": "kyc-health-develop",
  "function_version": "$LATEST",
  "request_id": "abc-123-def"
}
```

## Response Fields

| Field              | Type    | Description                            |
| ------------------ | ------- | -------------------------------------- |
| `status`           | string  | Always `"ok"` when service is running  |
| `service`          | string  | Service identifier: `"kyc-health"`     |
| `check_type`       | string  | Type of check: `"liveness"`            |
| `timestamp`        | string  | ISO 8601 timestamp of the check        |
| `cold_start`       | boolean | `true` if this was a cold Lambda start |
| `function_name`    | string  | AWS Lambda function name               |
| `function_version` | string  | Lambda function version                |
| `request_id`       | string  | Unique request identifier              |

## Status Codes

| Code | Description                                                     |
| ---- | --------------------------------------------------------------- |
| 200  | Service is healthy and responding                               |
| 500  | Service is unavailable (should not occur if service is running) |

## Use Cases

### Load Balancer Configuration

Configure your load balancer to poll this endpoint:

```
Health Check URL: /health
Interval: 30 seconds
Timeout: 5 seconds
Healthy Threshold: 2
Unhealthy Threshold: 3
```

### Monitoring Integration

Use this endpoint with monitoring tools:

```bash theme={null}
# Example monitoring script
while true; do
  response=$(curl -s -o /dev/null -w "%{http_code}" https://stg.kyc.legaltalent.ai/health)
  if [ "$response" != "200" ]; then
    echo "Health check failed: HTTP $response"
    # Send alert
  fi
  sleep 60
done
```

### Deployment Verification

After integration, verify the service is accessible:

```bash theme={null}
curl -f https://stg.kyc.legaltalent.ai/health || echo "Service unavailable"
```

## Readiness Check

The readiness endpoint performs a deeper health check that verifies dependencies (S3, DynamoDB) are accessible.

### Endpoint

```
GET /health/ready
```

### Authentication

Requires `health:readiness_check` permission. Include your Bearer token in the Authorization header.

### Description

This endpoint performs a readiness check that verifies:

* S3 bucket accessibility (watchlist snapshots)
* DynamoDB table accessibility (watchlists)
* Overall service readiness

Use this endpoint for:

* Pre-deployment verification
* Dependency health monitoring
* Service readiness confirmation

### Request Example

```bash theme={null}
curl https://stg.kyc.legaltalent.ai/health/ready \
    -H "Authorization: Bearer YOUR_TOKEN"
```

### Response Format

```json theme={null}
{
  "status": "healthy",
  "service": "kyc-health",
  "check_type": "readiness",
  "timestamp": "2024-11-22T10:30:00Z",
  "cold_start": false,
  "dependencies": {
    "s3": {
      "status": "healthy",
      "service": "s3",
      "bucket": "kyc-watchlists-snapshots-develop",
      "message": "S3 bucket accessible"
    },
    "dynamodb": {
      "status": "healthy",
      "service": "dynamodb",
      "table": "kyc-watchlists-develop",
      "message": "DynamoDB table accessible"
    }
  },
  "function_name": "kyc-health-develop",
  "function_version": "$LATEST",
  "request_id": "abc-123-def"
}
```

### Degraded Status Response

If any dependency is unhealthy, the overall status will be `"degraded"`:

```json theme={null}
{
  "status": "degraded",
  "service": "kyc-health",
  "check_type": "readiness",
  "timestamp": "2024-11-22T10:30:00Z",
  "dependencies": {
    "s3": {
      "status": "healthy",
      "service": "s3",
      "bucket": "kyc-watchlists-snapshots-develop",
      "message": "S3 bucket accessible"
    },
    "dynamodb": {
      "status": "unhealthy",
      "service": "dynamodb",
      "table": "kyc-watchlists-develop",
      "error": "ResourceNotFoundException",
      "message": "DynamoDB table not accessible: ResourceNotFoundException"
    }
  }
}
```

### Response Fields

| Field          | Type    | Description                                 |
| -------------- | ------- | ------------------------------------------- |
| `status`       | string  | Overall status: `"healthy"` or `"degraded"` |
| `service`      | string  | Service identifier: `"kyc-health"`          |
| `check_type`   | string  | Type of check: `"readiness"`                |
| `timestamp`    | string  | ISO 8601 timestamp of the check             |
| `cold_start`   | boolean | `true` if this was a cold Lambda start      |
| `dependencies` | object  | Status of each dependency (S3, DynamoDB)    |

### Dependency Status Fields

Each dependency includes:

| Field     | Type   | Description                            |
| --------- | ------ | -------------------------------------- |
| `status`  | string | `"healthy"` or `"unhealthy"`           |
| `service` | string | Service name (`"s3"` or `"dynamodb"`)  |
| `message` | string | Human-readable status message          |
| `error`   | string | Error code (only present if unhealthy) |

### Status Codes

| Code | Description                                             |
| ---- | ------------------------------------------------------- |
| 200  | Readiness check completed (may be healthy or degraded)  |
| 403  | Forbidden - Missing `health:readiness_check` permission |
| 401  | Unauthorized - Missing or invalid token                 |

### Use Cases

#### Pre-Deployment Verification

```bash theme={null}
# Verify service is ready before deployment
curl -f https://stg.kyc.legaltalent.ai/health/ready \
  -H "Authorization: Bearer YOUR_TOKEN" || exit 1
```

#### Monitoring Integration

```bash theme={null}
# Check readiness in monitoring script
response=$(curl -s https://stg.kyc.legaltalent.ai/health/ready \
  -H "Authorization: Bearer YOUR_TOKEN")
status=$(echo $response | jq -r '.status')

if [ "$status" != "healthy" ]; then
  echo "Service degraded: $response"
  # Send alert
fi
```

## Implementation Notes

* **No Caching**: Each request performs a fresh check
* **Public Access**: `/health` endpoint requires no authentication (by design for monitoring)
* **Authenticated Access**: `/health/ready` requires `health:readiness_check` permission
* **Always Available**: Returns 200 OK when the service is operational (status may be healthy or degraded)