fier of the article. Required for DELETE. Optional for GET (triggers status check mode). |

Request Body (POST only)

The POST method expects a JSON payload. All other methods ignore the request body.

{
  "articleId": "string"
}

Field	Type	Required	Description
articleId	string	Yes	Unique identifier of the article to bookmark. Whitespace is automatically trimmed.

Headers

Header	Value	Description
Cookie	<session_cookie>	Contains the authenticated user session.
Content-Type	application/json	Required for POST requests to parse the JSON body.

Response Format

Success Responses

GET (List All Bookmarks) Returns an array of bookmarked articles ordered by creation date (newest first).

{
  "bookmarks": [
    {
      "id": "cm5x8...",
      "articleId": "art_123",
      "slug": "understanding-nextjs-server-components",
      "title": "Understanding Next.js Server Components",
      "createdAt": "2024-05-12T14:30:00.000Z"
    }
  ]
}

GET (Check Single Article Status) Triggered when articleId is provided as a query parameter.

{
  "bookmarked": true
}

POST / DELETE Returns a simple acknowledgment upon successful execution.

{
  "ok": true
}

Error Responses

All error responses follow a consistent JSON structure: { "error": "string" }.

Status Code	Condition	Example Response
400 Bad Request	Missing articleId in POST body or DELETE query params.	{"error": "articleId required"}
401 Unauthorized	Missing, invalid, or expired session cookie.	{"error": "Unauthorized"}
404 Not Found	POST request targets an article that does not exist or is not published (isPublished: false).	{"error": "Article not found"}
500 Internal Server Error	Database connection failure, Prisma query error, or unexpected runtime exception.	{"error": "Internal server error"}

Usage Example

Below are practical curl commands demonstrating each HTTP method. Replace <YOUR_SESSION_COOKIE> with a valid session token and <ARTICLE_ID> with a target article identifier.

Check if an article is bookmarked:

curl -X GET "https://api.codcompass.com/api/user/bookmarks?articleId=art_123" \
  -H "Cookie: <YOUR_SESSION_COOKIE>"

Retrieve all saved bookmarks:

curl -X GET "https://api.codcompass.com/api/user/bookmarks" \
  -H "Cookie: <YOUR_SESSION_COOKIE>"

Bookmark an article:

curl -X POST "https://api.codcompass.com/api/user/bookmarks" \
  -H "Cookie: <YOUR_SESSION_COOKIE>" \
  -H "Content-Type: application/json" \
  -d '{"articleId": "art_123"}'

Remove a bookmark:

curl -X DELETE "https://api.codcompass.com/api/user/bookmarks?articleId=art_123" \
  -H "Cookie: <YOUR_SESSION_COOKIE>"

Common Pitfalls

1. Parameter Placement Mismatch
   The articleId parameter location differs by method. POST expects it in the JSON request body, while GET (status check) and DELETE expect it as a URL query parameter. Sending articleId in the body for a DELETE request will result in a 400 Bad Request error. Always verify the HTTP method before structuring your payload.

2. Unpublished Article Restriction
   The POST endpoint enforces a strict validation check: it only allows bookmarking articles where isPublished is true. Draft, archived, or unpublished articles will trigger a 404 Not Found response. Ensure your application filters or verifies article publication status before attempting to bookmark, or gracefully handle the 404 error in your UI.

3. Idempotent POST Behavior (Upsert Logic)
   The POST method uses a database upsert operation with an empty update clause. This means calling POST multiple times with the same articleId will not create duplicate records or throw errors. It simply ensures the bookmark exists. While this improves resilience against race conditions or double-clicks, it also means the endpoint will not return a 201 Created status or indicate whether the bookmark was newly created vs. already existing. Rely on the GET status check if you need to differentiate between new and existing saves.

Related Endpoints

• /api/articles — Retrieve article metadata, slugs, and publication status. Use this endpoint to verify that an article exists and is published before calling POST /api/user/bookmarks.
• /api/user/sessions — Manage authentication state, refresh tokens, and validate session cookies. Required for maintaining the authentication context needed by the bookmarks endpoint.
• /api/user/preferences — Configure user-specific settings such as notification preferences, theme selection, and reading history retention. Often paired with bookmarks to build a cohesive personalized dashboard.
• /api/search — Full-text search across published articles. Frequently used in conjunction with bookmarks to allow users to quickly locate and save relevant content from search results.