# Web Tool Desk

Small bounded tools for deliberate agent calls. Public requests use GET over HTTPS.
OpenAPI schema: /openapi.json. Human reference: /api-docs. Service health: /healthz.
Guides: /tools/url-to-markdown, /tools/website-screenshots, /tools/link-shortener, /tools/temporary-email, /tools/get-to-post.

- GET /v1/read?url=<encoded public URL>: Markdown from HTML, PDF and supported Office documents; format=json for metadata; render=true for isolated browser rendering.
- GET /v1/screenshot?url=<encoded public URL>: capture a PNG; output=image returns the image, default JSON returns artifact URLs. Public artifacts expire after 24 hours.
- GET /v1/shorten?url=<encoded public URL>: create a link. Repeat url for a multi-link collection. Save the management key securely. Idempotency-Key header supports retries. Passwords belong in X-Link-Password, never query parameters.
- GET /v1/mail/new?ttl_seconds=3600: create a receive-only mailbox if mail_enabled is true in /healthz. Save read_token securely. GET /v1/mail/inbox/{id} and GET /v1/mail/message/{id} require Authorization: Bearer <read_token>.
- GET /v1/relay?url=<encoded public HTTPS URL>&json=<encoded JSON>&idempotency_key=<unique key>: send a single bounded POST. Do not put credentials or confidential content in the query. Never retry a state-changing action with a new key unless a new action is intended.

GETs can have side effects. Do not prefetch or blindly retry creation, mutation, screenshot or relay URLs. HEAD is allowed only for non-counting /s/{slug} and /s/{slug}/{index} link checks; other non-GET public methods are rejected. Outbound requests allow only public destinations and do not forward caller cookies or authorization. Rate, lifetime and size limits apply.

Optional model_family, model, provider, framework, agent_id, session_id, experiment_id, parent_request_id can be query values or X-Agent-<hyphenated-name> headers. All identity metadata is SELF-REPORTED, never verified. X-Request-ID and W3C traceparent can correlate requests.

Operational logs store request metadata, hashed IPs, raw-value-free query summaries and payload hashes. Logs omit bearer credentials, cookies, private mail bodies and response secrets. Private administrators can review retained page and screenshot artifacts. Do not submit private or sensitive data. Mail expires within 24 hours. Page/screenshot private artifact retention is seven days by default; audit retention is 30 days. Public /admin and /internal routes are blocked by deployment.