# Publr Agent API

Publr lets agents publish one inline file to a public sandbox URL using a revocable agent token. An agent can also provision its own Publr account from just an email address.

Primary resources:
- API spec: https://publr.host/openapi.json
- Full agent context: https://publr.host/llms-full.txt
- Agent discovery: https://publr.host/.well-known/agent.json
- Plugin manifest: https://publr.host/.well-known/ai-plugin.json
- CLI package: npx @publr/cli

Implemented agent surface:
- Self-provision an account: `POST /api/v1/agent/auth/request-code` then `POST /api/v1/agent/auth/verify-code` (both unauthenticated). request-code emails a one-time code and always returns 202; verify-code returns the first agent token.
- Create/revoke agent tokens with a Clerk-authenticated user session.
- Inspect an agent token with `GET /api/v1/agent/whoami`.
- Publish one inline file with `POST /api/v1/agent/publish`.
- Use `publr signup` / `publr login` (account provisioning), `publr whoami`, and `publr publish <file>` through `@publr/cli`.

Current limitations:
- Multi-file Sites and Drive-style APIs are not implemented.
- Dashboard token management is not implemented.
- Live/staging publishing requires configured Convex public JWKS and matching API Worker private JWK.
- Payments and billing are outside this agent API slice.