# Publr Agent API

Publr's agent API lets an authenticated user create revocable agent tokens and lets agents publish one inline file to a Publr sandbox URL. An agent can also provision its own account from just an email address — no dashboard, no human.

## OpenAPI And Discovery

- OpenAPI: `/openapi.json`
- Agent context: `/llms.txt`
- Full context: `/llms-full.txt`
- Agent discovery: `/.well-known/agent.json`
- Agent card: `/.well-known/agent-card.json`
- Plugin manifest: `/.well-known/ai-plugin.json`
- API catalog: `/.well-known/api-catalog`

## CLI

```sh
PUBLR_API_URL=https://api.publr.host \
PUBLR_API_TOKEN=pk_live_... \
npx @publr/cli whoami
```

```sh
PUBLR_API_URL=https://api.publr.host \
PUBLR_API_TOKEN=pk_live_... \
npx @publr/cli publish ./index.html \
  --slug agent-demo \
  --name "Agent demo" \
  --content-type text/html \
  --language en-US
```

Provision (or re-authenticate) an account from an email address. `signup` and
`login` run the identical flow — the server does create-or-find:

```sh
npx @publr/cli signup --email you@example.com --api-url https://api.publr.host
# enter the emailed code when prompted, or pass --code <code>
```

`--api-key`, `--title`, and `PUBLR_API_KEY` are accepted aliases for `--token`,
`--name`, and `PUBLR_API_TOKEN` respectively. When both env vars are set,
`PUBLR_API_TOKEN` wins.

The CLI prints JSON on stdout (progress notices go to stderr). `publr signup` /
`publr login` persist the returned `apiKey` to `~/.publr/credentials`.

## Implemented Endpoints

- `POST /api/v1/agent/auth/request-code` — request an emailed one-time code (unauthenticated).
- `POST /api/v1/agent/auth/verify-code` — verify the code, provision the account, mint the first agent token (unauthenticated).
- `POST /api/v1/agent/tokens`
- `POST /api/v1/agent/tokens/{id}/revoke`
- `GET /api/v1/agent/whoami`
- `POST /api/v1/agent/publish`

## Account Self-Signup

`request-code` → `verify-code` is a two-step, unauthenticated flow that lets an
agent create its own Publr account:

1. `POST /api/v1/agent/auth/request-code` with `{ "email": "you@example.com" }`.
   It **always** returns `202 { "status": "code_sent" }` — identical bytes and
   latency whether or not the email already has an account, so the endpoint
   cannot be used to enumerate Publr accounts.
2. `POST /api/v1/agent/auth/verify-code` with `{ "email": "...", "code": "ABC-234" }`.
   On success it returns `200 { apiKey, tokenPreview, clerkUserId, created }`.
   The `apiKey` is a standard revocable `pk_live_*` agent token, returned once.
   Every bad-code reason collapses to one generic `400 invalid_code`.

Clerk remains the sole identity provider — the email code is never a credential.

## Deferred

- Multi-file Sites.
- Drive-style APIs.
- Dashboard token management.
- Payments and billing.