> ## Documentation Index > Fetch the complete documentation index at: https://docs.corti.ai/llms.txt > Use this file to discover all available pages before exploring further. # Submit feedback for a task > Submits feedback about a task as a whole or about a specific user-visible message within the task. The task must exist, belong to the supplied context, and belong to the authenticated customer. Multiple feedback resources may be submitted for the same task or message. ## OpenAPI ````yaml /agentic/auto-generated-openapi-v2.yml post /v2/agentic/contexts/{contextId}/tasks/{taskId}/feedback openapi: 3.1.0 info: title: Corti Agent API v2 version: 2.0.0 summary: Manage agents and converse with them over the A2A v1.0 protocol. description: > Version 2 of the Corti Agents REST API. ## What's new in v2 - **Unified `connectors`** — a single, flat, discriminated array replaces the v1 split between `experts`, `mcpServers`, and sub-agents. The envelope is extensible: new connector kinds (`a2a`, `openapi`, `custom`) slot in behind the `type` discriminator without breaking changes. - **Clean CRUD verbs** — `POST` creates, `GET` fetches/lists, `PATCH` performs a *true* partial update, `DELETE` removes. v1's PATCH was effectively a PUT. - **First-class metadata** — `visibility`, `model`, `lifecycle` (now a body field, not a query param), and free-form `labels`. ## A2A v1.0 only The conversational surface speaks **A2A protocol version `1.0` exclusively** (both the `JSONRPC` and `HTTP+JSON` bindings). The deprecated v0.3 binding from v1 is intentionally not carried forward. Per A2A §3.6, clients MUST send the `A2A-Version` header (`Major.Minor`, e.g. `1.0`) on every request to the `/a2a/*` surface, or supply it as the `A2A-Version` query parameter. This surface implements `1.0` only; an absent header is treated as `1.0`. Patch versions MUST NOT be sent. The server echoes the negotiated version in the `A2A-Version` response header. ## Partial updates (PATCH) `PATCH` uses **JSON Merge Patch** semantics (RFC 7386), served under the `application/merge-patch+json` media type: - **Omit a field** → left unchanged. - **`null`** → cleared / reset to its default. - **Arrays** (e.g. `connectors`) → *replaced wholesale*, never merged. To mutate a single connector without replacing the whole array, use the `/connectors` sub-resource endpoints. ## Streaming (Server-Sent Events) The streaming A2A surfaces — `message/stream`, `tasks/subscribe`, and the streaming JSON-RPC methods — respond with `text/event-stream`. The `text/event-stream` media type carries a sequence of Server-Sent Events; the attached schema describes a single event frame. Every event's `data` field is a string carrying a JSON document (`contentMediaType: application/json`); `contentSchema` declares the parsed payload (`StreamResponse` for the `HTTP+JSON` binding, `JSONRPCResponse` for the `JSONRPC` binding). The optional `id` field carries the SSE event id used for resumption via the `Last-Event-ID` request header. contact: name: Corti API Support url: https://corti.ai email: support@corti.ai license: name: Proprietary url: https://corti.ai/terms termsOfService: https://corti.ai/terms servers: - url: https://api.{env}.corti.app description: Corti regional API gateway variables: env: default: eu enum: - eu - us description: Deployment region. security: - bearerAuth: [] tenantHeader: [] tags: - name: Agents description: Create, read, update, and delete agents. - name: Agent Card description: A2A-compliant agent discovery cards. - name: A2A description: Converse with an agent over the A2A v1.0 protocol. - name: Connectors description: Manage the connectors attached to an agent. - name: Usage description: Bucketed invocation history for an agent. - name: Contexts description: Conversational contexts and their tasks. - name: Registry description: Discoverable, pre-built connectors offered by the platform. - name: Artifacts description: Retrieve artifacts produced by tasks. - name: Feedback description: Collect human or automated feedback on tasks and messages. paths: /v2/agentic/contexts/{contextId}/tasks/{taskId}/feedback: parameters: - $ref: '#/components/parameters/ContextId' - $ref: '#/components/parameters/TaskId' post: tags: - Feedback summary: Submit feedback for a task description: > Submits feedback about a task as a whole or about a specific user-visible message within the task. The task must exist, belong to the supplied context, and belong to the authenticated customer. Multiple feedback resources may be submitted for the same task or message. operationId: FeedbackCreate requestBody: required: true description: The feedback to submit. content: application/json: schema: $ref: '#/components/schemas/FeedbackCreateRequest' examples: minimal: $ref: '#/components/examples/FeedbackCreateMinimalExample' detailed: $ref: '#/components/examples/FeedbackCreateDetailedExample' responses: '201': description: Feedback created. headers: Location: description: Canonical URL of the created feedback resource. schema: type: string format: uri content: application/json: schema: $ref: '#/components/schemas/FeedbackResponse' example: id: fb.0192f4c8-9a3b-7e2f-9c4d-5a6b7c8d9e0f taskId: task.0192f4c8-4e7c-7d50-b13c-5eaf8a4d9c62 rating: scale: binary value: 1 normalizedScore: 1 labels: [] createdAt: '2026-05-19T12:00:00Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' components: parameters: ContextId: name: contextId in: path required: true description: Context identifier (prefixed UUIDv7). schema: $ref: '#/components/schemas/CommonContextIDValue' TaskId: name: taskId in: path required: true description: Task identifier (prefixed UUIDv7). schema: $ref: '#/components/schemas/CommonTaskIDValue' schemas: FeedbackCreateRequest: type: object description: Request body for submitting task feedback. required: - rating properties: rating: $ref: '#/components/schemas/FeedbackRating' labels: type: array description: > Structured observations about the result. Defaults to an empty array. Positive and negative labels may be combined. Duplicate labels are rejected. A maximum of five labels may be submitted. items: $ref: '#/components/schemas/FeedbackLabel' maxItems: 5 uniqueItems: true default: [] reason: type: string maxLength: 1000 description: > The user's explanation of the rating or labels. Required when `labels` contains `other`. examples: - The response stated the patient had diabetes - but this was not present in the available data. target: $ref: '#/components/schemas/FeedbackTarget' metadata: $ref: '#/components/schemas/FeedbackMetadata' additionalProperties: false FeedbackResponse: type: object description: A stored feedback resource. required: - id - taskId - rating - normalizedScore - labels - createdAt properties: id: $ref: '#/components/schemas/FeedbackIDValue' taskId: $ref: '#/components/schemas/CommonTaskIDValue' rating: $ref: '#/components/schemas/FeedbackRating' normalizedScore: type: number format: double minimum: 0 maximum: 1 description: | Corti-derived internal score between 0 and 1. The original scale and value are always retained alongside this score. example: 1 labels: type: array items: $ref: '#/components/schemas/FeedbackLabel' description: Structured observations about the result. examples: - - correct - helpful reason: type: string maxLength: 1000 description: Free-text explanation of the rating or labels. examples: - The response stated the patient had diabetes - but this was not present in the available data. target: $ref: '#/components/schemas/FeedbackTarget' metadata: $ref: '#/components/schemas/FeedbackMetadata' createdAt: type: string format: date-time readOnly: true description: When the feedback was created. example: '2026-05-19T12:00:00Z' CommonContextIDValue: type: string format: context-id description: >- Context identifier. Accepts `ctx.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(ctx\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - ctx.0192f4c8-3d6b-7c4f-a02b-4d9e7f3c8b51 CommonTaskIDValue: type: string format: task-id description: >- Task identifier. Accepts `task.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(task\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - task.0192f4c8-4e7c-7d50-b13c-5eaf8a4d9c62 FeedbackRating: type: object description: The original rating supplied by the customer. required: - scale - value properties: scale: $ref: '#/components/schemas/FeedbackRatingScale' value: type: number format: double description: The rating value on the selected scale. additionalProperties: false examples: - scale: binary value: 1 FeedbackLabel: type: string description: > Structured observation about the result. Positive and negative labels share one taxonomy so customers can represent mixed feedback. - `correct` — factually and contextually correct (positive). - `complete` — included the important expected information (positive). - `helpful` — materially helped the user complete their task (positive). - `wellPresented` — clear, readable, appropriately structured (positive). - `efficient` — reached a useful result without unnecessary content (positive). - `incorrect` — one or more claims, conclusions, or actions were wrong (negative). - `missingInformation` — important or expected information was omitted (negative). - `irrelevant` — included content that did not address the request (negative). - `misunderstoodRequest` — the system responded to the wrong intent (negative). - `unsupportedClaim` — a claim not supported by available information (negative). - `unsafeOrInappropriate` — unsafe, disallowed, or unsuitable (negative). - `poorlyPresented` — difficult to read or unsuitably structured (negative). - `tooVerbose` — substantially more detail than useful (negative). - `other` — another observation described in `reason` (both). enum: - correct - complete - helpful - wellPresented - efficient - incorrect - missingInformation - irrelevant - misunderstoodRequest - unsupportedClaim - unsafeOrInappropriate - poorlyPresented - tooVerbose - other FeedbackTarget: type: object description: | Identifies the specific user-visible response being evaluated. If omitted, the feedback applies to the task as a whole. required: - messageId properties: messageId: $ref: '#/components/schemas/CommonMessageIDValue' additionalProperties: false FeedbackMetadata: type: object description: Customer-provided provenance and correlation information. required: [] properties: collectionMethod: type: string maxLength: 100 description: >- How the customer collected the feedback. Informational only; does not affect rating validation or normalization. examples: - thumbs - survey clientReference: type: string maxLength: 255 description: | Customer-defined reference to correlate the feedback with an object in the customer's own system. Not unique and does not provide idempotency. Should not contain sensitive information. actor: $ref: '#/components/schemas/FeedbackActor' additionalProperties: false FeedbackIDValue: type: string format: feedback-id description: >- Feedback identifier. Accepts `fb.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(fb\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - fb.0192f4c8-7e2a-7b3c-9d4e-5f6a7b8c9d01 CommonErrorResponse: type: object description: > Corti management-plane error envelope, used by all non-A2A endpoints. - **Standard** — when the error chain contains at least one `PublicError`, `code` and `message` come from the outermost `PublicError` and `details` is merged across the whole chain (outer values take precedence). - **Fallback** — when the chain contains no `PublicError`, the response is a generic `500` carrying a `requestId` for support reference. - **Validation** — a single `PublicError` whose `details.validationErrors` lists the offending fields. Field names use camelCase on the wire (e.g. `requestId`, `howToFix`). The free-form `details` object may carry arbitrary caller-defined keys. Rate limiting (HTTP 429) is not yet implemented; the server does not emit a 429 response. required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable, machine-readable, SCREAMING_SNAKE_CASE error code. examples: - ASSIGNMENT_CONFLICT - VALIDATION_FAILED - INTERNAL_ERROR message: type: string description: Human-readable explanation. howToFix: type: string description: Optional guidance for the caller to resolve the error. details: type: object description: | Structured context, merged from every `PublicError` in the chain (outer values win). Omitted on the generic fallback response. additionalProperties: true properties: validationErrors: type: array description: Present when `code` is `VALIDATION_FAILED`. items: type: object required: - field - reason properties: field: type: string description: The field that failed validation. reason: type: string description: Why the field failed validation. requestId: type: string description: > Correlation ID from request middleware. Included only on the generic `500` fallback so consumers can quote it in support requests. description: The error object with code, message, and optional details. examples: - error: code: ASSIGNMENT_CONFLICT message: could not complete assignment details: assignment_id: asg_99 expert_id: exp_42 - error: code: VALIDATION_FAILED message: validation failed details: validationErrors: - field: email reason: invalid format - field: name reason: required - error: code: INTERNAL_ERROR message: internal server error requestId: req_abc123 FeedbackRatingScale: type: string description: > The scale on which the rating was collected. - `binary` — 0 (negative) or 1 (positive). Planned (not yet available): `likert5` (integer 1–5), `continuous01` (number 0–1). enum: - binary CommonMessageIDValue: type: string format: message-id description: >- Message identifier. Accepts `msg.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(msg\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - msg.0192f4c8-5f8d-7e61-924d-6fb09b5ead73 FeedbackActor: type: object description: Customer-defined opaque identifier for the feedback submitter. required: - externalId properties: externalId: type: string maxLength: 255 description: | Scoped to the authenticated customer; not globally unique and not independently verified. Should preferably be pseudonymous and must not contain names, emails, national identifiers, or medical record numbers. additionalProperties: false examples: FeedbackCreateMinimalExample: summary: Minimal binary positive rating description: >- The simplest possible feedback — a positive binary rating with no labels or reason. value: rating: scale: binary value: 1 FeedbackCreateDetailedExample: summary: Detailed report about a message description: >- A negative binary rating with labels, reason, message target, and full metadata. value: rating: scale: binary value: 0 labels: - unsupportedClaim reason: >- The response stated that the patient had diabetes, but this was not present in the available data. target: messageId: msg.0192f4c8-5f8d-7e61-924d-6fb09b5ead73 metadata: collectionMethod: caseReview clientReference: case-review-728193 actor: externalId: clinician_4182 responses: BadRequest: description: The request was malformed. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' Unauthorized: description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' NotFound: description: The resource does not exist or is not visible to the caller. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' UnprocessableEntity: description: The request was well-formed but semantically invalid. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: OAuth 2.0 / OIDC bearer token. tenantHeader: type: apiKey in: header name: Tenant-Name description: The tenant the request operates within. ````