Gateway API

Common Routes

Method	Path	Purpose
`POST`	`/gateway/fetch`	Read rows with filters, sort, limit, and grouping options
`PUT`	`/gateway/insert`	Insert rows
`POST`	`/gateway/update`	Update rows matching conditions
`DELETE`	`/gateway/delete`	Delete rows matching conditions
`POST`	`/gateway/query`	Execute SQL through gateway contract

Fetch Example

curl -X POST "http://localhost:4052/gateway/fetch" \
  -H "content-type: application/json" \
  -H "x-athena-client: analytics" \
  -d '{
    "table": "events",
    "columns": ["id", "type", "created_at"],
    "conditions": [{ "column": "type", "operator": "eq", "value": "checkout.completed" }],
    "order_by": { "column": "created_at", "direction": "desc" },
    "limit": 100
  }'

Query Example

curl -X POST "http://localhost:4052/gateway/query" \
  -H "content-type: application/json" \
  -H "x-athena-client: analytics" \
  -d '{"query":"select count(*) from events"}'

Post-Processing Support

Fetch/update payloads may include:

group_by
time_granularity
aggregation_column
aggregation_strategy
aggregation_dedup

When enabled, results include post_processing.grouped.

Stats tables and typed filters

When fetching client_statistics or client_table_statistics via /gateway/fetch (or related entry points), equality conditions on numeric and timestamp columns are aligned with Postgres column types so string JSON values do not trigger type errors (42883) at runtime. See Gateway fetch and stats tables.

Raw SQL drivers

/gateway/sql and /query/sql enforce gateway.query (admin or gateway key) and an allowlisted driver (athena, postgresql / postgres, supabase). See the same security page for context.

Structured gateway tracing

Gateway-style routes now emit a wide structured trace event on the athena_rs::gateway_trace target for request/response correlation.

The event includes the fields operators typically need first:

request_id, client, method, path, and logical operation
table_name, resource_id, status_code, outcome, and duration_ms
backend, cache hit/write markers, row counters, trace_id, and error_code

These trace events are emitted from the centralized operation logging path, so /gateway/*, /data, /rest/*, and /rpc/* stay aligned without each handler needing bespoke log formatting.