> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudservices.ecowestern.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Register and manage Waymark domains

> Attach custom hostnames to ECS resources

## Register a domain

`POST /waymark/domains` requires `waymark:write`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "hostname": "shop.example.com",
  "target": {
    "kind": "canopy",
    "resource_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

`hostname` must be fully qualified. `target.kind` must be `flow`, `canopy`, or `clearlake`. `target.resource_id` is the ECS resource UUID and must belong to the same account as the API key.

Response: `201 Created`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "hostname": "shop.example.com",
  "target_kind": "canopy",
  "target_resource_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "cname_target": "connect.cloudservices.ecowestern.net",
  "cname_instructions": "Add a CNAME record pointing shop.example.com to connect.cloudservices.ecowestern.net"
}
```

## List domains

`GET /waymark/domains` requires `waymark:read` and returns `{ "domains": [...] }`.

## Inspect a domain

`GET /waymark/domains/:hostname` requires `waymark:read` and returns the current status. Pending domains may include `message` and `verification_errors` fields.

## Delete a domain

`DELETE /waymark/domains/:hostname` requires `waymark:delete` and returns `204 No Content`.

DNS records at your registrar are not removed when a Waymark registration is deleted.

## Domain naming

Hostnames are globally unique. Register the exact hostname that will appear in DNS, including any subdomain such as `api.example.com` or `www.example.com`.