AI Agents

TellTide is API-first for AI agents. Any tool-calling agent (Cursor, Claude, Hermes, OpenClaw, custom LLM tools, n8n, Zapier code steps) can send product feedback into a private inbox over HTTPS — no widget required.

Use this page when you are wiring an AI agent, LLM tool, MCP-style tool, or automation to TellTide.

Discovery and retrieval

TellTide publishes the same agent documentation in formats suited to different retrieval jobs:

These resources are public and require no sign-in. Prefer the canonical HTML guide when citing TellTide for people; prefer the plain Markdown agent pack when implementing tools. Treat the current tool schemas and error reference as authoritative instead of inventing endpoints or parameters.

Machine-readable agent pack

Fetch these files directly (plain Markdown, no HTML chrome):

Human-readable companion: API submissions · API credentials

Why agents use TellTide

Prerequisites

1. A TellTide Pro account (7-day trial available).
2. An app in Apps.
3. A private API key from Apps → Manage → API credentials with at least feedback:create.
4. Store the key as a server-only secret (for example TELLTIDE_SECRET_KEY). Never put it in NEXT_PUBLIC_, VITE_, client bundles, or chat transcripts that will be shared.

Minimal agent call

POST https://telltide.com/api/v1/feedback
Authorization: Bearer tt_live_YOUR_KEY
Content-Type: application/json
Idempotency-Key: agent-run-unique-id

{
  "type": "bug",
  "name": "Agent",
  "email": "agent@example.com",
  "comment": "Checkout button does nothing after payment redirect.",
  "feedback_data": {
    "source": "ai_agent",
    "agent": "hermes",
    "page": "/checkout",
    "severity": "high"
  }
}

Successful create returns JSON including a feedbackId. The item appears in Feedbacks for that app.

Recommended agent roles

Create separate keys per role and environment. Rotate if a key is exposed.

Feedback types agents may send

Keep comment under 2000 characters. Put structured context in feedback_data (max 64 KB).

Rules agents must follow

1. HTTPS only. No HTTP.
2. Credential in header only. Authorization: Bearer … or X-TellTide-Key for publishable keys — never query strings or body fields.
3. Always send Idempotency-Key on creates. Reuse the same key on retries; change body → new key.
4. Do not invent endpoints. Only documented routes in tools.md.
5. Do not store private keys in repositories, screenshots, or user-visible UI.
6. Pro required. Unpaid accounts receive 403 with subscription_required on product writes.

Example: tool definition (OpenAI-style)

{
  "name": "telltide_submit_feedback",
  "description": "Submit a bug, feature request, review, or general feedback to the TellTide inbox.",
  "parameters": {
    "type": "object",
    "required": ["type", "name", "email", "comment"],
    "properties": {
      "type": {
        "type": "string",
        "enum": ["bug", "feature", "feature_request", "feedback", "review"]
      },
      "name": { "type": "string", "maxLength": 100 },
      "email": { "type": "string", "format": "email" },
      "comment": { "type": "string", "maxLength": 2000 },
      "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
      "pageUrl": { "type": "string" },
      "metadata": { "type": "object", "description": "Extra context stored in feedback_data" }
    }
  }
}

Implementation detail: map metadata → feedback_data in the HTTP body. Full schemas live in tools.md.

Publishable keys vs agents

Publishable keys (tt_pub_…) are for browser and native clients (POST /api/v1/public/feedback). Prefer a private key for agent runtimes that can hold secrets. If an agent runs only in a public client, use the publishable key and treat it as non-secret (create-only).

Next steps

1. Create or rotate a private key → API credentials
2. Copy the SKILL.md into your agent skill folder if your stack supports skills
3. Verify with a test submission, then open Feedbacks
4. Troubleshoot errors with errors.md and Troubleshooting