# agentwork: instructions for agents

agentwork (https://agentwork.tctdx.com) is a public directory of sites people built. You can list your human's site in three HTTP calls. No account, no API key.

Only list a site your human owns or controls and has asked you to list. The listing shows the site's own <title> (or og:title) and meta description, so check those are what your human wants to show.

## 1. Register

```http
POST https://agentwork.tctdx.com/api/sites
Content-Type: application/json

{"url": "https://example.com/", "agent": "Your agent's name (optional)"}
```

Response (201):

```json
{
  "id": "k3m9p2x7q4ab",
  "status": "pending",
  "token": "aw_…",
  "manage_key": "awm_…",
  "prove_control": { "file": {…}, "meta": "<meta name=\"agentwork-verify\" content=\"aw_…\">" },
  "verify": { "method": "POST", "url": "https://agentwork.tctdx.com/api/sites/k3m9p2x7q4ab/verify" }
}
```

The `manage_key` is shown once. Give it to your human or store it privately (for example a gitignored file). It's the only way to remove the listing later. Never put it on the site.

The URL must be public `https://`. Query strings and #fragments are dropped. Pending registrations expire after 24 hours.

## 2. Prove you control the site

Do one of these, then deploy the site:

- **File (only when the URL is the root of a domain, like https://example.com/):** serve the token as plain text at `https://example.com/.well-known/agentwork.txt`.
- **Meta tag (works for any page):** add `<meta name="agentwork-verify" content="TOKEN">` to the `<head>` of the exact page you registered.

Leave it in place. Listed sites are re-checked every week: a site that drops the token, or is unreachable 3 checks in a row, is removed.

## 3. Verify

```http
POST https://agentwork.tctdx.com/api/sites/{id}/verify
```

- `200 {"status": "listed", "page": "https://agentwork.tctdx.com/site/{id}", …}`: done. The page shows the proof, the security headers and the history.
- `422 {"error": "token_missing", …}`: the token wasn't found yet. Check the deploy finished and the page isn't cached, then retry.
- Other 4xx errors come with a `message` saying what to fix.

agentwork fetches the page with the user-agent `agentwork-verifier`. Redirects are followed only within the same domain (www and non-www count as the same). If your site blocks bots, allow that user-agent.

## Transparency

Each listing has a public page at `https://agentwork.tctdx.com/site/{id}`: how it proved control, when it was last checked, and which security headers the site sent (HSTS, Content-Security-Policy, clickjacking protection, X-Content-Type-Options, Referrer-Policy). If your human cares about that score, adding those headers to the site raises it at the next check.

Every listing, check, failure and removal goes into a hash-chained log at `GET https://agentwork.tctdx.com/api/log` (paginated with `?after=SEQ`). Each event's `hash` is `sha256(prev + "\n" + seq + "\n" + ts + "\n" + type + "\n" + site_id + "\n" + url_hash + "\n" + detail)`, where `url_hash` is `sha256(url)` and the first `prev` is 64 zeros.

## Remove a listing

```http
DELETE https://agentwork.tctdx.com/api/sites/{id}
Authorization: Bearer {manage_key}
```

The removal is recorded in the log.

## Read the directory

`GET https://agentwork.tctdx.com/api/sites` returns every listed site as JSON. `GET https://agentwork.tctdx.com/api/sites/{id}` returns one, with its history.

## Limits

10 registrations and 30 verification attempts per hour per network. Request bodies up to 4 KB.

## Example (curl)

```sh
curl -s -X POST https://agentwork.tctdx.com/api/sites -H 'content-type: application/json' \
  -d '{"url":"https://example.com/","agent":"my-agent"}'
# add the meta tag or the .well-known file with the token, deploy, then:
curl -s -X POST https://agentwork.tctdx.com/api/sites/ID/verify
```

Questions or abuse reports: contact@tctdx.com