tomatically clamped. | | offset | integer | No | 0 | ≥ 0 | Number of records to skip. Used for pagination. Negative values are clamped to 0. | | q | string | No | undefined | Any | Full-text search query. Filters records matching the provided string. | | status | string | No | undefined | Any | Filters records by crawl status (e.g., success, failed, pending). Exact match depends on underlying schema. |

Notes:

• Parameters are parsed using standard URL search parameters.
• If limit is omitted or invalid, it falls back to 40.
• If offset is omitted or invalid, it falls back to 0.
• The q and status parameters are optional. Omitting them returns all records within the pagination bounds.

Response Format

All responses return a JSON payload. The structure varies slightly depending on the database state and UI configuration.

Success Response (200 OK)

When the local crawler UI is enabled and the SQLite database exists, the endpoint returns a paginated result set.

{
  "ok": true,
  "rows": [
    {
      "id": "a1b2c3d4",
      "url": "https://example.com/docs/api",
      "status": "success",
      "title": "API Documentation",
      "crawled_at": "2024-05-20T14:32:00Z"
    }
  ],
  "total": 1542,
  "limit": 40,
  "offset": 0
}

Fields:

• ok: Boolean indicating successful execution.
• rows: Array of crawl records matching the query. Structure depends on the underlying database schema.
• total: Total number of records matching the filter criteria (ignores pagination).
• limit & offset: Echoes the applied pagination values.

Database Not Initialized (200 OK)

If the SQLite database has not been created yet (i.e., no crawl has been run), the endpoint returns a successful response with a descriptive message instead of an error.

{
  "ok": true,
  "rows": [],
  "total": 0,
  "message": "本地 SQLite 尚未创建，请先运行至少一次爬虫。"
}

UI Disabled (404 Not Found)

If the local crawler UI feature is disabled in the environment configuration, the endpoint returns a 404 status with a JSON error payload.

{
  "ok": false,
  "error": "Not found"
}

Server Error (500 Internal Server Error)

If an unhandled exception occurs during database querying or parameter parsing, the Next.js runtime will return a standard 500 error. The route does not explicitly catch all database-level failures, so monitoring tools should be configured to track unexpected runtime exceptions.

Usage Example

Retrieve the first 20 records, search for "authentication", and filter by successful status:

curl -X GET "https://your-domain.com/api/local-only/crawl-library?limit=20&offset=0&q=authentication&status=success"

Paginate to the next page:

curl -X GET "https://your-domain.com/api/local-only/crawl-library?limit=20&offset=20&q=authentication&status=success"

Common Pitfalls

1. Unexpected 404 Responses: The endpoint is protected by a UI guard (assertLocalCrawlerUiEnabled). If your environment variable or configuration disables the local crawler UI, the route will immediately return a 404 JSON response. Verify that the UI feature flag is enabled in your deployment configuration before debugging pagination or search issues.

2. Silent Database State: When the SQLite database does not exist, the endpoint returns 200 OK with an empty rows array and a Chinese-language message. This is intentional to prevent frontend crashes during initial setup, but it can be mistaken for an empty result set. Always check for the presence of the message field or verify that at least one crawl has completed before querying.

3. Pagination Clamping Behavior: The limit parameter is strictly clamped between 1 and 200. Passing limit=500 will silently return 200 records. Similarly, negative offset values are clamped to 0. If your frontend expects strict validation errors for out-of-bounds values, you must implement client-side checks before making the request.

Related Endpoints

This endpoint is part of the local crawler module and is designed to work alongside the ingestion and configuration routes that populate the underlying SQLite database. In a typical deployment, it is used in conjunction with:

• Local Crawler Execution API: Triggers crawl jobs and writes results to the SQLite database.
• Local Crawler Configuration API: Manages crawl schedules, filters, and UI feature flags.

Exact paths for these companion endpoints depend on your project's routing structure, but they share the same /api/local-only/ namespace and rely on the same database guard and UI toggle mechanisms. Ensure that the crawler execution pipeline has run successfully before querying the library endpoint to avoid empty responses.