Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HNU-himematsu/HNU-TimeLetter/llms.txt

Use this file to discover all available pages before exploring further.

The HNU-TimeLetter project exposes a set of Next.js route handler APIs under /api. All endpoints return JSON and are served from the same origin as the Next.js application. APIs are divided into three tiers: public endpoints that require no authentication, admin endpoints that require a valid admin_auth session cookie, and a webhook endpoint that uses Bearer token authentication for Feishu automation triggers.

​
Base URL

EnvironmentBase URL
Local developmenthttp://localhost:3000/api
Productionhttps://himematsu.cn/api
All paths in this documentation are written relative to /api. API version: v1.2.
All API responses use Content-Type: application/json. There is no versioning prefix in the URL — the current version is reflected in the documentation and changelog only.

​
Authentication Tiers

The API has three authentication tiers:
TierMechanismWho uses it
PublicNo authentication requiredFrontend pages, any client
Adminadmin_auth HttpOnly session cookieAdmin dashboard, management scripts
WebhookAuthorization: Bearer <token> header or ?secret= query paramFeishu Automation
For full details on logging in, cookie properties, rate limiting, and webhook tokens, see the Authentication page.

​
Endpoint Index

​
Public APIs — No Authentication Required

These endpoints are read-only and serve data from the src/data/*.json artifact files that are produced by sync jobs. No build or server restart is needed after a sync completes — the data is available immediately at runtime.
MethodPathDescription
GET/api/contentMap locations and stories (homepage narrative data)
GET/api/contributorsCredits / contributors list
GET/api/creation-boardCreation board ideas and card headers
GET/api/announcement-configAnnouncement popup configuration (public read)
GET/api/feishu-jsapi-signatureGenerate a Feishu JSAPI signature for the current page URL

​
Admin APIs — Cookie Authentication Required

All admin endpoints (except POST /api/admin/login) require a valid admin_auth cookie. Requests without a valid cookie receive 401 Unauthorized.
MethodPathDescription
POST/api/admin/loginLog in — sets admin_auth cookie (no cookie required)
DELETE/api/admin/loginLog out — clears admin_auth cookie
GET/api/admin/sync/configRead scheduler configuration and runtime status
PATCH/api/admin/sync/configUpdate scheduler configuration (hot-reloads immediately)
GET/api/admin/sync/jobsList sync jobs (newest first)
POST/api/admin/sync/jobsCreate and enqueue a new sync job (async, returns 202)
GET/api/admin/sync/jobs/:jobIdGet full details of a specific sync job
GET/api/admin/sync/jobs/:jobId/logsGet execution logs for a sync job (last 200 lines)
GET/api/admin/syncLegacy compat: read sync status summary
POST/api/admin/syncLegacy compat: trigger sync (action: "trigger") or update config (action: "update")
GET/api/admin/announcementRead announcement configuration (admin)
PATCH/api/admin/announcementUpdate announcement configuration

​
Webhook

MethodPathDescription
POST/api/admin/sync/webhookFeishu Automation trigger — enqueues a sync job via Bearer token

​
API Pages

Authentication

Session cookie login/logout, rate limiting, and webhook Bearer token setup.

Public: Content

GET /api/content — map locations and embedded story records.

Public: Contributors

GET /api/contributors — credits and contributor list.

Public: Creation Board

GET /api/creation-board — community creation ideas and card headers.

Admin: Sync Jobs

Create, list, inspect, and monitor Feishu data sync jobs.

Admin: Sync Config

Read and update the scheduler cron configuration.

Admin: Announcement

Read and update the admin-side announcement popup config.

Webhook

POST /api/admin/sync/webhook — Feishu Automation Bearer token trigger.

​
HTTP Status Codes

CodeStatusMeaning
200OKRequest succeeded. Used for queries, updates, and logout.
202AcceptedRequest accepted; processing is asynchronous. Returned when a sync job is successfully enqueued.
400Bad RequestInvalid request parameters — e.g. unknown table key, malformed cron expression, empty required field.
401UnauthorizedMissing or invalid admin_auth cookie, incorrect password, or invalid webhook Bearer token.
404Not FoundThe requested resource does not exist — e.g. job ID not found.
409ConflictA sync job is already running. The response body includes currentJobId.
429Too Many RequestsLogin rate limit exceeded (5 consecutive failures → 30-minute cooldown). The response body includes retryAfterSeconds: 1800.
500Internal Server ErrorUnexpected server-side failure — e.g. file read/write error or missing environment variable.

​
Error Response Shape

All error responses return a JSON object with a message field: 
{ "message": "Unauthorized" }
Some endpoints add extra fields to the error body for programmatic handling: 
{
  "success": false,
  "message": "Too many failed attempts",
  "retryAfterSeconds": 1800
}

{
  "message": "已有同步任务正在执行",
  "currentJobId": "sync_20260430095900_xy99zz"
}

​
Data Freshness

Public APIs (/api/content, /api/contributors, /api/creation-board) read directly from the src/data/*.json artifact files at runtime using no-store caching. When an admin sync job completes, it writes updated JSON files to disk — the next request to the public API immediately returns the new data. No application rebuild or server restart is required. 
Feishu Bitable (source of truth)
    ↓  sync job (scheduled / manual / webhook)
src/data/*.json  (artifact files)
    ↓  runtime read (no-store)
/api/content · /api/contributors · /api/creation-board
    ↓
Frontend pages

Build docs developers (and LLMs) love

Get started for freeTalk to us