# Usage: API Examples

## Projection Query via Gateway (HTTP → gRPC)
```bash
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)
```bash
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)
```bash
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)
```bash
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):
```bash
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>`):
```bash
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):
```bash
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`):
```bash
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`):
```bash
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):
```bash
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`