Pages API
Relevant source files
The following files were used as context for generating this wiki page:The Pages API is a core component of the Web Archive server, providing a comprehensive set of endpoints for managing archived web pages. It handles the full lifecycle of a page, from creation and storage to retrieval, modification, and deletion. This API serves as the backend for both the browser extension, which captures and uploads pages, and the web interface, which allows users to browse and manage their archives.
The API is built using Hono and includes functionalities for uploading page content, querying page metadata, managing page status (e.g., showcased, deleted), and serving page content and associated assets like screenshots.
Data Model
The primary data entity is the Page, which is stored in a D1 database table named pages. This table holds metadata about the archived page, including its title, original URL, and references to its content stored in an R2 bucket.
Sources: packages/server/src/model/page.ts
Page Schema
The diagram below illustrates the schema for the pages table.
Page Table Fields
| Field | Type | Description | Constraints |
|---|---|---|---|
id | INTEGER | The unique identifier for the page. | PRIMARY KEY |
title | TEXT | The title of the archived page. | NOT NULL |
pageDesc | TEXT | A user-provided description of the page. | |
pageUrl | TEXT | The original URL from which the page was archived. | |
contentUrl | TEXT | The key for the stored HTML content in the R2 bucket. | NOT NULL |
folderId | INTEGER | The ID of the folder this page belongs to. | FOREIGN KEY |
screenshotId | TEXT | The key for the stored screenshot image in the R2 bucket. | NULLABLE |
isShowcased | INTEGER | A boolean flag (0 or 1) to indicate if the page is featured in the showcase. | NOT NULL |
isDeleted | INTEGER | A boolean flag (0 or 1) for soft-deleting the page. | Default 0 |
createdAt | TEXT | Timestamp when the record was created. | Default CURRENT_TIMESTAMP |
updatedAt | TEXT | Timestamp when the record was last updated. | |
deletedAt | TEXT | Timestamp when the page was soft-deleted. | NULLABLE |
Sources: packages/server/src/model/page.ts:184-196, packages/server/src/api/pages.ts:20-56
API Endpoints
The Pages API exposes several endpoints for managing pages. These are defined in packages/server/src/api/pages.ts.
Page Creation
POST /api/pages/upload_new_page
This endpoint handles the creation of a new archived page. It is used by the browser extension to upload the captured page content, screenshot, and metadata.
Request Body (multipart/form-data):
| Parameter | Type | Description | Required |
|---|---|---|---|
title | string | The title of the page. | Yes |
pageDesc | string | A description for the page. | No |
pageUrl | string | The original URL of the page. | Yes |
pageFile | File | The captured HTML content of the page. | Yes |
folderId | number | The ID of the folder to save the page in. | Yes |
screenshot | File | A screenshot of the page. | No |
bindTags | string[] | A JSON string array of tags to associate. | No |
isShowcased | number (0/1) | Whether to add the page to the showcase. | No |
Sources: packages/server/src/api/pages.ts:19-57
Upload Sequence Diagram
This diagram shows the process of a browser extension saving a new page.
Page Querying
POST /api/pages/query
Retrieves a paginated list of pages based on specified filters.
Request Body (JSON):
| Parameter | Type | Description | Required |
|---|---|---|---|
folderId | number | Filter pages by a specific folder ID. | No |
tagId | number | Filter pages by a specific tag ID. | No |
pageNumber | number | The page number for pagination. | No |
pageSize | number | The number of items per page. | No |
keyword | string | A keyword to search for in page titles. | No |
Sources: packages/server/src/api/pages.ts:89-120, packages/server/src/model/page.ts:60-96
POST /api/pages/query_all_page_ids
Retrieves all page IDs within a specific folder.
Request Body (JSON):
| Parameter | Type | Description | Required |
|---|---|---|---|
folderId | number | The ID of the folder to query. | Yes |
Sources: packages/server/src/api/pages.ts:138-156, packages/server/src/model/page.ts:262-267
POST /api/pages/query_by_url
Finds pages that match a specific URL. This is used by the browser extension to check if a page has already been archived.
Request Body (JSON):
| Parameter | Type | Description | Required |
|---|---|---|---|
pageUrl | string | The URL of the page to look for. | Yes |
Sources: packages/server/src/api/pages.ts:159-184, packages/server/src/model/page.ts:98-102, packages/plugin/popup/components/SavedPageList.tsx:12-16
GET /api/pages/recent_save
Fetches the 20 most recently saved pages.
Sources: packages/server/src/api/pages.ts:186-189, packages/server/src/model/page.ts:222-226
Page Retrieval
GET /api/pages/detail
Retrieves the metadata for a single page by its ID.
Query Parameters:
| Parameter | Type | Description | Required |
|---|---|---|---|
id | number | The ID of the page to fetch. | Yes |
Sources: packages/server/src/api/pages.ts:191-209, packages/web/src/data/page.ts:5-12
GET /api/pages/content
Retrieves the raw HTML content of an archived page.
Query Parameters:
| Parameter | Type | Description | Required |
|---|---|---|---|
pageId | number | The ID of the page whose content is requested. | Yes |
Sources: packages/server/src/api/pages.ts:360-384, packages/web/src/pages/(layout)/page.[slug].tsx:11-21
GET /api/pages/screenshot
Retrieves the screenshot image for a page.
Query Parameters:
| Parameter | Type | Description | Required |
|---|---|---|---|
id | string | The screenshotId of the page. | Yes |
Sources: packages/server/src/api/pages.ts:430-448, packages/web/src/data/page.ts:101-114
Page Modification
PUT /api/pages/update_page
Updates the metadata of an existing page, including its title, folder, description, and associated tags.
Request Body (JSON):
| Parameter | Type | Description | Required |
|---|---|---|---|
id | number | The ID of the page to update. | Yes |
folderId | number | The new folder ID. | Yes |
title | string | The new title. | Yes |
isShowcased | number | The new showcase status (0 or 1). | Yes |
pageDesc | string | The new description. | No |
pageUrl | string | The new page URL. | No |
bindTags | string[] | An array of tag names to add. | No |
unbindTags | string[] | An array of tag names to remove. | No |
Sources: packages/server/src/api/pages.ts:232-273, packages/server/src/model/page.ts:245-260
PUT /api/pages/update_showcase
A dedicated endpoint to quickly toggle the isShowcased status of a page.
Request Body (JSON):
| Parameter | Type | Description | Required |
|---|---|---|---|
id | number | The ID of the page to update. | Yes |
isShowcased | number | The new showcase status (0 or 1). | Yes |
Sources: packages/server/src/api/pages.ts:386-406, packages/web/src/data/page.ts:92-99
Page Deletion and Recovery
The system uses a soft-delete mechanism, allowing for recovery from a "trash" area.
Deletion and Recovery Flow
DELETE /api/pages/delete_page
Soft-deletes a page by setting its isDeleted flag to 1.
Query Parameters:
| Parameter | Type | Description | Required |
|---|---|---|---|
id | number | The ID of the page to delete. | Yes |
Sources: packages/server/src/api/pages.ts:211-230, packages/server/src/model/page.ts:133-141
POST /api/pages/query_deleted
Retrieves all pages that have been soft-deleted.
Sources: packages/server/src/api/pages.ts:300-304, packages/server/src/model/page.ts:114-131
POST /api/pages/restore_page
Restores a soft-deleted page by setting its isDeleted flag back to 0. If the folder containing the page was also deleted, it restores the folder first.
Request Body (JSON):
| Parameter | Type | Description | Required |
|---|---|---|---|
id | number | The ID of the page to restore. | Yes |
folderId | number | The folder ID of the page (optional optimization). | No |
Sources: packages/server/src/api/pages.ts:306-342, packages/server/src/model/page.ts:143-151
DELETE /api/pages/clear_deleted
Permanently deletes all soft-deleted pages from the database and removes their associated content and screenshots from the R2 bucket.
Sources: packages/server/src/api/pages.ts:344-350, packages/server/src/model/page.ts:208-220