diff --git a/docs/api/highlights/create_highlight.md b/docs/api/highlights/create_highlight.md new file mode 100644 index 0000000..3c68b7b --- /dev/null +++ b/docs/api/highlights/create_highlight.md @@ -0,0 +1,66 @@ +# Create Highlight + +Create a new highlight for a media item. + +**Endpoint**: `POST /api/media-items/{media_id}/highlights` +**Auth**: Required +**Content-Type**: `application/json` + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| media_id | string | Yes | Media item UUID | + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| selection_text | string | Yes | Highlighted text | +| start_position | string | No | Start position (e.g., epubcfi) | +| end_position | string | No | End position (e.g., epubcfi) | +| color | string | No | Highlight color (hex, default: "#ffff00") | +| percentage_start | float | No | Start percentage (0-1) | +| percentage_end | float | No | End percentage (0-1) | + +### Example Request + +```json +{ + "selection_text": "Highlighted text...", + "start_position": "epubcfi(/6/4/2:15)", + "end_position": "epubcfi(/6/4/2:20)", + "color": "#ffff00", + "percentage_start": 0.45, + "percentage_end": 0.47 +} +``` + +## Response (201 Created) + +```json +{ + "id": "uuid", + "media_item_id": "uuid", + "user_id": "uuid", + "selection_text": "Highlighted text...", + "start_position": "epubcfi(/6/4/2:15)", + "end_position": "epubcfi(/6/4/2:20)", + "color": "#ffff00", + "percentage_start": 0.45, + "percentage_end": 0.47, + "created_at": "2026-01-31T10:00:00Z" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid highlight data | +| 401 | Invalid or expired token | +| 404 | Media item not found | + +## Try It Out + + diff --git a/docs/api/highlights/delete_highlight.md b/docs/api/highlights/delete_highlight.md new file mode 100644 index 0000000..efbe67a --- /dev/null +++ b/docs/api/highlights/delete_highlight.md @@ -0,0 +1,41 @@ +# Delete Highlight + +Delete a highlight. + +**Endpoint**: `DELETE /api/media-items/highlights/{highlight_id}` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| highlight_id | string | Yes | Highlight UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +DELETE /api/media-items/highlights/uuid +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (204 No Content) + +Highlight deleted successfully. + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 403 | User does not own this highlight | +| 404 | Highlight not found | + +## Try It Out + + diff --git a/docs/api/highlights/get_highlights.md b/docs/api/highlights/get_highlights.md new file mode 100644 index 0000000..dfe4f15 --- /dev/null +++ b/docs/api/highlights/get_highlights.md @@ -0,0 +1,61 @@ +# Get Highlights + +Retrieve all highlights for a specific media item. + +**Endpoint**: `GET /api/media-items/{media_id}/highlights` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| media_id | string | Yes | Media item UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +GET /api/media-items/uuid/highlights +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "highlights": [ + { + "id": "uuid", + "media_item_id": "uuid", + "user_id": "uuid", + "selection_text": "Highlighted text passage...", + "start_position": "epubcfi(/6/4/2:15)", + "end_position": "epubcfi(/6/4/2:20)", + "color": "#ffff00", + "percentage_start": 0.45, + "percentage_end": 0.47, + "character_start": 15432, + "character_end": 15480, + "epubcfi_start": "epubcfi(/6/4/2:15)", + "epubcfi_end": "epubcfi(/6/4/2:20)", + "created_at": "2026-01-31T10:00:00Z" + } + ] +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 404 | Media item not found | + +## Try It Out + + diff --git a/docs/api/highlights/update_highlight.md b/docs/api/highlights/update_highlight.md new file mode 100644 index 0000000..b1d7245 --- /dev/null +++ b/docs/api/highlights/update_highlight.md @@ -0,0 +1,55 @@ +# Update Highlight + +Update an existing highlight. + +**Endpoint**: `PUT /api/media-items/highlights/{highlight_id}` +**Auth**: Required +**Content-Type**: `application/json` + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| highlight_id | string | Yes | Highlight UUID | + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| selection_text | string | No | Updated highlighted text | +| color | string | No | Updated highlight color (hex) | + +### Example Request + +```json +{ + "selection_text": "Updated text", + "color": "#00ff00" +} +``` + +## Response (200 OK) + +```json +{ + "id": "uuid", + "media_item_id": "uuid", + "user_id": "uuid", + "selection_text": "Updated text", + "color": "#00ff00", + "updated_at": "2026-01-31T10:00:00Z" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid highlight data | +| 401 | Invalid or expired token | +| 403 | User does not own this highlight | +| 404 | Highlight not found | + +## Try It Out + + diff --git a/docs/api/notes/create_note.md b/docs/api/notes/create_note.md new file mode 100644 index 0000000..d0d3fe2 --- /dev/null +++ b/docs/api/notes/create_note.md @@ -0,0 +1,60 @@ +# Create Note + +Create a new note for a media item. + +**Endpoint**: `POST /api/media-items/{media_id}/notes` +**Auth**: Required +**Content-Type**: `application/json` + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| media_id | string | Yes | Media item UUID | + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| content | string | Yes | Note content | +| position | string | No | Location reference (e.g., epubcfi) | +| percentage_location | float | No | Location as percentage (0-1) | +| epubcfi_location | string | No | EPUB CFI location | + +### Example Request + +```json +{ + "content": "This is a note", + "position": "epubcfi(/6/4/2:15)", + "percentage_location": 0.45, + "epubcfi_location": "epubcfi(/6/4/2:15)" +} +``` + +## Response (201 Created) + +```json +{ + "id": "uuid", + "media_item_id": "uuid", + "user_id": "uuid", + "content": "This is a note", + "position": "epubcfi(/6/4/2:15)", + "percentage_location": 0.45, + "epubcfi_location": "epubcfi(/6/4/2:15)", + "created_at": "2026-01-31T10:00:00Z" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid note data | +| 401 | Invalid or expired token | +| 404 | Media item not found | + +## Try It Out + + diff --git a/docs/api/notes/delete_note.md b/docs/api/notes/delete_note.md new file mode 100644 index 0000000..3e7fe51 --- /dev/null +++ b/docs/api/notes/delete_note.md @@ -0,0 +1,41 @@ +# Delete Note + +Delete a note. + +**Endpoint**: `DELETE /api/media-items/notes/{note_id}` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| note_id | string | Yes | Note UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +DELETE /api/media-items/notes/uuid +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (204 No Content) + +Note deleted successfully. + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 403 | User does not own this note | +| 404 | Note not found | + +## Try It Out + + diff --git a/docs/api/notes/get_notes.md b/docs/api/notes/get_notes.md new file mode 100644 index 0000000..6cfe935 --- /dev/null +++ b/docs/api/notes/get_notes.md @@ -0,0 +1,58 @@ +# Get Notes + +Retrieve all notes for a specific media item. + +**Endpoint**: `GET /api/media-items/{media_id}/notes` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| media_id | string | Yes | Media item UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +GET /api/media-items/uuid/notes +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "notes": [ + { + "id": "uuid", + "media_item_id": "uuid", + "user_id": "uuid", + "content": "This is an interesting passage...", + "position": "epubcfi(/6/4/2:15)", + "percentage_location": 0.45, + "character_start": 15432, + "character_end": 15480, + "epubcfi_location": "epubcfi(/6/4/2:15)", + "created_at": "2026-01-31T10:00:00Z", + "updated_at": "2026-01-31T10:00:00Z" + } + ] +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 404 | Media item not found | + +## Try It Out + + diff --git a/docs/api/notes/update_note.md b/docs/api/notes/update_note.md new file mode 100644 index 0000000..f4e2410 --- /dev/null +++ b/docs/api/notes/update_note.md @@ -0,0 +1,55 @@ +# Update Note + +Update an existing note. + +**Endpoint**: `PUT /api/media-items/notes/{note_id}` +**Auth**: Required +**Content-Type**: `application/json` + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| note_id | string | Yes | Note UUID | + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| content | string | No | Updated note content | +| position | string | No | Updated location reference | + +### Example Request + +```json +{ + "content": "Updated note content", + "position": "epubcfi(/6/4/2:20)" +} +``` + +## Response (200 OK) + +```json +{ + "id": "uuid", + "media_item_id": "uuid", + "user_id": "uuid", + "content": "Updated note content", + "position": "epubcfi(/6/4/2:20)", + "updated_at": "2026-01-31T10:00:00Z" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid note data | +| 401 | Invalid or expired token | +| 403 | User does not own this note | +| 404 | Note not found | + +## Try It Out + + diff --git a/docs/api/progress/delete_progress.md b/docs/api/progress/delete_progress.md new file mode 100644 index 0000000..46808a6 --- /dev/null +++ b/docs/api/progress/delete_progress.md @@ -0,0 +1,40 @@ +# Delete Reading Progress + +Delete reading progress for a media item. + +**Endpoint**: `DELETE /api/media-items/{media_id}/progress` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| media_id | string | Yes | Media item UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +DELETE /api/media-items/uuid/progress +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (204 No Content) + +Progress deleted successfully. + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 404 | Media item not found | + +## Try It Out + + diff --git a/docs/api/progress/get_progress.md b/docs/api/progress/get_progress.md new file mode 100644 index 0000000..b00d588 --- /dev/null +++ b/docs/api/progress/get_progress.md @@ -0,0 +1,56 @@ +# Get Reading Progress + +Retrieve reading progress for a specific media item. + +**Endpoint**: `GET /api/media-items/{media_id}/progress` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| media_id | string | Yes | Media item UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +GET /api/media-items/uuid/progress +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "media_item_id": "uuid", + "user_id": "uuid", + "current_page": 45, + "total_pages": 200, + "percentage": 0.225, + "character_offset": 15432, + "epubcfi": "epubcfi(/6/4/2:15)", + "chapter": 3, + "chapter_progress": 0.5, + "last_read_at": "2026-01-31T10:00:00Z", + "format_group": "reflowable", + "viewport_y": 0.12, + "zoom_level": 1.0 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 404 | Media item not found | + +## Try It Out + + diff --git a/docs/api/progress/update_progress.md b/docs/api/progress/update_progress.md new file mode 100644 index 0000000..8b70b33 --- /dev/null +++ b/docs/api/progress/update_progress.md @@ -0,0 +1,72 @@ +# Update Reading Progress + +Update reading progress for a media item. This will sync across all devices via WebSocket. + +**Endpoint**: `PUT /api/media-items/{media_id}/progress` +**Auth**: Required +**Content-Type**: `application/json` + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| media_id | string | Yes | Media item UUID | + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| source | string | Yes | Progress source (e.g., "web", "koreader", "kobo") | +| location | object | Yes | Location information | +| location.percentage | float | No | Progress percentage (0-1) | +| location.epubcfi | string | No | EPUB CFI location | +| location.character | integer | No | Character offset | +| location.chapter | integer | No | Chapter number | +| location.page | integer | No | Current page | +| location.total_pages | integer | No | Total pages | +| device_metadata | object | No | Device metadata | +| device_metadata.device_type | string | No | Device type | +| device_metadata.user_agent | string | No | User agent string | + +### Example Request + +```json +{ + "source": "web", + "location": { + "percentage": 0.45678, + "epubcfi": "epubcfi(/6/4/2:15)", + "character": 15432, + "chapter": 3, + "page": 89, + "total_pages": 200 + }, + "device_metadata": { + "device_type": "web", + "user_agent": "Mozilla/5.0..." + } +} +``` + +## Response (200 OK) + +```json +{ + "sync_status": "success", + "progress_updated": true, + "devices_notified": ["device-1", "device-2"], + "broadcast": true +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid location data | +| 401 | Invalid or expired token | +| 404 | Media item not found | + +## Try It Out + +