# tell.st — A space to talk with your users.

> Install a single script to open a conversation space on your website. Visitors share feedback without registering. Verified owners can reply, manage private reports and update status; followers can receive updates. A homepage badge works without JavaScript, and a meta tag verifies ownership without adding an entry.

## Core Capabilities & Architecture

- **Address-Bar Prefix Routing (`tell.st/[domain]`)**: Prepending `https://tell.st/` to any domain or URL opens its public visual feedback board with PSL + multi-tenant host isolation (`github.io`, `vercel.app`, `pages.dev`, etc.).
- **Optional Page Markers & AI Prompts**: Feedback can include optional DOM selectors, layout details and images. These provide context for AI prompts and coding agents.
- **Explicit Ownership Verification**: Sign in, install the account-specific script, homepage badge anchor or meta tag, then click Verify in the dashboard. Visitor heartbeats and plain share badges never claim a site. The Shadow DOM isolated widget is `under 20 KiB` gzipped.
- **Public and Private Feedback**: Reporters can mark sensitive reports as `isPrivate: true` to restrict on-platform access to the authorized author, verified site owner, platform administrator and tools with a valid site token. An agent connected to the owner’s account can read private feedback through MCP. On verified sites, the owner and configured alert addresses can receive new private feedback and visitor comments by email, including the report text and page path. [Private feedback and notifications](https://tell.st/privacy#private-feedback).

Ratings and site reviews are deferred. The badge is a static feedback link without ratings or counts.

## Key Documentation & Entry Points

- [tell.st home](https://tell.st/): See a conversation example and how to connect a website.
- [Full LLM Specification & API Reference (llms-full.txt)](https://tell.st/llms-full.txt): REST endpoints, MCP tool arguments and result formats. The server exposes the current tool schemas through tools/list.
- [Developer Docs & MCP Guide](https://tell.st/docs): Complete integration guide for site owners, AI agents, and CI/CD pipelines.
- [Browser Extension & 1-Click Bookmarklet](https://tell.st/extension): Download the Chrome/Edge Manifest V3 extension (`/tell-st-extension.zip`) or drag the zero-install bookmarklet to pin DOM elements on any website.
- [Site Owner Dashboard & Verification](https://tell.st/app): Generate your `data-key`, verify your homepage, configure Slack/Discord/JSON Webhooks, and unlock private reports.
- [Official Widget Script (`w.js`)](https://tell.st/w.js): Lightweight host shell for the shared embedded interaction space.
- [Global RSS 2.0 Feed](https://tell.st/feed.xml): RSS feed of up to 50 recent public feedback reports.
- [XML Sitemap](https://tell.st/sitemap.xml): Includes up to 40 site boards, with up to 50 public feedback permalinks per listed site.

## Public API & MCP Endpoints

Feedback lists default to 25 items (limit 1–100). Pass nextCursor as cursor with unchanged filters. Exports return at most 100 items per page; follow the Link response header or X-Next-Cursor. Private access is reauthorized on every page.

- `POST https://tell.st/api/mcp`: Model Context Protocol (MCP) JSON-RPC 2.0 endpoint supporting account OAuth (PKCE) and legacy scoped site tokens, exposing `get_site_setup`, `verify_site_claim`, `list_site_pins`, `get_pin_fix_prompt`, `resolve_pin`, `delete_pin`, and `create_pin` (supports `Authorization: Bearer` header).
- `GET https://tell.st/api/pins?domain={domain}`: Returns site status, feedback and its processing status for a domain.
- `POST https://tell.st/api/pins`: Creates generic feedback with optional DOM context, image and retry-safe submissionId (rate-limited, supports Turnstile verification and automatic Webhook dispatch).
- `GET https://tell.st/api/pins/export?domain={domain}&format={md|csv|json}`: Exports feedback for a domain in Markdown, CSV, or JSON.
- `GET https://tell.st/api/badge/{domain}`: Static feedback-link SVG badge; no rating or live counts.
- `GET https://tell.st/api/feed/{domain}`: Per-domain RSS 2.0 XML feed.
- `GET https://tell.st/api/og/pin/{shortId}`: Generates dynamic SVG OpenGraph social cards for any pin.

## Live Domain Boards Index

- [realtest.org Public Feedback Board](https://tell.st/realtest.org): 1 total pins (Official Claimed Site)
- [cle.st Public Feedback Board](https://tell.st/cle.st): 1 total pins (Official Claimed Site)
- [tell.st Public Feedback Board](https://tell.st/tell.st): 1 total pins (Official Claimed Site)
- [nologin.tools Public Feedback Board](https://tell.st/nologin.tools): 0 total pins (Official Claimed Site)
- [30s.to Public Feedback Board](https://tell.st/30s.to): 0 total pins (Official Claimed Site)

## Recent Public Feedback

- [realtest.org/ (#dc2136314c39386b)](https://tell.st/p/dc2136314c39386b): Great Job ～ (Status: open, Upvotes: 1)
- [cle.st/ (#c01a8e585124b2bc)](https://tell.st/p/c01a8e585124b2bc): 👍 期待！ (Status: open, Upvotes: 1)
- [tell.st/ (#ed5681a0c0420a72)](https://tell.st/p/ed5681a0c0420a72): Hello World！ (Status: open, Upvotes: 1)

## Optional

- [About tell.st](https://tell.st/about): How visitors and site owners discuss feedback and follow progress.
- [AI Discovery Summary JSON](https://tell.st/ai/summary.json): Structured machine-readable service overview.
- [AI Discovery FAQ JSON](https://tell.st/ai/faq.json): Structured Q&A for answer engines.
- [Privacy Policy](https://tell.st/privacy): Data collection, cookies, and reporter privacy controls.
- [Terms of Service](https://tell.st/terms): Platform rules, moderation, and acceptable use.