Close an ACTIVE conversation manually. Only the project owner can close a conversation. The conversation must be currently ACTIVE.

• Closing sets the conversation status to CLOSED.
• Already CLOSED conversations cannot be closed again — a 409 Conflict is returned.
• The response returns the updated conversation metadata without the message list.
• Closed conversations remain readable via UC-04004 (Conversation Detail).

sequenceDiagram
    actor User

    User->>+FE: clicks "Close Conversation"

    FE->>+BE: PUT /api/v1/projects/{projectId}/conversations/{conversationId}/close <br> Authorization: Bearer {accessToken}

    BE->>BE: validate access token
    alt token missing or invalid
        BE-->>FE: 401 Unauthorized <br> ErrorResponse
    end

    BE->>DB: load project by projectId
    alt project not found
        BE-->>FE: 404 Not Found <br> ErrorResponse
    end

    BE->>BE: check project belongs to user's tenant
    alt project does not belong to tenant
        BE-->>FE: 403 Forbidden <br> ErrorResponse
    end

    BE->>DB: load conversation by conversationId (scoped to projectId)
    alt conversation not found
        BE-->>FE: 404 Not Found <br> ErrorResponse
    end

    BE->>BE: check conversation status is ACTIVE
    alt conversation is already CLOSED
        BE-->>FE: 409 Conflict <br> ErrorResponse
    end

    BE->>DB: update conversation status = CLOSED

    BE->>-FE: 200 OK <br> ConversationResponse

    FE->>-User: update conversation status in UI

PUT /api/v1/projects/{projectId}/conversations/{conversationId}/close (no request body)

200 OK ConversationResponse:

{
  "data": {
    "id": 8,
    "title": "I want to add a contact form to the homepage",
    "status": "CLOSED",
    "messageCount": 4,
    "createdAt": "2026-04-29T12:00:00Z",
    "updatedAt": "2026-04-29T12:15:01Z"
  }
}

401 Unauthorized (missing or invalid access token) ErrorResponse:

{
  "status": 401,
  "code": "AUTHENTICATION_FAILED",
  "message": "Access token is missing or invalid"
}

403 Forbidden (project does not belong to user’s tenant) ErrorResponse:

{
  "status": 403,
  "code": "FORBIDDEN",
  "message": "You do not have access to this project"
}

404 Not Found (project not found) ErrorResponse:

{
  "status": 404,
  "code": "NOT_FOUND_PROJECT",
  "message": "Project not found"
}

404 Not Found (conversation not found or does not belong to project) ErrorResponse:

{
  "status": 404,
  "code": "NOT_FOUND_CONVERSATION",
  "message": "Conversation not found"
}

409 Conflict (conversation is already CLOSED) ErrorResponse:

{
  "status": 409,
  "code": "CONFLICT_CONVERSATION",
  "message": "Conversation is already CLOSED"
}

Frontend

Validations

Backend

Validations

Test Cases