GCO Global API Gateway — API spec sheet¶

API Gateway api-gateway-global · OpenAPI 3.0.3 · API version 1.0.0 · 14 endpoints · 0 schemas

Authenticated global aggregation API for GCO

The single authenticated entry point for GCO. Every request is signed with AWS SigV4 and authorized by IAM; the Lambda proxies behind the routes add the request-bound HMAC envelope that the in-cluster services require, so this API is the only supported caller of the cluster besides the regional bridges. /api/v1/{proxy+} and /inference/{proxy+} reach the regions over Global Accelerator; /api/v1/global/* fans out to every regional API Gateway; /studio/* exists only with the analytics environment.

• Machine-readable document: docs/openapi/api-gateway-global.json — the document scripts/generate_api_gateway_openapi.py reads out of the synthesized CDK stack; this sheet is rendered from it
• Interactive console (Swagger UI): https://aws-solutions-library-samples.github.io/global-capacity-orchestrator-on-aws/swagger/api-gateway-global/
• Catalogue index: README.md · interaction diagram

Servers¶

• https://{api_id}.execute-api.{region}.{url_suffix}/{stage}

Stage prod of the deployed REST API. The full URL is the ApiEndpoint output of the gco-api-gateway stack.

Deployment¶

• Endpoint type: EDGE
• Stage: prod — throttling 1000 req/s (burst 2000), execution logging INFO, data trace off, metrics on, X-Ray tracing on, access logs on
• Conditional routes: operations marked Only when exist under:
• analytics: Present only when analytics_environment.enabled is true in cdk.json.
• global-accelerator: Present only in the commercial aws partition, where Global Accelerator provides the data path to the regional ALBs. Elsewhere the global API keeps only its aggregate routes and workload traffic uses each region's bridge.

Resource policy¶

Statements deployed on the REST API (${AWS::AccountId} is the deploying account):

[
  {
    "Action": "execute-api:Invoke",
    "Condition": {
      "StringEquals": {
        "aws:PrincipalAccount": "${AWS::AccountId}"
      }
    },
    "Effect": "Allow",
    "Principal": {
      "AWS": "*"
    },
    "Resource": "execute-api:/*"
  },
  {
    "Action": "execute-api:Invoke",
    "Effect": "Allow",
    "Principal": {
      "AWS": "*"
    },
    "Resource": "execute-api:/*/GET/studio/*"
  }
]

WAF¶

Security schemes¶

cognito¶

• Type: apiKey — header Authorization (cognito_user_pools)

ID token issued by the Studio Cognito user pool, validated by the <project>-studio-cognito-authorizer authorizer.

sigv4¶

• Type: apiKey — header Authorization (awsSigv4)

AWS Signature Version 4 for service execute-api, signed with IAM credentials of the deploying account that carry execute-api:Invoke on this API (for example awscurl --service execute-api --region <region>).

Endpoints¶

Endpoint details¶

GET /api/v1/global/health¶

Fans out to /api/v1/health on every regional API Gateway and returns one health object per region.

• Operation ID: getApiV1GlobalHealth
• Tags: global
• Security: sigv4
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: cross-region-aggregator (lambda/cross-region-aggregator/handler.py; python3.14, handler.lambda_handler, 29 s timeout)
• Behaviour: Discovers every -regional-api- stack's RegionalApiEndpoint output, fans the request out to each regional API with SigV4 and merges the answers into one response.
• Then:
  1. Each region's API Gateway bridge, called with SigV4 by the aggregator's own execution role (GET/DELETE api/v1/jobs, GET api/v1/health, api/v1/status, api/v1/policy) — api-gateway-regional
  2. regional-api-proxy VPC Lambda: resolves the ALB from SSM //alb-hostname- and signs the HMAC envelope
  3. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  4. manifest-processor (catch-all and /api/v1/manifests) or health-monitor (/api/v1/health, /api/v1/metrics, /healthz) — manifest-processor, health-monitor

Responses

GET /api/v1/global/jobs¶

Fans out to /api/v1/jobs on every regional API Gateway and merges the results. Requires the regional bridges to be deployed; each region's answer is attributed to it in the response.

• Operation ID: getApiV1GlobalJobs
• Tags: global
• Security: sigv4
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: cross-region-aggregator (lambda/cross-region-aggregator/handler.py; python3.14, handler.lambda_handler, 29 s timeout)
• Behaviour: Discovers every -regional-api- stack's RegionalApiEndpoint output, fans the request out to each regional API with SigV4 and merges the answers into one response.
• Then:
  1. Each region's API Gateway bridge, called with SigV4 by the aggregator's own execution role (GET/DELETE api/v1/jobs, GET api/v1/health, api/v1/status, api/v1/policy) — api-gateway-regional
  2. regional-api-proxy VPC Lambda: resolves the ALB from SSM //alb-hostname- and signs the HMAC envelope
  3. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  4. manifest-processor (catch-all and /api/v1/manifests) or health-monitor (/api/v1/health, /api/v1/metrics, /healthz) — manifest-processor, health-monitor

Responses

DELETE /api/v1/global/jobs¶

Fans out to /api/v1/jobs on every regional API Gateway and merges the results. Requires the regional bridges to be deployed; each region's answer is attributed to it in the response.

• Operation ID: deleteApiV1GlobalJobs
• Tags: global
• Security: sigv4
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: cross-region-aggregator (lambda/cross-region-aggregator/handler.py; python3.14, handler.lambda_handler, 29 s timeout)
• Behaviour: Discovers every -regional-api- stack's RegionalApiEndpoint output, fans the request out to each regional API with SigV4 and merges the answers into one response.
• Then:
  1. Each region's API Gateway bridge, called with SigV4 by the aggregator's own execution role (GET/DELETE api/v1/jobs, GET api/v1/health, api/v1/status, api/v1/policy) — api-gateway-regional
  2. regional-api-proxy VPC Lambda: resolves the ALB from SSM //alb-hostname- and signs the HMAC envelope
  3. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  4. manifest-processor (catch-all and /api/v1/manifests) or health-monitor (/api/v1/health, /api/v1/metrics, /healthz) — manifest-processor, health-monitor

Responses

GET /api/v1/global/status¶

Fans out to /api/v1/status on every regional API Gateway (answered by the manifest-processor) and merges templates, webhooks, resource limits and allowed namespaces per region.

• Operation ID: getApiV1GlobalStatus
• Tags: global
• Security: sigv4
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: cross-region-aggregator (lambda/cross-region-aggregator/handler.py; python3.14, handler.lambda_handler, 29 s timeout)
• Behaviour: Discovers every -regional-api- stack's RegionalApiEndpoint output, fans the request out to each regional API with SigV4 and merges the answers into one response.
• Then:
  1. Each region's API Gateway bridge, called with SigV4 by the aggregator's own execution role (GET/DELETE api/v1/jobs, GET api/v1/health, api/v1/status, api/v1/policy) — api-gateway-regional
  2. regional-api-proxy VPC Lambda: resolves the ALB from SSM //alb-hostname- and signs the HMAC envelope
  3. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  4. manifest-processor (catch-all and /api/v1/manifests) or health-monitor (/api/v1/health, /api/v1/metrics, /healthz) — manifest-processor, health-monitor

Responses

GET /api/v1/{proxy+}¶

Catch-all for the control-plane API served by the in-cluster FastAPI services. {proxy+} is the rest of the path — for example jobs, jobs/{namespace}/{name}, manifests, health, status — so the operations available here are the /api/v1/* paths of the manifest-processor and health-monitor documents, minus /api/v1/global/*, which the aggregator serves. The request is forwarded unchanged (the stage prefix is not part of the backend path); the response is returned unchanged.

Only when: Present only in the commercial aws partition, where Global Accelerator provides the data path to the regional ALBs. Elsewhere the global API keeps only its aggregate routes and workload traffic uses each region's bridge.

• Operation ID: getApiV1Proxy
• Tags: control-plane
• Security: sigv4
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: api-gateway-proxy (lambda/api-gateway-proxy/handler.py; python3.14, handler.lambda_handler, 29 s timeout)
• Behaviour: Buffered control-plane proxy. Fetches the HMAC signing key from Secrets Manager, rejects region-pinning headers and base64 bodies, signs the method, path, query, body digest, timestamp and nonce into the X-GCO-* envelope and forwards over private-root TLS within 28 s.
• Then:
  1. AWS Global Accelerator: TCP/443 pass-through to the regional internal ALB
  2. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  3. manifest-processor (catch-all and /api/v1/manifests) or health-monitor (/api/v1/health, /api/v1/metrics, /healthz) — manifest-processor, health-monitor

Responses

POST /api/v1/{proxy+}¶

Catch-all for the control-plane API served by the in-cluster FastAPI services. {proxy+} is the rest of the path — for example jobs, jobs/{namespace}/{name}, manifests, health, status — so the operations available here are the /api/v1/* paths of the manifest-processor and health-monitor documents, minus /api/v1/global/*, which the aggregator serves. The request is forwarded unchanged (the stage prefix is not part of the backend path); the response is returned unchanged.

Only when: Present only in the commercial aws partition, where Global Accelerator provides the data path to the regional ALBs. Elsewhere the global API keeps only its aggregate routes and workload traffic uses each region's bridge.

• Operation ID: postApiV1Proxy
• Tags: control-plane
• Security: sigv4
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: api-gateway-proxy (lambda/api-gateway-proxy/handler.py; python3.14, handler.lambda_handler, 29 s timeout)
• Behaviour: Buffered control-plane proxy. Fetches the HMAC signing key from Secrets Manager, rejects region-pinning headers and base64 bodies, signs the method, path, query, body digest, timestamp and nonce into the X-GCO-* envelope and forwards over private-root TLS within 28 s.
• Then:
  1. AWS Global Accelerator: TCP/443 pass-through to the regional internal ALB
  2. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  3. manifest-processor (catch-all and /api/v1/manifests) or health-monitor (/api/v1/health, /api/v1/metrics, /healthz) — manifest-processor, health-monitor

Responses

PUT /api/v1/{proxy+}¶

Catch-all for the control-plane API served by the in-cluster FastAPI services. {proxy+} is the rest of the path — for example jobs, jobs/{namespace}/{name}, manifests, health, status — so the operations available here are the /api/v1/* paths of the manifest-processor and health-monitor documents, minus /api/v1/global/*, which the aggregator serves. The request is forwarded unchanged (the stage prefix is not part of the backend path); the response is returned unchanged.

Only when: Present only in the commercial aws partition, where Global Accelerator provides the data path to the regional ALBs. Elsewhere the global API keeps only its aggregate routes and workload traffic uses each region's bridge.

• Operation ID: putApiV1Proxy
• Tags: control-plane
• Security: sigv4
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: api-gateway-proxy (lambda/api-gateway-proxy/handler.py; python3.14, handler.lambda_handler, 29 s timeout)
• Behaviour: Buffered control-plane proxy. Fetches the HMAC signing key from Secrets Manager, rejects region-pinning headers and base64 bodies, signs the method, path, query, body digest, timestamp and nonce into the X-GCO-* envelope and forwards over private-root TLS within 28 s.
• Then:
  1. AWS Global Accelerator: TCP/443 pass-through to the regional internal ALB
  2. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  3. manifest-processor (catch-all and /api/v1/manifests) or health-monitor (/api/v1/health, /api/v1/metrics, /healthz) — manifest-processor, health-monitor

Responses

PATCH /api/v1/{proxy+}¶

Catch-all for the control-plane API served by the in-cluster FastAPI services. {proxy+} is the rest of the path — for example jobs, jobs/{namespace}/{name}, manifests, health, status — so the operations available here are the /api/v1/* paths of the manifest-processor and health-monitor documents, minus /api/v1/global/*, which the aggregator serves. The request is forwarded unchanged (the stage prefix is not part of the backend path); the response is returned unchanged.

Only when: Present only in the commercial aws partition, where Global Accelerator provides the data path to the regional ALBs. Elsewhere the global API keeps only its aggregate routes and workload traffic uses each region's bridge.

• Operation ID: patchApiV1Proxy
• Tags: control-plane
• Security: sigv4
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: api-gateway-proxy (lambda/api-gateway-proxy/handler.py; python3.14, handler.lambda_handler, 29 s timeout)
• Behaviour: Buffered control-plane proxy. Fetches the HMAC signing key from Secrets Manager, rejects region-pinning headers and base64 bodies, signs the method, path, query, body digest, timestamp and nonce into the X-GCO-* envelope and forwards over private-root TLS within 28 s.
• Then:
  1. AWS Global Accelerator: TCP/443 pass-through to the regional internal ALB
  2. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  3. manifest-processor (catch-all and /api/v1/manifests) or health-monitor (/api/v1/health, /api/v1/metrics, /healthz) — manifest-processor, health-monitor

Responses

DELETE /api/v1/{proxy+}¶

Catch-all for the control-plane API served by the in-cluster FastAPI services. {proxy+} is the rest of the path — for example jobs, jobs/{namespace}/{name}, manifests, health, status — so the operations available here are the /api/v1/* paths of the manifest-processor and health-monitor documents, minus /api/v1/global/*, which the aggregator serves. The request is forwarded unchanged (the stage prefix is not part of the backend path); the response is returned unchanged.

Only when: Present only in the commercial aws partition, where Global Accelerator provides the data path to the regional ALBs. Elsewhere the global API keeps only its aggregate routes and workload traffic uses each region's bridge.

• Operation ID: deleteApiV1Proxy
• Tags: control-plane
• Security: sigv4
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: api-gateway-proxy (lambda/api-gateway-proxy/handler.py; python3.14, handler.lambda_handler, 29 s timeout)
• Behaviour: Buffered control-plane proxy. Fetches the HMAC signing key from Secrets Manager, rejects region-pinning headers and base64 bodies, signs the method, path, query, body digest, timestamp and nonce into the X-GCO-* envelope and forwards over private-root TLS within 28 s.
• Then:
  1. AWS Global Accelerator: TCP/443 pass-through to the regional internal ALB
  2. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  3. manifest-processor (catch-all and /api/v1/manifests) or health-monitor (/api/v1/health, /api/v1/metrics, /healthz) — manifest-processor, health-monitor

Responses

GET /inference/{proxy+}¶

Streaming access to deployed inference endpoints. {proxy+} is <endpoint-name> or <endpoint-name>/<serving-path>; the in-cluster inference-proxy resolves the endpoint by name and allows only its serving and health paths (see the inference-proxy document). Bodies are limited to 1 MiB and the connection may stay open for API Gateway's full 15-minute streaming window.

Only when: Present only in the commercial aws partition, where Global Accelerator provides the data path to the regional ALBs. Elsewhere the global API keeps only its aggregate routes and workload traffic uses each region's bridge.

• Operation ID: getInferenceProxy
• Tags: inference
• Security: sigv4
• Integration: aws_proxy, 900 s integration timeout, response streaming

Backend

• Lambda: inference-streaming-proxy (lambda/inference-streaming-proxy/index.mjs; nodejs24.x, index.handler, 900 s timeout)
• Behaviour: Node.js response-streaming proxy (ROUTING_MODE=global). Accepts GET, HEAD and POST under /inference//..., caps the body at 1 MiB, signs the HMAC envelope and streams the model server's response for up to 15 minutes.
• Then:
  1. AWS Global Accelerator: TCP/443 pass-through to the regional internal ALB
  2. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  3. inference-proxy Service: resolves the endpoint by name, enforces its state and the serving-path allowlist — inference-proxy
  4. The endpoint's model-server Service in gco-inference (, -canary or -proxy), streamed back through every hop

Responses

POST /inference/{proxy+}¶

Streaming access to deployed inference endpoints. {proxy+} is <endpoint-name> or <endpoint-name>/<serving-path>; the in-cluster inference-proxy resolves the endpoint by name and allows only its serving and health paths (see the inference-proxy document). Bodies are limited to 1 MiB and the connection may stay open for API Gateway's full 15-minute streaming window.

Only when: Present only in the commercial aws partition, where Global Accelerator provides the data path to the regional ALBs. Elsewhere the global API keeps only its aggregate routes and workload traffic uses each region's bridge.

• Operation ID: postInferenceProxy
• Tags: inference
• Security: sigv4
• Integration: aws_proxy, 900 s integration timeout, response streaming

Backend

• Lambda: inference-streaming-proxy (lambda/inference-streaming-proxy/index.mjs; nodejs24.x, index.handler, 900 s timeout)
• Behaviour: Node.js response-streaming proxy (ROUTING_MODE=global). Accepts GET, HEAD and POST under /inference//..., caps the body at 1 MiB, signs the HMAC envelope and streams the model server's response for up to 15 minutes.
• Then:
  1. AWS Global Accelerator: TCP/443 pass-through to the regional internal ALB
  2. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  3. inference-proxy Service: resolves the endpoint by name, enforces its state and the serving-path allowlist — inference-proxy
  4. The endpoint's model-server Service in gco-inference (, -canary or -proxy), streamed back through every hop

Responses

HEAD /inference/{proxy+}¶

Streaming access to deployed inference endpoints. {proxy+} is <endpoint-name> or <endpoint-name>/<serving-path>; the in-cluster inference-proxy resolves the endpoint by name and allows only its serving and health paths (see the inference-proxy document). Bodies are limited to 1 MiB and the connection may stay open for API Gateway's full 15-minute streaming window.

Only when: Present only in the commercial aws partition, where Global Accelerator provides the data path to the regional ALBs. Elsewhere the global API keeps only its aggregate routes and workload traffic uses each region's bridge.

• Operation ID: headInferenceProxy
• Tags: inference
• Security: sigv4
• Integration: aws_proxy, 900 s integration timeout, response streaming

Backend

• Lambda: inference-streaming-proxy (lambda/inference-streaming-proxy/index.mjs; nodejs24.x, index.handler, 900 s timeout)
• Behaviour: Node.js response-streaming proxy (ROUTING_MODE=global). Accepts GET, HEAD and POST under /inference//..., caps the body at 1 MiB, signs the HMAC envelope and streams the model server's response for up to 15 minutes.
• Then:
  1. AWS Global Accelerator: TCP/443 pass-through to the regional internal ALB
  2. Internal ALB — the Kubernetes Gateway gco-system/gco-gateway; HTTPRoute gco-routes picks the Service by longest path prefix — cluster-gateway
  3. inference-proxy Service: resolves the endpoint by name, enforces its state and the serving-path allowlist — inference-proxy
  4. The endpoint's model-server Service in gco-inference (, -canary or -proxy), streamed back through every hop

Responses

GET /studio/callback¶

Unauthenticated MOCK integration returning an empty 200 body: the Cognito hosted-UI OAuth redirect target. The browser redirect carries the authorization code as a query-string parameter and nothing reads the body.

Only when: Present only when analytics_environment.enabled is true in cdk.json.

• Operation ID: getStudioCallback
• Tags: studio
• Security: none (unauthenticated)
• Integration: mock

Backend

• Integration: mock
• Behaviour: API Gateway answers directly; no Lambda and no backend is involved.

Responses

GET /studio/login¶

Authenticated with a Cognito ID token from the Studio user pool rather than SigV4. Returns a presigned SageMaker Studio URL for the caller's user profile.

Only when: Present only when analytics_environment.enabled is true in cdk.json.

• Operation ID: getStudioLogin
• Tags: studio
• Security: cognito
• Integration: aws_proxy, 29 s integration timeout

Backend

• Lambda: analytics-presigned-url (lambda/analytics-presigned-url/handler.py; python3.13, index.handler)
• Behaviour: The analytics stack's presigned-URL Lambda (GCOAnalyticsStack): exchanges the Cognito identity for a SageMaker Studio presigned login URL. Synthesized here with an inline stand-in because the analytics stack is not part of this API's template.

Responses

Schemas¶

This api gateway declares no component schemas.