# TellTide memory

Durable facts for agents. Prefer this file over guessing.

## Identity

- **Product:** TellTide — feedback widget, private inbox, optional public roadmap.
- **Site:** https://telltide.com
- **API host:** `https://telltide.com` (no other production API host).
- **Docs (agents):** https://telltide.com/docs/integration/ai-agents
- **Docs (HTTP examples):** https://telltide.com/docs/integration/api-submissions
- **Docs (keys):** https://telltide.com/docs/api-tokens
- **Agent pack:** https://telltide.com/agents/

## Auth model

| Credential | Prefix | Where | Header | Capability |
|------------|--------|-------|--------|------------|
| Publishable | `tt_pub_` | Browser / native / public clients | `X-TellTide-Key` | Create only → `POST /api/v1/public/feedback` |
| Private | `tt_live_` / `tt_test_` | Trusted server / agent runtime | `Authorization: Bearer …` | Explicit scopes on `/api/v1/feedback*` |

- Private keys are secrets. Shown once at creation; TellTide stores a hash.
- Keys are **app-bound**. Do not cross apps with one key.
- Dashboard session auth (Clerk) is separate from API keys. Agents should use API keys, not cookie sessions.

## Scopes (private keys)

| Scope | Allows |
|-------|--------|
| `feedback:create` | Create feedback |
| `feedback:read` | List / get feedback |
| `feedback:update` | Patch feedback (status, etc.) |
| `feedback:delete` | Delete feedback |

Default agent key: **`feedback:create` only**.

## Endpoints agents care about

| Method | Path | Auth |
|--------|------|------|
| `POST` | `/api/v1/feedback` | Private Bearer |
| `POST` | `/api/v1/public/feedback` | Publishable `X-TellTide-Key` |
| `GET` | `/api/v1/feedback` | Private + `feedback:read` |
| `GET` | `/api/v1/feedback/:id` | Private + `feedback:read` |
| `PATCH` | `/api/v1/feedback/:id` | Private + `feedback:update` |
| `DELETE` | `/api/v1/feedback/:id` | Private + `feedback:delete` |

Always send `Idempotency-Key` on creates.

## Feedback types

`bug` · `review` · `feedback` · `feature` · `feature_request`

## Limits (create)

| Field | Limit |
|-------|-------|
| `name` | 100 chars |
| `email` | 254 chars |
| `comment` | 2000 chars |
| `pageUrl` | 2048 chars |
| `feedback_data` | 64 KB JSON |
| Image attach | PNG/JPEG, max 5 MB (optional) |
| Request body | 8 MB max |

## Commercial gate

- Active **Pro** (or trial) required for product writes.
- Unpaid → `403` / `subscription_required`.
- No forever-free plan.

## Positioning

TellTide is for **collect → triage → ship** feedback loops, not a heavy planning suite. Agents submit signal; humans (or triage agents) decide what goes to the public roadmap.