===== 1. Background & Objective =====
To support platform integration and workflow automation for MCW, CX Genie must provide open APIs for third-party systems to perform the following operations on form data:

  * Retrieve form field metadata
  * Create new form entries
  * Update specific form entries
  * Query all or filtered form data
  * Archive form entries (internal use only)

These APIs will be applied in scenarios such as:
  * Data synchronization
  * Auto-fill features
  * Self-service queries

===== 2. API Security Design =====

==== 2.1 workspace_token ====
**Authentication**  
All API requests must include the following field in the request payload:

<code json>
"workspace_token": "your_token_here"
</code>

The system will verify the token against the corresponding Workspace’s permissions.  
Requests with invalid or missing tokens will return a **401 Unauthorized** error.

==== 2.2 Error Response Format ====
<code json>
{
  "error": "Invalid or missing workspace_token"
}
</code>

===== 3. Features & API List =====
^ API ID   ^ Feature Name          ^ Description                                    ^ Method ^ Example Path                                ^
| [[API-001]]  | Get Field Metadata    | Retrieve field definitions for a specific form | POST   | /api/v1/form-results-value/metadata          |
| API-002  | Create Form Entry     | Submit a new form response to a specific Workspace | POST   | /api/v1/form-results-value/create            |
| API-003  | Update Form Entry     | Update an existing form entry by result_id     | PUT    | /api/v1/form-results-value/update/{result_id}|
| API-004  | Query Form Entries    | Retrieve all or filtered form data             | POST   | /api/v1/form-results-value/query             |
| API-005  | Archive Form Entry    | Mark form entry as archived (internal API only)| PATCH  | /api/v1/form-results-value/archive/{result_id}|

===== 4. API Details =====

==== API-001: Get Field Metadata ====
**Method:** POST  \\
**Endpoint:** `/api/v1/form-results-value/metadata`

**Request Payload**
<code json>
{
  "workspace_id": "abc123",
  "form_id": "form456",
  "workspace_token": "xxxxx"
}
</code>

**Response**
<code json>
{
  "form_name": "Customer Feedback",
  "fields": [
    {
      "field_key": "email",
      "label": "Email",
      "type": "text",
      "required": true
    },
    {
      "field_key": "rating",
      "label": "Rating",
      "type": "number",
      "required": false
    }
  ]
}
</code>


==== API-002: Create Form Entry ====
**Method:** POST  
**Endpoint:** `/api/v1/form-results-value/create`

**Request Payload**
<code json>
{
  "workspace_id": "abc123",
  "form_id": "form456",
  "workspace_token": "xxxxx",
  "customer_email": "user@example.com",
  "data": {
    "email": "user@example.com",
    "rating": 5,
    "files": [
      {
        "name": "image1.jpg",
        "url": "https://storage.example.com/file/image1.jpg",
        "type": "image/jpeg",
        "size": 1024000
      },
      {
        "name": "document.pdf",
        "url": "https://storage.example.com/file/document.pdf",
        "type": "application/pdf",
        "size": 2048000
      }
    ]
  }
}
</code>

**Note:** For any field with `type=upload`, you should call the File Upload API first and pass the response in the format above.  
See: [[Form Record File Upload API]]

**Success Response**
<code json>
{
  "message": "Form result created successfully",
  "result_id": "xyz789"
}
</code>

**Error Response**
<code json>
{
  "error": "Missing required field: email"
}
</code>


----

==== API-003: Update Form Entry ====
**Method:** PUT  
**Endpoint:** `/api/v1/form-results-value/update/{result_id}`

**Path Parameter**
^ Parameter  ^ Type   ^ Description                         ^ Required |
| result_id  | string | Unique identifier of the record     | Yes      |

**Request Payload**
^ Field          ^ Type    ^ Description           ^ Required |
| workspace_id   | string  | Workspace identifier | Yes       |
| workspace_token| string  | Access token         | Yes       |
| data           | object  | Key-value fields to update | Yes |

**Example**
<code json>
{
  "workspace_id": "abc123",
  "workspace_token": "xxxxx",
  "data": {
    "rating": 4
  }
}
</code>

**Note:**  
The system will validate that each field in `data` matches the expected format from the form metadata.  
If a field value does not match its type, an error will be returned.

**Success Response**
<code json>
{
  "message": "Form result updated"
}
</code>

**Error Responses**
Examples:  

_Invalid value_
<code json>
{
  "error": "Invalid value for field 'rating': expected type 'number'"
}
</code>

_Missing token_
<code json>
{
  "error": "Invalid or missing workspace_token"
}
</code>

_Invalid field key_
<code json>
{
  "error": "Field 'unknown_field' is not defined in the form"
}
</code>


----

==== API-004: Query Form Entries ====
**Method:** POST  
**Endpoint:** `/api/v1/form-results-value/query`

**Request Payload**
<code json>
{
  "workspace_id": "abc123",
  "form_id": "form456",
  "workspace_token": "xxxxx",
  "filters": {
    "email": "user@example.com"
  },
  "limit": 10,
  "offset": 0
}
</code>

**Response**
<code json>
{
  "total": 1,
  "data": [
    {
      "result_id": "xyz789",
      "email": "user@example.com",
      "rating": 5
    }
  ]
}
</code>


----

==== API-005: Archive Form Entry (Internal Use Only) ====
**Method:** PATCH  
**Endpoint:** `/api/v1/form-results-value/archive/{result_id}`

**Path Parameter**  
* `result_id`: ID of the record to archive

**Request Payload**
<code json>
{
  "workspace_id": "abc123",
  "workspace_token": "xxxxx",
  "internal_access_key": "internalSecretKey"
}
</code>

**Success Response**
<code json>
{
  "message": "Form result archived"
}
</code>

**Unauthorized Response**
<code json>
{
  "error": "Unauthorized access"
}
</code>


----