REST Endpoints

While AIQLick is primarily a GraphQL-based platform, several REST endpoints are exposed for health monitoring, webhook integration, and operational control.

Backend REST Endpoints

Base URL: https://api.aiqlick.com (production) | https://api-dev.aiqlick.com (development)

Health Checks

Endpoint	Method	Auth	Description
/health	GET	None	Liveness check. Returns 200 OK if the process is running.
/healthz	GET	None	ALB health check endpoint. Used by AWS infrastructure for load balancer target health.

Example request:

curl https://api.aiqlick.com/health

Example response (200 OK):

{
  "status": "ok"
}

Stripe Webhook

Endpoint	Method	Auth	Description
/stripe/webhook	POST	Stripe signature	Receives Stripe webhook events for payment processing.

This endpoint validates the incoming request using the STRIPE_WEBHOOK_SECRET environment variable. It processes events including:

• checkout.session.completed -- Subscription activation and credit pack purchases
• invoice.paid -- Recurring subscription payments
• invoice.payment_failed -- Failed payment handling
• customer.subscription.updated -- Plan changes
• customer.subscription.deleted -- Subscription cancellations

Signature verification: Stripe signs each webhook payload with a secret. The Backend verifies this signature before processing any event. Requests without a valid signature are rejected with a 400 Bad Request response.

AI Service REST Endpoints

Base URL: https://ai.aiqlick.com (production) | https://ai-dev.aiqlick.com (development)

Health Checks

Endpoint	Method	Auth	Description
/health	GET	None	Liveness check. Returns 200 OK if the process is running.
/health/ready	GET	None	Readiness check. Returns component-level status including database, workers, and circuit breakers.
/docs	GET	None	Swagger/OpenAPI interactive documentation for all REST endpoints.

Liveness check (/health):

curl https://ai.aiqlick.com/health

{
  "status": "healthy"
}

Readiness check (/health/ready):

curl https://ai.aiqlick.com/health/ready

{
  "status": "healthy",
  "components": {
    "database": {
      "status": "healthy",
      "latency_ms": 2.4
    },
    "workers": {
      "status": "healthy",
      "active": 4,
      "idle": 12
    },
    "circuit_breakers": {
      "bedrock": "closed",
      "rekognition": "closed",
      "transcribe": "closed"
    }
  }
}

The readiness endpoint reports on three component categories:

• Database: Connection pool health and query latency to PostgreSQL.
• Workers: Status of async worker processes handling AI operations.
• Circuit breakers: State of circuit breakers protecting external AWS service calls. States are closed (healthy), open (failing, requests blocked), or half-open (testing recovery).

Jitsi Event Webhooks

Endpoint	Method	Auth	Description
/api/events/room/created	POST	Internal	Receives room creation events from the Jitsi Prosody server.
/api/events/room/destroyed	POST	Internal	Receives room destruction events from the Jitsi Prosody server.

These endpoints are called by the Prosody XMPP server (running on the Jitsi EC2 instance) when meeting lifecycle events occur. Room creation and destruction events trigger automated workflows such as meeting insight generation.

Example payload (room created):

{
  "event": "room_created",
  "room": "meeting-room-name",
  "timestamp": "2025-01-15T10:30:00Z"
}

Example payload (room destroyed):

{
  "event": "room_destroyed",
  "room": "meeting-room-name",
  "timestamp": "2025-01-15T11:00:00Z"
}

Additional Health Endpoints

Endpoint	Method	Auth	Description
/health/database	GET	None	Database-specific health check. Verifies PostgreSQL connectivity and pool status.
/health/live	GET	None	Liveness probe (static, always 200 if the process is running).

Monitoring Endpoints

Endpoint	Method	Auth	Description
/monitoring/stats	GET	Internal	Overall system statistics and resource usage.
/monitoring/operations	GET	Internal	AI operation counts and status summary.
/monitoring/app-logs	GET	Internal	Application log viewer with filtering.
/monitoring/errors	GET	Internal	Recent error log entries.
/monitoring/ai-services	GET	Internal	Status of external AI service integrations (Bedrock, Rekognition, Transcribe).

Match Score Generator

The match score generator is a background process that calculates compatibility scores between talents and jobs. These endpoints provide operational control.

Endpoint	Method	Auth	Description
/api/v1/background-tasks/match-score-generator/status	GET	Internal	Returns the current state of the generator (running, stopped, processing).
/api/v1/background-tasks/match-score-generator/start	POST	Internal	Starts the match score generator process.
/api/v1/background-tasks/match-score-generator/stop	POST	Internal	Gracefully stops the generator after completing the current batch.
/api/v1/background-tasks/match-score-generator/metrics	GET	Internal	Returns processing metrics including throughput and queue depth.

Status response:

curl https://ai.aiqlick.com/api/v1/background-tasks/match-score-generator/status

{
  "status": "running",
  "uptime_seconds": 3600,
  "current_batch": 42,
  "queue_size": 156
}

Metrics response:

curl https://ai.aiqlick.com/api/v1/background-tasks/match-score-generator/metrics

{
  "total_processed": 12450,
  "total_errors": 23,
  "avg_processing_time_ms": 850,
  "queue_depth": 156,
  "throughput_per_minute": 71.2,
  "last_processed_at": "2025-01-15T10:29:45Z"
}

OpenAPI Documentation

The AI Service provides interactive API documentation via Swagger UI at the /docs endpoint:

https://ai.aiqlick.com/docs

This page documents all REST endpoints with request/response schemas, and allows direct testing of API calls from the browser.

Health Check Usage in CI/CD

Health check endpoints play a critical role in the deployment pipeline:

Backend Deployment

After deploying a new container image, the CI/CD pipeline:

1. Waits for the container to start.
2. Polls /health until it returns 200 OK.
3. Sends a GraphQL introspection query to /graphql to verify the schema loaded correctly.
4. Marks the deployment as successful or triggers a rollback.

AI Service Deployment

After deploying a new container image, the CI/CD pipeline:

1. Waits for the container to start.
2. Polls /health for liveness.
3. Polls /health/ready to confirm all components (database, workers, circuit breakers) are healthy.
4. On failure, automatically rolls back to the :previous Docker image tag.

Jitsi Deployment

The Jitsi deployment verifies that https://book.aiqlick.com/ returns a successful HTTP response after restarting containers.

Endpoint Summary

Service	Endpoint	Method	Purpose
Backend	/health	GET	Health check (DB + Redis connectivity)
Backend	/healthz	GET	ALB health check
Backend	/stripe/webhook	POST	Stripe event receiver
AI Service	/health	GET	Liveness check
AI Service	/health/ready	GET	Readiness with component status
AI Service	/health/database	GET	Database connectivity check
AI Service	/health/live	GET	Liveness probe (static)
AI Service	/docs	GET	Swagger/OpenAPI documentation
AI Service	/api/events/room/created	POST	Prosody room created webhook
AI Service	/api/events/room/destroyed	POST	Prosody room destroyed webhook
AI Service	/monitoring/stats	GET	System statistics
AI Service	/monitoring/operations	GET	AI operation summary
AI Service	/monitoring/app-logs	GET	Application logs
AI Service	/monitoring/errors	GET	Error logs
AI Service	/monitoring/ai-services	GET	AI service status
AI Service	/api/v1/background-tasks/match-score-generator/status	GET	Generator status
AI Service	/api/v1/background-tasks/match-score-generator/start	POST	Start generator
AI Service	/api/v1/background-tasks/match-score-generator/stop	POST	Stop generator
AI Service	/api/v1/background-tasks/match-score-generator/metrics	GET	Processing metrics