# Feedback

Feedback turns a versioned task and its items into private review links. Each signed-in owner can create task sets, issue separate reviewer links, and read only their own results.

## Agent workflow

When a user asks you to create a task set, help them shape their source data, editable output, review instructions, and capture policy into the JSON contract below. Ask the owner to sign in at https://feedback.clavia.ai/owner and create an API key. The API key starts with `fdb_` and is shown once. Treat it as a secret.

Use `Authorization: Bearer $FEEDBACK_API_KEY` for every `/api/v1` request. The complete OpenAPI document is at https://feedback.clavia.ai/openapi.json.

1. Upload binary files with `POST /api/v1/assets`. Send the bytes as the body, the file name in `X-File-Name`, and the media type in `Content-Type`. Add every returned asset ID to `assetIds` and use the returned asset reference in item input.
2. Optionally call `POST /api/v1/presentations/suggest` with representative `sampleInput` and `sampleOutput` values. Review the suggested presentation before using it.
3. Create one immutable task set with `POST /api/v1/task-sets`.
4. Create a private assignment for each reviewer with `POST /api/v1/task-sets/{taskSetId}/review-links`. Send `{"count":2}` for two reviewers. The configured limit is 50 links per request.
5. Keep every returned review URL private. Give a different URL to each reviewer. Separate packets prevent drafts, recordings, and submissions from overwriting one another.
6. List assignments with `GET /api/v1/task-sets/{taskSetId}/packets`. Read a packet with `GET /api/v1/packets/{packetId}`, submitted revisions with `GET /api/v1/packets/{packetId}/submissions`, and in-progress voice and DOM capture with `GET /api/v1/packets/{packetId}/checkpoints`.
7. Read `GET /api/v1/packets/{packetId}/analysis` for a compact timeline that joins transcript timestamps, file events, reconstructed DOM targets, submissions, file changes, pointer hotspots, and recording-noise counts.

## Task-set contract

The request body contains `task`, `job`, and `items`. It may also contain `assetIds` and a default `expiresAt` Unix timestamp in milliseconds.

- `task.instructions` is shown during setup and can be reopened from the Instructions button in the review workspace. Explain what reviewers will see, what they may edit, and what a useful review means. The first file path named in the instructions opens when the workspace starts.
- `task.inputSchema` validates each item input. Supported JSON Schema fields are `type`, `title`, `description`, `enum`, `properties`, `required`, `items`, `minLength`, `maxLength`, `minimum`, `maximum`, and `additionalProperties`.
- `task.outputSchema` validates the submitted result. JSON files must parse before submission.
- `task.presentation.input` accepts `field`, `conversation`, `document`, and `file-set` blocks. Paths are JSON Pointer paths into item input. `sourcePath` places a source in the review file tree.
- `task.presentation.output` can be a single editable `file`, an editable `workspace` that points to a presented file set, a structured `form`, or an editable `document`.
- File-set entries contain `path`, `mediaType`, and `content`. Editable text types are `application/json`, `text/markdown`, and `text/plain`. Uploaded PDFs, DOCX files, images, and other binary sources use asset references.
- For direct file review, put every editable file in one file set and point a workspace output at it. The suggestion endpoint does this automatically when the sample input contains one file set. Do not add actions, a form output, or a separate `task.json` unless the owner asks for structured labels.
- The submitted `files` object is the complete revised workspace. A source path missing from that object is a reviewer deletion. The source revision remains unchanged.
- `task.presentation.actions` declares any explicit reviewer decisions. Use an empty array when direct file edits and think-aloud reasoning are enough.
- Set `task.presentation.reasoning.visible` to `false` when voice replaces written notes. A hidden reasoning field must have `required: false`.
- Every task requires microphone consent, page recording consent, the microphone check, spotlight practice, and spotlight on by default. The server rejects task sets that disable these review requirements. Raw audio is discarded after transcription. `confirmUnchangedSubmission` defaults to `true` and controls the extra confirmation for a task with no file changes.
- Each item has a stable `id`, immutable `revision`, input, generated starting value, and provenance. Use `user-supplied`, `unknown`, or a provider, model, prompt version, and policy version object.

## Complete example

`POST https://feedback.clavia.ai/api/v1/task-sets`

```json
{
  "task": {
    "id": "contract-review",
    "version": 1,
    "name": "Contract review",
    "instructions": "Review the source and improve the draft. Think aloud while you work.",
    "inputSchema": {
      "type": "object",
      "required": [
        "source",
        "editableFiles"
      ],
      "properties": {
        "source": {
          "type": "string"
        },
        "editableFiles": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "path",
              "mediaType",
              "content"
            ],
            "properties": {
              "path": {
                "type": "string"
              },
              "mediaType": {
                "type": "string"
              },
              "content": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "outputSchema": {
      "type": "object",
      "additionalProperties": true
    },
    "presentation": {
      "version": "contract-workspace-v1",
      "input": [
        {
          "kind": "field",
          "path": "/source",
          "label": "Source",
          "sourcePath": "Source/source.txt",
          "display": "long-text"
        },
        {
          "kind": "file-set",
          "path": "/editableFiles",
          "label": "Draft files",
          "sourcePath": "Drafts"
        }
      ],
      "output": {
        "kind": "workspace",
        "filesPath": "/editableFiles"
      },
      "actions": [],
      "reasoning": {
        "required": false,
        "label": "Reasoning",
        "visible": false
      }
    },
    "policy": {
      "domRecording": "consent-required",
      "voiceCapture": "consent-required",
      "audioRetention": "discard-after-transcription",
      "spotlight": "available",
      "spotlightDefault": "on"
    }
  },
  "job": {
    "id": "contract-review-august",
    "snapshot": 1
  },
  "items": [
    {
      "id": "matter-001",
      "revision": 1,
      "input": {
        "source": "Review this source material.",
        "editableFiles": [
          {
            "path": "draft.json",
            "mediaType": "application/json",
            "content": "{\n  \"status\": \"draft\"\n}"
          }
        ]
      },
      "generated": {
        "value": {
          "draft.json": {
            "status": "draft"
          }
        },
        "provenance": "user-supplied"
      }
    }
  ]
}
```

Create review links after the task-set request returns `taskSetId`:

```sh
curl https://feedback.clavia.ai/api/v1/task-sets/TASK_SET_ID/review-links \
  -X POST \
  -H "Authorization: Bearer $FEEDBACK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"count":2}'
```

The plaintext review tokens appear only in that response. Store them securely. Task sets, source revisions, and submissions are immutable. Create a new task version or item revision for corrections.