Usage: API Examples

Projection Query via Gateway (HTTP → gRPC)

curl -sS -X POST \
  -H "x-tenant-id: tenant-a" \
  -H "x-correlation-id: demo" \
  -H "traceparent: 00-00000000000000000000000000000001-0000000000000001-01" \
  http://localhost:8080/v1/query/User \
  -d '{"uqf":"{\"eq\":{\"id\":\"u1\"}}"}'

Projection Query via gRPC (direct, internal)

grpcurl -d '{"tenant_id":"tenant-a","view_type":"User","uqf":"{}"}' \
  -H 'x-tenant-id: tenant-a' \
  -H 'x-correlation-id: demo' \
  -H 'traceparent: 00-00000000000000000000000000000001-0000000000000001-01' \
  -plaintext localhost:9090 projection.gateway.v1.QueryService/ExecuteQuery

Aggregate Command via Gateway (HTTP → gRPC)

curl -sS -X POST \
  -H "x-tenant-id: tenant-a" \
  -H "x-correlation-id: demo" \
  -H "traceparent: 00-00000000000000000000000000000001-0000000000000001-01" \
  http://localhost:8080/v1/aggregate/BankAccount/command \
  -d '{"id":"acc-1","command_type":"Open","payload":{"owner":"Alice"}}'

Runner Admin via Gateway (HTTP → gRPC)

curl -sS -X POST \
  -H "x-tenant-id: tenant-a" \
  -H "authorization: Bearer <token>" \
  http://localhost:8080/admin/runner/drain?wait_ms=0

Document Storage via Control API (S3-backed)

List documents for a tenant (Control API uses UUID tenant ids):

curl -sS \
  -H "authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-uuid>" \
  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs"

Upload a document (stores at docs/<tenant>/<type>/<id>/<filename>):

curl -sS -X PUT \
  -H "authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-uuid>" \
  -H "content-type: application/octet-stream" \
  --data-binary @./bundle.tar.gz \
  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/deployments/<doc-id>/bundle.tar.gz"

Download by object key (streamed proxy; key must belong to the tenant prefix):

curl -sS -o ./out.tar.gz \
  -H "authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-uuid>" \
  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/object/<url-encoded-key>"

Delete by object key (requires control:write):

curl -sS -X DELETE \
  -H "authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-uuid>" \
  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/object/<url-encoded-key>"

Presign upload (JSON body; returns PUT URL and key):

curl -sS -X POST \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -H "x-tenant-id: <tenant-uuid>" \
  -d '{"doc_type":"deployments","doc_id":"<doc-id>","filename":"bundle.tar.gz","content_type":"application/gzip"}' \
  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/presign/upload"

Presign download (JSON body with full key under that tenant):

curl -sS -X POST \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -H "x-tenant-id: <tenant-uuid>" \
  -d '{"key":"docs/<tenant-uuid>/deployments/<doc-id>/bundle.tar.gz"}' \
  "http://localhost:38080/admin/v1/tenants/<tenant-uuid>/docs/presign/download"

Environment variables for the Control API (also accept S3_* names without the CONTROL_ prefix; see S3_PLAN.md):

CONTROL_S3_ENDPOINT — S3 API base URL used by the server client
CONTROL_S3_PUBLIC_ENDPOINT — optional; host used in presigned URLs when browsers must reach a different host than the API (e.g. localhost:9000 vs minio:9000 in compose)
CONTROL_S3_REGION, CONTROL_S3_BUCKET_DOCS, CONTROL_S3_PREFIX_DOCS, CONTROL_S3_FORCE_PATH_STYLE, CONTROL_S3_INSECURE
Secrets may be mounted as files: CONTROL_S3_ACCESS_KEY_ID_FILE, CONTROL_S3_SECRET_ACCESS_KEY_FILE

3.7 KiB Raw Blame History