# agentsite for agents — quick-start

Authenticate, find the spec, operate on a customer's site — without trial and error.

By AgentSite · Updated 2026-05-27

## Quick-start for agents

You're an AI agent acting on behalf of a customer who has an AgentSite account. This page is the smallest set of facts you need to (a) authenticate, (b) discover the API, and (c) make useful changes without surprises.

If you only have one shot at reading docs, read this one.

## 1\. Authenticate

AgentSite accepts `Authorization: Bearer <token>` on every API call. Two token shapes work:

-   **JWT session token** — issued via Google login or magic link. Held by the dashboard; not usually visible to agents.
-   **Personal Access Token (PAT)** — created by the user at [https://agentsite.app/settings/tokens](https://agentsite.app/settings/tokens). Looks like `asit_...`. Carries explicit scopes + optional expiry. **This is what agents use.**

Ask your user to mint a PAT scoped to what you actually need:

| Scope | Lets you do |
| --- | --- |
| `sites:read` | List sites; read configs, file previews, usage, paths, rendered pages, bot telemetry, AEO reports. |
| `sites:write` | PATCH any site setting (config, file modes, body mode, generation tier, index path, skip patterns), regenerate paths, expire cache. |
| `reports:read` | Read AEO reports by id. |
| `tokens:read` | List PATs (rarely needed by an agent). |

Default scope set for a new PAT covers `sites:read`, `sites:write`, `reports:read` — comfortable for most agent loops.

**You will get a 403** if you try to:

-   `DELETE /site/:id` (soft-delete still requires the human session)
-   `POST /site/:id/rotate` (site-token rotation stays interactive)
-   Mint or revoke another PAT (`POST /api-token`, rotate, delete)
-   Touch billing writes, or hit any `/admin/*` endpoint

These are deliberate — they don't fail because the token is broken; they fail because the action requires interactive human authorization. **Note:** `POST /site` (registering a new domain) is **not** in this list — agents can do that on behalf of a logged-in user. See §3.5 below.

## 2\. Discover the API

Machine-readable spec: [https://api.agentsite.app/openapi.yaml](https://api.agentsite.app/openapi.yaml) (or `/openapi.json`).

The spec covers every non-admin endpoint with full request/response schemas. Tags split it into logical groups (sites, reports, render, tokens). Validate against the spec rather than guessing field names — they evolve.

A human-readable companion lives at [https://api.agentsite.app/docs.md](https://api.agentsite.app/docs.md) if you need narrative context on cache semantics, render-engine choice, or response headers.

## 3\. The smallest useful loop

```bash
TOK=asit_xxx   # the user's PAT
BASE=https://api.agentsite.app

# List the user's sites
curl -s -H "Authorization: Bearer $TOK" "$BASE/site"
# → [{ id, host, ... }, ...]

# Read one site's config
SID=site_abc123
curl -s -H "Authorization: Bearer $TOK" "$BASE/site/$SID/config"
# → { displayName, robotsAllowCitationBots, robotsAllowTrainingBots, ... }

# Update one field
curl -s -X PATCH -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  "$BASE/site/$SID/config" \
  -d '{"displayName":"Acme Docs"}'
# → 200 with the updated SiteConfigSummary

# Regenerate one path (after a content change on the customer's site)
curl -s -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  "$BASE/site/$SID/regenerate-path" \
  -d '{"path":"/pricing"}'
# → { status, renderedAt, ... }
```

Every endpoint follows the same shape: bearer auth, JSON in, JSON out, standard HTTP semantics. 4xx errors carry `{ error, message }`.

## 3.5. Onboarding a brand-new site

If the user hands you their token and says "set up AgentSite on my site at `example.com`," you handle the whole loop. Sketch:

```bash
TOK=asit_xxx
BASE=https://api.agentsite.app

# 1. Register the domain. The response carries the site id and a
#    SITE_TOKEN — same token shape (asit_…) but bound to one site.
#    You can use either bearer for the snippet runtime; the SITE_TOKEN
#    is the conventional choice because it's scoped to one host.
curl -s -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  "$BASE/site" \
  -d '{"domain":"example.com"}'
# → { id, domain, token, tokenTail, isActive, createdAt }

# 2. Pick the install pattern from /install.md based on the user's
#    stack (Nginx / Express / Express-Sidecar / Edge / SDK). Edit
#    the user's repo to apply the pattern. Set AGENTSITE_TOKEN to
#    the SITE_TOKEN you received (or to the user's PAT — both work).
#    Do NOT ship the PAT to the browser; keep it server-side.

# 3. Verify the install. AgentsiteDetector fetches the customer's
#    homepage and looks for the snippet sentinel.
curl -s -X POST -H "Authorization: Bearer $TOK" \
  "$BASE/site/$SITE_ID/snippet-probe"
# → { detected: true|false, version?, evidence }

# 4. Link the user to https://agentsite.app/dashboard/<SITE_ID> so
#    they can watch the first AEO score arrive.
```

If `detected: false`, common failure modes: token not in env, dev server hasn't been restarted with the new env, CDN cache is still serving the pre-install bytes, or the snippet is hitting the wrong API base. Walk the user through checking each.

## 4\. Reading AEO reports

```bash
REPORT_ID=aerp_xxx
curl -s -H "Authorization: Bearer $TOK" "$BASE/aeo-report/$REPORT_ID"
# → { id, compositeScore, layerScores, pages: [...], findings: [...] }
```

Reports surface AEO (Answer Engine Optimization) score breakdowns. Use them to tell the user where their site is weak for AI-citation purposes.

You **cannot** submit a new report on the user's behalf — that endpoint is public and metered, but submitting it implies a deliberate "run a scan now" action that should be the user's decision.

## 5\. Agent etiquette

A few things that will save you from being That Agent.

-   **Don't reflexively call `/regenerate`.** A full-site regenerate is long-running and meters against the user's plan. Call it when the user explicitly asks for it, or when you've made a setting change that needs it. Otherwise prefer `/regenerate-path` (one path at a time) or `/cache/expire` (mark stale; next request re-renders).
-   **Don't try to create or delete sites.** Both are session-only. If the user wants to add a new site, tell them to do it from [https://agentsite.app/dashboard](https://agentsite.app/dashboard).
-   **Don't change billing.** All billing writes are session-only. Read endpoints are scoped to `sites:read` if you genuinely need usage / balance data.
-   **Probe with `X-Agentsite: none` when you need raw customer state.** Send the `X-Agentsite: none` request header (or `X-Agentsite: none` via fetch options) to bypass AgentSite's render and return the customer's raw response. Useful for verifying what's actually on their server before recommending changes. _Header-only by design — the query-string form (`?_agentsite=none`) was removed when the Nginx install pattern landed, since nginx can't parse query strings. Every install pattern honors the same bypass surface._
-   **Respect 403 on principle.** A 403 isn't a sign your token is wrong — re-read the "you will get a 403" list above. The system is telling you the action belongs to the human.

## 6\. Common loops in plain English

-   **"Set up better robots.txt for citation bots."** → GET `/site/:id/config`, examine `robotsAllowCitationBots` + `robotsAllowTrainingBots`, PATCH to the user's desired policy, then GET `/site/:id/files` to preview the generated robots.txt.
-   **"Why is the AEO score low?"** → GET `/aeo-report/:id`, look at `findings[]` and per-page `dimensionScores`. Recommend fixes; do not auto-apply.
-   **"This page didn't update — refresh it."** → POST `/site/:id/regenerate-path` with `{path}`. Wait a few seconds; GET `/site/:id/bundle?path=...` to verify the new render.
-   **"What's getting traffic?"** → GET `/site/:id/paths?days=7`. Returns top paths + hit counts.

## Where to go deeper

-   **OpenAPI:** [https://api.agentsite.app/openapi.yaml](https://api.agentsite.app/openapi.yaml)
-   **Detailed API reference (humans):** [https://api.agentsite.app/docs.md](https://api.agentsite.app/docs.md)
-   **Install patterns (if the user hasn't installed yet):** [https://api.agentsite.app/install.md](https://api.agentsite.app/install.md)
-   **llms.txt (top-level pointer for AI crawlers):** [https://api.agentsite.app/llms.txt](https://api.agentsite.app/llms.txt)

If you hit something that doesn't match this doc, the spec at `/openapi.yaml` is authoritative.