> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete a review-project conversation

> Validate the conversation's required review values and mark it complete for the acting reviewer. A successful response can still report blockers when completion requirements have not been satisfied.



## OpenAPI

````yaml /api-reference/v1/reviews-v1.yaml post /review-projects/{project_id}/complete-conversation
openapi: 3.0.3
info:
  title: Coval Reviews API
  version: 1.0.0
  description: >
    Manage human review annotations and projects for AI evaluation quality
    assurance.


    **Annotations** are saved review data for a simulation output, metric, and

    reviewer, including ground-truth values and notes.


    **Projects** organize review assignments by linking simulations, metrics,
    and

    assignees. Creating a project defines assignments for the configured

    (simulation, metric, assignee) combinations, not saved annotations.

    Submit review data through the annotation API, then use the returned
    annotation

    ID for later updates.


    Key concepts:

    - Review assignments and saved annotations are separate resources

    - Annotation completion depends on saved ground truth and applicable project
    rules

    - Resource naming: `review-annotations/{id}`, `review-projects/{id}`
  contact:
    name: Coval API Support
    email: support@coval.dev
    url: https://docs.coval.ai
  license:
    name: Proprietary
    url: https://coval.dev/terms
servers:
  - url: https://api.coval.dev/v1
    description: Production API
security:
  - ApiKeyAuth: []
tags:
  - name: Review Annotations
    description: Annotation CRUD operations
  - name: Review Projects
    description: Project CRUD operations
paths:
  /review-projects/{project_id}/complete-conversation:
    parameters:
      - $ref: '#/components/parameters/WorkspaceId'
    post:
      tags:
        - Review Projects
      summary: Complete a review-project conversation
      description: >-
        Validate the conversation's required review values and mark it complete
        for the acting reviewer. A successful response can still report blockers
        when completion requirements have not been satisfied.
      operationId: completeReviewConversation
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
          description: Review project ID (ULID).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteReviewConversationRequest'
      responses:
        '200':
          description: Completion evaluated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompleteReviewConversationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The conversation cannot be completed in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Metric registration configuration requires repair
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    WorkspaceId:
      name: X-Coval-Workspace-Id
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 26
      description: >-
        Workspace that scopes this operation. When omitted, the organization's
        active default workspace is used when one can be resolved.
  schemas:
    CompleteReviewConversationRequest:
      type: object
      required:
        - simulation_output_id
      properties:
        assignee_user_id:
          type: string
          nullable: true
          minLength: 26
          maxLength: 26
          description: >-
            Verified Coval reviewer User ID. Null retains the email selector or
            authenticated self-review; an email supplied alongside an ID must
            refer to the same reviewer.
        simulation_output_id:
          type: string
          minLength: 1
          description: Simulation output whose review conversation should be completed.
        assignee:
          type: string
          minLength: 1
          nullable: true
          description: Assignee to complete; defaults to the authenticated acting user.
    CompleteReviewConversationResponse:
      type: object
      required:
        - success
        - is_complete
        - completed_conversation_count
      properties:
        success:
          type: boolean
        is_complete:
          type: boolean
        completed_conversation_count:
          type: integer
        blockers:
          type: array
          items:
            $ref: '#/components/schemas/CompleteReviewConversationBlocker'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: INVALID_ARGUMENT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameter
            details:
              type: array
              description: Detailed error information
              items:
                type: object
                properties:
                  field:
                    type: string
                    nullable: true
                    description: Field that caused the error
                  description:
                    type: string
                    description: Detailed error description
    CompleteReviewConversationBlocker:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - MISSING_METRIC_VALUE
            - MISSING_DISAGREEMENT_NOTE
            - MISSING_REVIEW_LABEL
        message:
          type: string
        metric_id:
          type: string
          nullable: true
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INVALID_ARGUMENT
              message: Invalid request body
              details:
                - field: simulation_output_id
                  description: simulation_output_id is required
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UNAUTHENTICATED
              message: Authentication failed
              details:
                - field: X-API-Key
                  description: Invalid or missing API key
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: PERMISSION_DENIED
              message: Insufficient permissions
              details:
                - field: permissions
                  description: >-
                    The API key does not include the required reviews
                    permission.
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
              details:
                - field: annotation_id
                  description: Annotation not found or not accessible by your organization
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INTERNAL
              message: Internal server error
              details:
                - description: An unexpected error occurred
    ServiceUnavailable:
      description: Service temporarily unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INTERNAL
              message: Service temporarily unavailable
              details:
                - description: Database routing is temporarily unavailable. Please retry.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Organization API key for authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.