API Overview

Base URL & Environments

The StackFlow REST API is served from your instance subdomain under the prod API Gateway stage. Replace <your-instance> with your organization's StackFlow subdomain.

Architecture

All API requests flow through CloudFront (distribution E1UTZ9SVSR2WGV) to API Gateway (uazcuhdus2), which invokes the StackFlowAPI Lambda function. The Lambda runs Node.js 22.x on ARM64 with 1792 MB RAM and a 300-second timeout. It connects to Aurora PostgreSQL 16 for ITSM data, Amazon Neptune for CMDB graph queries, and ElastiCache Redis for caching.

Client Request
    │
    ▼
CloudFront (E1UTZ9SVSR2WGV) ← WAF: OWASP rules + rate limiting
    │
    ▼
API Gateway (uazcuhdus2, stage: prod)
    │  Throttle: 5000 burst / 5000 rate per second
    ▼
Lambda Authorizer ← validates Cognito JWT
    │
    ▼
StackFlowAPI Lambda (nodejs22.x, arm64, 1792MB)
    ├── Aurora PostgreSQL 16 (ITSM data)
    ├── Neptune (CMDB graph)
    ├── ElastiCache Redis (cache / semantic cache)
    └── Bedrock (AI endpoints)

API Versioning

The current API version is v1, embedded in the URL path as /prod/api/v1/... for versioned resources. The legacy unversioned paths (/prod/api/incidents) remain active and map to v1. Breaking changes will be introduced under a new version prefix with a 6-month deprecation notice.

Authentication Summary

Every API request (except /health) requires a valid Cognito ID token in the Authorization header. Use the ID token, not the access token — the ID token carries the user's role claims that StackFlow's authorizer validates.

Authorization: Bearer <id_token>

See the Authentication page for full details on obtaining and refreshing tokens. Service accounts and CI/CD pipelines should use the OAuth 2.0 client credentials flow with an API key header.

Request Format

All request bodies must be JSON with Content-Type: application/json. Query parameters use standard URL encoding. Field names follow snake_case convention. All timestamps must be ISO 8601 UTC (e.g., 2026-05-19T14:30:00Z).

curl -X POST https://<your-instance>.stackflow-tech.com/prod/api/incidents   -H "Authorization: Bearer $ID_TOKEN"   -H "Content-Type: application/json"   -d '{
    "short_description": "Database timeout in prod",
    "priority": "P2",
    "category": "database"
  }'

Response Format

Successful responses return HTTP 200 or 201 with a JSON body. Single-resource responses return the object directly. List responses are wrapped in a pagination envelope. Error responses always include error, code, and requestId fields.

// Single resource
{
  "id": "INC0001234",
  "short_description": "Database timeout in prod",
  "priority": "P2",
  "state": "new",
  "created_at": "2026-05-19T14:30:00Z"
}

// Error response
{
  "error": "Incident not found",
  "code": "RESOURCE_NOT_FOUND",
  "requestId": "7f3a1c2d-8e9b-4f0a-b1c2-d3e4f5a6b7c8"
}

Pagination

All list endpoints support cursor-based and offset-based pagination. Use ?page=1&limit=50 for offset pagination. The response envelope includes total, page, limit, and has_more fields.

GET /prod/api/incidents?page=2&limit=25&state=new&priority=P1

# Response envelope:
{
  "data": [...],
  "total": 342,
  "page": 2,
  "limit": 25,
  "has_more": true
}

Health Check

The health endpoint is unauthenticated and returns the API status. Use it for uptime monitoring and load balancer health checks.

curl https://<your-instance>.stackflow-tech.com/prod/api/health

# Response:
{"status":"healthy","version":"2026.1","region":"us-east-1"}