docs: Add cards endpoints docs (#57)

* Document API endpoints for card operations

Added API endpoints section with details on card operations.

Signed-off-by: freya-docs <freya.docs.pp@gmail.com>

* Update README with Card API examples and error cases

Added examples for PUT, DELETE, and error handling for Cards.

Signed-off-by: freya-docs <freya.docs.pp@gmail.com>

* Add 409 error in README

Signed-off-by: freya-docs <freya.docs.pp@gmail.com>

---------

Signed-off-by: freya-docs <freya.docs.pp@gmail.com>

Author: freya-docs

README.md

@@ -118,6 +118,139 @@ DevCard uses a three-layer follow engine:
 | WebView Connect | In-app WebView interaction | LinkedIn, Twitter/X |
 | Profile Link | Opens profile in browser | GitLab, Devfolio, others |
 
+## API Endpoints
+
+The API provides the following endpoints (defined by the `cardRoutes` function in `apps/backend/src/routes/cards.ts`):
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| **GET** | `/` | List all cards for the authenticated user |
+| **POST** | `/` | Create a new card (first card is auto-set as default) |
+| **PUT** | `/:id` | Update a card's title and/or links |
+| **DELETE** | `/:id` | Delete a card |
+| **PUT** | `/:id/default` | Set a card as the default card |
+
+### **POST /** - Create a New Card (Example)
+
+**Request:**
+```json
+POST /cards HTTP/1.1
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "title": "New Card",
+  "linkIds": [
+    "223e4567-e89b-12d3-a456-426614174000",
+    "323e4567-e89b-12d3-a456-426614174000"
+  ]
+}
+```
+
+**Response (201 Created):**
+```json
+{
+  "id": "623e4567-e89b-12d3-a456-426614174000",
+  "title": "New Card",
+  "isDefault": false,
+  "links": [
+    {
+      "id": "223e4567-e89b-12d3-a456-426614174000",
+      "platform": "github",
+      "username": "john-doe",
+      "url": "https://github.com/john-doe"
+    },
+    {
+      "id": "323e4567-e89b-12d3-a456-426614174000",
+      "platform": "twitter",
+      "username": "johndoe",
+      "url": "https://twitter.com/johndoe"
+    }
+  ]
+}
+```
+**Field constraints:**
+- `title`: String, 1-100 characters (required)
+- `linkIds`: Array of UUID strings (required, can be empty array)
+
+### **PUT /:id** - Update a Card (Example)
+
+**Request:**
+```json
+PUT /cards/123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "title": "Updated Card Title",
+  "linkIds": [
+    "223e4567-e89b-12d3-a456-426614174000"
+  ]
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "title": "Updated Card Title",
+  "isDefault": true,
+  "links": [
+    {
+      "id": "223e4567-e89b-12d3-a456-426614174000",
+      "platform": "github",
+      "username": "john-doe",
+      "url": "https://github.com/john-doe"
+    }
+  ]
+}
+```
+
+**Field constraints:**
+- `title`: String, 1-100 characters (optional)
+- `linkIds`: Array of UUID strings (optional)
+
+### **DELETE /:id** - Delete a Card (Example)
+
+**Request:**
+```http
+DELETE /cards/123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
+Authorization: Bearer <token>
+```
+
+**Response (204 No Content):**
+```
+(empty body)
+```
+### **PUT /:id/default** - Set a Card as Default (Example)
+
+**Request:**
+```http
+PUT /cards/423e4567-e89b-12d3-a456-426614174000/default HTTP/1.1
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Response (200 OK):**
+```json
+{
+  "message": "Default card updated"
+}
+```
+
+### Error Cases
+
+The following error cases are implemented:
+
+| Scenario | Status | Response |
+|----------|--------|----------|
+| **Create/Update Card** | 400 | `{ error: 'Validation failed', details: parsed.error.flatten() }` — when title or linkIds don't meet constraints |
+| **Create/Update Card** | 409 | `{ error: 'Username already taken'}` — when a user with the same username exists |
+| **Update Card** | 404 | `{ error: 'Card not found' }` — when card ID doesn't exist or doesn't belong to authenticated user |
+| **Delete Card** | 404 | `{ error: 'Card not found' }` — when card ID doesn't exist or doesn't belong to authenticated user |
+| **Set Default Card** | 404 | `{ error: 'Card not found' }` — when card ID doesn't exist or doesn't belong to authenticated user |
+| **Successful Deletion** | 204 | No content |
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions, coding standards, and PR process.