omitted fields retain their existing values. This aligns with standard PATCH semantics and conditional update logic.

Headers

Header	Value	Required
Content-Type	application/json	Yes

Request Body Schema

Field	Type	Required	Description
status	string	No	Workflow state. Accepts standard lifecycle values. If set to "approved", the system automatically maps it to "published", generates a published_at timestamp, and sets reviewed_by to a default admin identifier.
contentEn	string	No	The English article body. Supports Markdown or HTML formatting.
titleEn	string	No	The English title of the article.
category	string	No	Primary content category or tag for organizational filtering.
monetization	string | boolean	No	Indicates monetization tier, eligibility, or flag status.
difficultyLevel	string | number	No	Complexity rating (e.g., "beginner", "intermediate", "advanced" or numeric equivalents).

Example Request Body

{
  "status": "approved",
  "titleEn": "Understanding Next.js Server Components",
  "category": "Frontend Frameworks",
  "difficultyLevel": "intermediate",
  "monetization": true
}

Response Format

The endpoint returns a JSON response indicating the outcome of the update operation. Successful database commits return a 200 OK status. Parsing failures or database errors are caught and returned as 500 Internal Server Error responses.

Success Response (200 OK)

{
  "success": true
}

Error Response (500 Internal Server Error)

{
  "error": "Database connection failed"
}

Note: The route handler uses a single try/catch block that captures JSON parsing errors, Supabase query failures, and runtime exceptions. All errors return a 500 status with a descriptive error string. Clients should validate payloads before transmission and implement exponential backoff for transient failures.

Usage Example

The following curl command demonstrates a typical update request. Replace [id] with the target article's unique identifier.

curl -X PATCH "https://api.codcompass.com/api/articles/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "contentEn": "# Revised Article Content\\n\\nUpdated sections for accuracy and clarity.",
    "category": "Backend Development",
    "difficultyLevel": "advanced"
  }'

Common Pitfalls

1. Automatic Status Transformation
   Developers frequently expect the status field to be stored exactly as submitted. However, the endpoint contains explicit conditional logic: if status === "approved", it is automatically converted to "published" in the database, and published_at is populated with the current UTC timestamp. If you need to set a custom status that bypasses this transformation, ensure it does not match the "approved" string.

2. Partial Update Behavior & Null Handling
   Because the route builds an updates object conditionally (if (field) updates.field = field), fields with falsy values (null, "", 0, false) are silently ignored. If your workflow requires explicitly clearing a field (e.g., removing a category), sending null will not update the database. Instead, consider sending an empty string or a database-specific sentinel value, and verify how your Supabase schema handles NULL constraints.

3. Missing or Incorrect Content-Type Header
   The handler calls request.json() without fallback parsing or content negotiation. If the Content-Type: application/json header is omitted, misspelled, or set to text/plain, the server will throw a parsing exception that bubbles up to the catch block, resulting in a 500 error. Always configure your HTTP client to explicitly set the JSON content type, and validate payload structure before transmission.

Related Endpoints

• GET /api/articles — Retrieve a paginated list of articles with filtering, sorting, and search capabilities.
• GET /api/articles/[id] — Fetch a single article by its unique identifier, returning full content, metadata, and publication state.
• POST /api/articles — Create a new article draft. Typically used to initialize content before transitioning to this PATCH endpoint for review and publication.
• DELETE /api/articles/[id] — Permanently remove an article from the knowledge base. Use with caution, as this operation is irreversible.