# ag-id

Dynamic DNS for AI agents: register a host to get a stable `<name>.ag-id.cc`
subdomain and a bearer token, then point it at your current IP over a plain
HTTP API. No captchas, no human verification, no friction, and no limit on how
many names you register. An agent can make itself reachable by DNS or URL
without owning a domain.

## Base URL

`https://api.ag-id.cc`

## Model

- Host = `<name>.ag-id.cc`, where `name` is 8 characters of `[a-z0-9]`,
  server-picked (callers cannot choose it).
- The bearer token is issued once at registration and shown only in that
  response; it is never retrievable afterward, so save it.
- Records are A and AAAA only, at most one of each per host, and must be public
  addresses (private, loopback, link-local, and multicast are rejected).
- Hosts never expire. `DELETE` is soft: the records are removed but the row and
  token stay, so a later `PATCH` restores the host.
- Register as many hosts as you like.

## Examples

Register a host (no auth):

```
curl -sS -X POST https://api.ag-id.cc/hosts
```

```
201 Created
{"name": "a1b2c3d4", "fqdn": "a1b2c3d4.ag-id.cc", "token": "agid_..."}
```

Read a host's state (bearer):

```
curl -sS https://api.ag-id.cc/hosts/a1b2c3d4 \
  -H "Authorization: Bearer agid_..."
```

```
200 OK
{"name": "a1b2c3d4", "fqdn": "a1b2c3d4.ag-id.cc", "a": "203.0.113.7", "aaaa": null, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}
```

Update records (bearer). A string sets that family, `null` clears it, and an
omitted field leaves it untouched:

```
curl -sS -X PATCH https://api.ag-id.cc/hosts/a1b2c3d4 \
  -H "Authorization: Bearer agid_..." \
  -H "Content-Type: application/json" \
  -d '{"a": "203.0.113.7", "aaaa": null}'
```

```
200 OK
{"name": "a1b2c3d4", "fqdn": "a1b2c3d4.ag-id.cc", "a": "203.0.113.7", "aaaa": null, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:05Z"}
```

Delete a host (bearer, soft):

```
curl -sS -X DELETE https://api.ag-id.cc/hosts/a1b2c3d4 \
  -H "Authorization: Bearer agid_..."
```

```
204 No Content
```

## OpenAPI

- Spec (JSON): `https://api.ag-id.cc/openapi.json`
- Interactive docs (Swagger UI): `https://api.ag-id.cc/docs`

## Health

`https://api.ag-id.cc/health`