Skip to content

For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/create-transcript-assistant-feedback.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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

FieldTypeRequiredDescription
#project_idstringRequired: YesUnique identifier of the project.
#generation_idstringRequired: YesUnique identifier of the generation within the project.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional 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

FieldTypeRequiredDescription
#kindstringRequired: NoWhat the report is: bug, feature (an idea) or other. Any other value is recorded as other.bugfeatureother
#messagestringRequired: NoThe person's note (up to 4,000 characters; longer text is cut).
#turn_idstringRequired: NoThe assistant turn the report is about, from Ask the edit assistant; it must be a turn of this generation.
#include_conversationbooleanRequired: NoSet true to attach conversation to the report; otherwise conversation is ignored.
#conversationarrayRequired: NoThe chat as the person saw it, oldest first; the newest 80 turns are kept and malformed entries are dropped.Fields below
#page_urlstringRequired: NoThe page the report was written on (up to 500 characters kept).
#user_agentstringRequired: NoThe person's browser (up to 300 characters kept).
#sourcestringRequired: NoWhere the report was written, for example panel (the default; up to 40 characters kept).
conversation[] 5 fields
FieldTypeRequiredDescription
#conversation[].rolestringRequired: YesWho wrote the turn.userassistant
#conversation[].textstringRequired: NoThe turn's text (up to 4,000 characters kept).
#conversation[].errorstringRequired: NoAn error shown with the turn, if any (up to 500 characters kept).
#conversation[].momentsintegerRequired: NoHow many moments the answer showed.
#conversation[].proposalsarrayRequired: NoThe answer's proposals as shown (up to 20): title, changes, accepted, skipped and examples.

Request

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

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"
  }'

Response

Returns 201 Created with the recorded transcript_assistant_feedback.

Success: 201Created.

Response fields

FieldTypePresentDescription
#objectstringAlwaysResource type, always "transcript_assistant_feedback".transcript_assistant_feedback
#idstringAlwaysIdentifier of the recorded report.
#project_idstringAlwaysIdentifier of the project.
#generation_idstringAlwaysIdentifier of the generation.
#turn_idstring | nullAlwaysThe assistant turn the report is about, or null.
#emailedbooleanAlwaystrue when the report reached the Diffio team by email; false when only the record was kept (the team still sees it).

Response 201Created.

Successful response
{
  "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

  • 201Created.Report recorded (and emailed to the Diffio team when emailed is true).
  • 400Bad request.
    Malformed JSON, or 3 more causes
    • Malformed JSON
    • Neither a message nor an included conversation
    • A turn_id that is not a turn id
    • Oversized header
    invalid_jsoninvalid_fieldinvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks generations:write. permission_denied
  • 404Not found.
    Project not found, or 2 more causes
    • Project not found
    • Generation not found
    • turn_id names no turn of this generation
    project_not_foundgeneration_not_foundtranscript_assistant_turn_not_found
  • 429Too many requests.More than 10 reports in an hour from this end user, or this account without Diffio-End-User. rate_limited
  • 502Bad gateway.Diffio could not record the report; retry with backoff. internal_error
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
    • 405Client error. 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 401Unauthorized: the API key is missing or invalid.:

Error response
{
  "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.

Report an issue with this page