# TellTide tools

HTTP tools for AI agents. Base URL: `https://telltide.com`.

Env: `TELLTIDE_SECRET_KEY` = private key (`tt_live_…` or `tt_test_…`).

---

## telltide_submit_feedback

Submit one feedback item to the TellTide inbox.

### When to call

User or agent workflow needs to file a bug, feature request, review, or general feedback.

### HTTP

```
POST /api/v1/feedback
Authorization: Bearer ${TELLTIDE_SECRET_KEY}
Content-Type: application/json
Idempotency-Key: ${idempotency_key}
```

### Parameters

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `type` | string | yes | `bug` \| `review` \| `feedback` \| `feature` \| `feature_request` |
| `name` | string | yes | Reporter display name, ≤100 |
| `email` | string | yes | Valid email, ≤254 |
| `comment` | string | yes* | Human summary, ≤2000 (*required for useful triage; send non-empty) |
| `rating` | integer | no | 1–5; mainly for `review` |
| `pageUrl` | string | no | Page or surface URL, ≤2048 |
| `feedback_data` | object | no | Extra JSON context, ≤64KB |
| `idempotency_key` | string | yes | Unique per logical create; reuse on retry |

### Example

```bash
curl -sS https://telltide.com/api/v1/feedback \
  -H "Authorization: Bearer $TELLTIDE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "bug",
    "name": "Agent",
    "email": "agent@example.com",
    "comment": "Export CSV hangs on large workspaces.",
    "feedback_data": {"source":"ai_agent","surface":"export"}
  }'
```

### OpenAI-style function schema

```json
{
  "type": "function",
  "function": {
    "name": "telltide_submit_feedback",
    "description": "Submit bug, feature request, review, or feedback to TellTide.",
    "parameters": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type", "name", "email", "comment", "idempotency_key"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["bug", "feature", "feature_request", "feedback", "review"]
        },
        "name": { "type": "string", "maxLength": 100 },
        "email": { "type": "string", "format": "email", "maxLength": 254 },
        "comment": { "type": "string", "maxLength": 2000 },
        "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
        "pageUrl": { "type": "string", "maxLength": 2048 },
        "feedback_data": { "type": "object" },
        "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 128 }
      }
    }
  }
}
```

---

## telltide_list_feedback

List feedback for the key's app. Requires scope `feedback:read`.

### HTTP

```
GET /api/v1/feedback
Authorization: Bearer ${TELLTIDE_SECRET_KEY}
```

Use only when the user explicitly wants the agent to read inbox data.

---

## telltide_get_feedback

Fetch one item. Requires `feedback:read`.

### HTTP

```
GET /api/v1/feedback/{feedbackId}
Authorization: Bearer ${TELLTIDE_SECRET_KEY}
```

---

## telltide_update_feedback

Patch status / fields. Requires `feedback:update`.

### HTTP

```
PATCH /api/v1/feedback/{feedbackId}
Authorization: Bearer ${TELLTIDE_SECRET_KEY}
Content-Type: application/json
```

Allowed update fields (subset): `status`, `type`, `comment`, `feedback_data`, `priority`, `internal_note`, `roadmap_status`.

Do not enable this tool unless the user asked for triage automation.

---

## telltide_delete_feedback

Permanently delete. Requires `feedback:delete`. Prefer human confirmation before calling.

### HTTP

```
DELETE /api/v1/feedback/{feedbackId}
Authorization: Bearer ${TELLTIDE_SECRET_KEY}
```

---

## Publishable submit (browser / native only)

```
POST /api/v1/public/feedback
X-TellTide-Key: tt_pub_…
Content-Type: application/json
Idempotency-Key: …
```

Same body shape as `telltide_submit_feedback`. Prefer private keys for server-side agents.