HTTP/JSON

The HTTP/JSON surface comes from grpc-gateway: routes and payload shapes are generated from google.api.http annotations in the proto. No handlers are written by hand.

Route mapping

Annotations sit on each rpc, for example in the sample resource:

rpc GetResource(GetResourceRequest) returns (Resource) {
  option (google.api.http) = {get: "/v1/resources/{id}"};
}

The full mapping for the sample resource:

RPC	HTTP
CreateResource	POST /v1/resources
GetResource	GET /v1/resources/{id}
ListResources	GET /v1/resources
UpdateResource	PATCH /v1/resources/{id}
DeleteResource	DELETE /v1/resources/{id}

Calling and auth

curl localhost:8080/v1/resources/x \
  -H 'Authorization: Bearer <token>'

Without a token the response is 401. The gateway shares the interceptor chain with gRPC and MCP, and error bodies come from the unified error model — internal causes are not included.

Request body limits

The gateway caps request bodies at 1 MB with a 30-second read timeout: oversized bodies get 413, slow reads get 408.

CORS and OpenAPI

• server.enable_cors: true is only the master switch; the actual allowlist is server.cors_origins. Origins not listed there receive no CORS headers at all — enabling enable_cors without setting origins still blocks browsers. Use "*" to allow all, or list explicit origins (GORTEXA_SERVER__CORS_ORIGINS accepts a comma-separated override). Preflight OPTIONS requests are short-circuited.
• With server.openapi: true, the OpenAPI spec is served at /openapi.json. The spec is a build artifact of make gen, read once at startup and served from memory.

Response headers

Response headers pass through an allowlist: internal headers do not leak, and X-Request-Id is preserved for correlation.