# TellTide payloads

Request and response shapes for agent integrations.

## Create feedback (private)

`POST /api/v1/feedback`

### Request body

```json
{
  "type": "bug",
  "name": "Alex",
  "email": "alex@example.com",
  "comment": "Short description of the issue or idea.",
  "rating": 5,
  "pageUrl": "https://app.example.com/settings",
  "feedback_data": {
    "source": "ai_agent",
    "agent": "openclaw",
    "severity": "high",
    "context": {}
  }
}
```

| Field | Required | Notes |
|-------|----------|-------|
| `type` | yes | `bug` \| `review` \| `feedback` \| `feature` \| `feature_request` |
| `name` | yes | ≤100 |
| `email` | yes | ≤254 |
| `comment` | recommended | ≤2000 |
| `rating` | no | integer 1–5 |
| `pageUrl` | no | ≤2048 |
| `appId` | no | Must match key's app if sent |
| `feedback_data` | no | Object; ≤64KB; depth ≤5; ≤50 keys |
| `imageUrl` | no | Optional PNG/JPEG data URL; ≤5MB |

Reserved `feedback_data` keys (do not set): `activity_log`, `internal_notes`, `priority_level`, `screenshot_id`.

### Headers

```
Authorization: Bearer tt_live_…
Content-Type: application/json
Idempotency-Key: <unique>
```

### Success

HTTP `200` or `201` with JSON including a feedback identifier (commonly `feedbackId`) and a short message. Treat any 2xx with an id as success.

## Create feedback (publishable)

`POST /api/v1/public/feedback`

Same body. Header:

```
X-TellTide-Key: tt_pub_…
Idempotency-Key: <unique>
```

## Update feedback

`PATCH /api/v1/feedback/:feedbackId`

```json
{
  "status": "in_progress",
  "priority": "high",
  "internal_note": "Reproduced on staging."
}
```

`status` examples: `new`, `open`, `in_progress`, `resolved`, `closed`, `rejected`, `on_hold`, `declined`.

`roadmap_status` examples: `received`, `evaluating`, `scheduled`, `in_progress`, `completed`, `declined` (when roadmap features are used).

## List / get

`GET /api/v1/feedback` — array or list payload for the credential's app.  
`GET /api/v1/feedback/:feedbackId` — single mapped feedback object.

## Error envelope

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "Human-readable explanation.",
    "requestId": "req_..."
  }
}
```

Always preserve `requestId` when reporting failures to a human.