> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/create-transcript-assistant-feedback/.

# Send assistant feedback

Sends the Diffio team a bug report, an idea or other feedback about the edit assistant on one generation (`201 Created`). Use it for the feedback form an assistant turn offers in `feedback_offer`.

POST `https://api.diffio.ai/v2/projects/{project_id}/generations/{generation_id}/transcript/assistant/feedback`

- Key scope: `generations:write`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: JSON

## Request

Send a `message`, the `conversation` with `include_conversation: true`, or both; a report with neither is refused.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | Unique identifier of the project. |
| `generation_id` | string | Yes | Unique identifier of the generation within the project. |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Optional end-user identifier (up to 128 characters). Scopes the request to that end user's projects and counts the report against that end user's limit; omit to act across the whole account. |

### Body fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | No | What the report is: `bug`, `feature` (an idea) or `other`. Any other value is recorded as `other`. |
| `message` | string | No | The person's note (up to 4,000 characters; longer text is cut). |
| `turn_id` | string | No | The assistant turn the report is about, from [Ask the edit assistant](https://diffio.ai/docs/api-reference/create-transcript-assistant-turn/); it must be a turn of this generation. |
| `include_conversation` | boolean | No | Set `true` to attach `conversation` to the report; otherwise `conversation` is ignored. |
| `conversation` | array | No | The chat as the person saw it, oldest first; the newest 80 turns are kept and malformed entries are dropped. [Fields below](#fields-conversation) |
| `page_url` | string | No | The page the report was written on (up to 500 characters kept). |
| `user_agent` | string | No | The person's browser (up to 300 characters kept). |
| `source` | string | No | Where the report was written, for example `panel` (the default; up to 40 characters kept). |

**`conversation[]` fields**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation[].role` | string | Yes | Who wrote the turn. Values: `user`, `assistant`. |
| `conversation[].text` | string | No | The turn's text (up to 4,000 characters kept). |
| `conversation[].error` | string | No | An error shown with the turn, if any (up to 500 characters kept). |
| `conversation[].moments` | integer | No | How many moments the answer showed. |
| `conversation[].proposals` | array | No | The answer's proposals as shown (up to 20): `title`, `changes`, `accepted`, `skipped` and `examples`. |

## Example request

The Python and Node.js SDKs have no helper for this endpoint yet; send it with cURL or any HTTP client.

**cURL**

```bash
curl -X POST "https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/transcript/assistant/feedback" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "feature",
    "message": "I want to cut the intro down to ten seconds.",
    "turn_id": "8f14e45fceea4e6b9d2c7a1b3e5d9f02",
    "include_conversation": true,
    "conversation": [
      {
        "role": "user",
        "text": "Shorten the intro to ten seconds."
      },
      {
        "role": "assistant",
        "text": "I can remove or replace words, but I cannot trim a passage to a set length."
      }
    ],
    "source": "panel"
  }'
```

**JSON: JSON body**

```json
{
  "kind": "feature",
  "message": "I want to cut the intro down to ten seconds.",
  "turn_id": "8f14e45fceea4e6b9d2c7a1b3e5d9f02",
  "include_conversation": true,
  "conversation": [
    {
      "role": "user",
      "text": "Shorten the intro to ten seconds."
    },
    {
      "role": "assistant",
      "text": "I can remove or replace words, but I cannot trim a passage to a set length."
    }
  ],
  "source": "panel"
}
```

## Response

Returns `201 Created` with the recorded `transcript_assistant_feedback`.

Success: `201`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"transcript_assistant_feedback"`. |
| `id` | string | Always | Identifier of the recorded report. |
| `project_id` | string | Always | Identifier of the project. |
| `generation_id` | string | Always | Identifier of the generation. |
| `turn_id` | string \| null | Always | The assistant turn the report is about, or `null`. |
| `emailed` | boolean | Always | `true` when the report reached the Diffio team by email; `false` when only the record was kept (the team still sees it). |

## Example response (201)

**Successful response**

```json
{
  "object": "transcript_assistant_feedback",
  "project_id": "73118d99-36cf-4039-8005-b962d522fff7",
  "generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7",
  "id": "kV2mR8sTq4LwZ1bN6yPd",
  "turn_id": "8f14e45fceea4e6b9d2c7a1b3e5d9f02",
  "emailed": true
}
```

## Return codes

- `201` Report recorded (and emailed to the Diffio team when `emailed` is `true`).
- `400`
  - Malformed JSON
  - Neither a `message` nor an included `conversation`
  - A `turn_id` that is not a turn id
  - Oversized header
  Codes: [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json), [`invalid_field`](https://diffio.ai/docs/api-reference/errors/#invalid_field), [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or lacks `generations:write`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404`
  - Project not found: [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found)
  - Generation not found: [`generation_not_found`](https://diffio.ai/docs/api-reference/errors/#generation_not_found)
  - `turn_id` names no turn of this generation: [`transcript_assistant_turn_not_found`](https://diffio.ai/docs/api-reference/errors/#transcript_assistant_turn_not_found)
- `429` More than 10 reports in an hour from this end user, or this account without `Diffio-End-User`. [`rate_limited`](https://diffio.ai/docs/api-reference/errors/#rate_limited)
- `502` Diffio could not record the report; retry with backoff. [`internal_error`](https://diffio.ai/docs/api-reference/errors/#internal_error)
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` HTTP method not supported on this path; check the Allow header (code method_not_allowed).

### Example error response

Errors are JSON: an `error` object with `code`, `message` and `request_id`. An unrecognized key returns `401`:

**Error response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}
```

## Notes

- When a completed turn has a `feedback_offer`, show a form prefilled with its `kind` and `summary`, then send what the person writes here with that turn's `id` as `turn_id`.
- Reports are not billed. Each end user (or the account, without `Diffio-End-User`) can send 10 reports per hour.

## Related pages

- Previous: [Get an edit assistant turn](https://diffio.ai/docs/api-reference/get-transcript-assistant-turn/): Poll an edit-assistant turn for its reply, word-level edit proposals, moments, or failure details.
- Next: [Publish a project's share](https://diffio.ai/docs/api-reference/publish-project-share/): Publish or update a project's public playback share, optionally pinned to one generation or preview length.

- [Full API guide](https://diffio.ai/docs/developers/full-api-guide/): Every topic, limit and concept in one index.
- [Billing](https://diffio.ai/docs/overview/administration/billing/): Starter credit, metering and invoices.
