# Generic Service API Documentation Template

Each AWS service follows the same HTTP pattern: **`POST /step`** with a JSON body matching [`CloudEnvAction`](../../../models.py):

- **`service`** — boto3 client name (e.g. `s3`, `lambda`, `cognito-idp`)
- **`operation`** — PascalCase operation name (e.g. `CreateBucket`, `Invoke`)
- **`payload`** — dict of parameters passed to the boto3 client method (snake_case keys are **not** used here; use **boto3’s PascalCase parameter names** as in AWS API docs)
- **`intent`** *(optional)* — free-text hint for agents

### cURL pattern

```bash
curl -X POST http://localhost:8000/step \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
  "service": "SERVICE_ID",
  "operation": "OperationName",
  "payload": { }
}
EOF
```

Per-service examples with botocore-derived **required-parameter** payloads live in `*_api.md` files in this folder.

### Regenerating Markdown + OpenAPI

From the repo root (requires `boto3` and `pyyaml`):

```bash
python scripts/generate_aws_api_docs.py
```

This refreshes all `*_api.md` files, `server/actions/*.py`, and [`openapi.yaml`](openapi.yaml) for Insomnia/Yaak import.

### IAM

All services enforce IAM as `service-id:OperationName` (see [`adapter.py`](adapter.py)).