> ## Documentation Index
> Fetch the complete documentation index at: https://developers.aptranet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Shield API

> Authenticate protection automation, handle project ownership and entitlements, and interpret Cloud Shield responses.

Use `https://api.aptranet.com/shield` with the [access-key and secret headers](/api-reference/authentication). The key determines the project. Resource IDs returned by this API belong to that project; never derive or reuse IDs from another account.

## Start with service and distributions

1. Read `GET /shield/service` for readiness, plan code, limits, and active add-ons.
2. Read `GET /shield/distributions` for eligible CDN distributions and existing attachments.
3. Attach a distribution with `POST /shield/domains` and `{"distribution_id": 42}`.
4. Wait until the returned domain ID is available before changing domain policies or rules.

## Request conventions

Most collections use `limit` and `offset`; inspect each endpoint's maximum. Array query parameters use repeated keys, such as `ids=12&ids=15`. Send ISO 8601 timestamps when a filter requires a time; use `YYYY-MM-DD` for pre-billing dates. Unknown query filters are rejected.

Read the endpoint reference for the required fields of each action. PATCH routes accept the fields described by their schema. Bulk rule deletion uses POST with delete permission. Response-page preview uses POST with list permission. Clearing local reputation tags uses modify permission.

## Readiness and errors

| Response | What to do |
| - | - |
| `400` invalid input or unsupported filter | Correct the request using the endpoint schema |
| `402` inactive service | Activate the organization's Cloud Shield subscription |
| `403` missing permission, plan, or add-on | Review project permissions and the service's reported entitlements |
| `404` missing resource | Verify the selected project and resource ID |
| `409` limit or lifecycle conflict | Review the current state before making another change |
| `502` or `503` unavailable service | Check service status and retry reads with backoff |
| `shield_reconciliation_required` | Refresh and contact support before retrying the mutation; the change may already have applied |

Collection responses can include a `results` array and `count`, while some analytics return arrays directly. Responses vary by operation. Handle an empty body separately from an empty collection and preserve the data-freshness headers described in [investigations](/cloud-shield/investigations).

Legacy `/shield/domains/{domain_id}/tls` operations return `409 managed_by_cdn`. Use the linked distribution's TLS configuration instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.