PRD_API_CONTRACT.md

# PRD Agent API Contract

This document describes the contract for the new PRD agent endpoints in the multi-agent system backend.

---

## Endpoints

### 1. `POST /prd/chat`
- **Purpose:** Submit a user message to the PRD agent and receive an agent response with section tagging.
- **Request Body:**
  ```json
  {
    "session_id": "string", // Unique session identifier (optional for new session)
    "message": "string" // User's message or answer
  }
  ```
- **Response:**
  ```json
  {
    "session_id": "string", // Session identifier (generated if new)
    "agent_response": "string", // Agent's reply (clarification, next question, or confirmation)
    "tagged_section": "string", // PRD section this message is tagged to (e.g., "goals", "features")
    "all_tags": [ // (Optional) All tagged responses so far
      { "section": "string", "content": "string" }
    ],
    "missing_sections": ["string"] // (Optional) PRD sections still missing
  }
  ```

---

### 2. `GET /prd/doc`
- **Purpose:** Retrieve the synthesized PRD document for a session.
- **Query Parameters:**
  - `session_id` (string, required): Session identifier
  - `format` (string, optional): `"markdown"` (default) or `"json"`
- **Response:**
  - If `format=markdown`:
    ```json
    {
      "session_id": "string",
      "document": "string" // PRD as Markdown
    }
    ```
  - If `format=json`:
    ```json
    {
      "session_id": "string",
      "document": {
        "overview": "string",
        "goals": "string",
        "features": ["string"],
        "stakeholders": ["string"],
        "constraints": "string",
        "success_criteria": "string",
        "out_of_scope": "string"
      }
    }
    ```

---

### 3. `GET /prd/status`
- **Purpose:** Get the current PRD session status, including tagged responses and missing sections.
- **Query Parameters:**
  - `session_id` (string, required): Session identifier
- **Response:**
  ```json
  {
    "session_id": "string",
    "completed_sections": ["string"],
    "missing_sections": ["string"],
    "all_tags": [
      { "section": "string", "content": "string" }
    ]
  }
  ```

---

## Notes
- All endpoints return standard error responses for invalid input or missing session.
- Section names follow the Standard PRD Template: `overview`, `goals`, `features`, `stakeholders`, `constraints`, `success_criteria`, `out_of_scope`.
- The contract may be extended to support additional metadata or advanced workflows.