API (Public) Runbook
The Phenom public API gateway combining Hasura GraphQL and Auth services, deployed on AWS App Runner or behind an ALB.
Source:
asset-registry.yaml; curl https://api.thephenom.app/healthz → HTTP 500 (service degraded); Cognito pool us-east-1_knEL7cqS3 confirmed; deployment topology pending App Runner vs ALB confirmation
C2PA signed · SanMarcSoft AI content credential
What it is
api.thephenom.app is the public-facing API for the Phenom platform, combining Hasura GraphQL and authentication services. It is the primary backend consumed by the NEST application and any third-party integrations. All database reads and writes, user auth flows, and data queries route through this service. Downtime here is a P0 incident that renders NEST non-functional.
Deployment chain
| Layer | Value |
|---|---|
| URL | https://api.thephenom.app |
| DNS | Cloudflare (proxied, orange-cloud) |
| Hosting | AWS App Runner or Application Load Balancer (ALB) |
| Services | Hasura GraphQL engine + Auth service |
| Region | us-east-1 |
| AWS profile | phenom |
| Database | phenom-prod-postgres (RDS PostgreSQL, us-east-1) |
| Auth | AWS Cognito pool us-east-1_knEL7cqS3 |
Verify exact hosting (App Runner vs ALB+ECS) in the AWS console; both configurations are used in the Phenom stack.
Common operations
Check Hasura health
curl -sf https://api.thephenom.app/healthz
# Expected: "OK" or JSON {"status":"OK"}
Restart service (App Runner)
SERVICE_ARN=$(aws apprunner list-services \
--profile phenom --region us-east-1 \
--query 'ServiceSummaryList[?contains(ServiceName,`api`)].ServiceArn' \
--output text)
aws apprunner start-deployment \
--service-arn "$SERVICE_ARN" \
--profile phenom \
--region us-east-1
Restart service (ECS Fargate)
aws ecs update-service \
--cluster phenom-prod-cluster \
--service phenom-api \
--force-new-deployment \
--profile phenom \
--region us-east-1
aws ecs wait services-stable \
--cluster phenom-prod-cluster \
--services phenom-api \
--profile phenom \
--region us-east-1
View recent logs
# App Runner:
aws logs tail /aws/apprunner/phenom-api \
--follow \
--profile phenom \
--region us-east-1
# ECS:
aws logs tail /ecs/phenom-api \
--follow \
--profile phenom \
--region us-east-1
Run a test GraphQL query
curl -sf -X POST https://api.thephenom.app/v1/graphql \
-H "Content-Type: application/json" \
-d '{"query":"{ __typename }"}' | python3 -m json.tool
# Expected: {"data":{"__typename":"query_root"}}
Apply Hasura metadata / migrations
# From the Phenom-Backend repo:
cd hasura/
hasura metadata apply --endpoint https://api.thephenom.app \
--admin-secret "$HASURA_ADMIN_SECRET"
hasura migrate apply --endpoint https://api.thephenom.app \
--admin-secret "$HASURA_ADMIN_SECRET" \
--database-name default
Verify it is working
curl -si https://api.thephenom.app/healthz
# Expected: HTTP/2 200
curl -sf -X POST https://api.thephenom.app/v1/graphql \
-H "Content-Type: application/json" \
-d '{"query":"{ __typename }"}' | grep '__typename'
# Expected: line containing "__typename" in response JSON
Common failure modes
| Symptom | Likely cause | Remediation |
|---|---|---|
| 502 / 503 | Service crashed or App Runner unhealthy | Check CloudWatch logs; restart service |
| GraphQL errors: “relation does not exist” | Migration not applied | Run hasura migrate apply against the endpoint |
| Auth 401 on all requests | Cognito pool misconfigured or JWT secret wrong | Verify Hasura HASURA_GRAPHQL_JWT_SECRET env var matches Cognito pool |
| Slow queries | Missing indexes or RDS under load | Check RDS Performance Insights; optimize queries |
| Metadata out of sync | Hasura metadata not applied after schema change | Run hasura metadata apply |
| 429 too many requests | Rate limiting from Cloudflare or App Runner | Check CF rate limiting rules; scale App Runner concurrency |
Related
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.