Formosa ESG 2026 Worker API — Endpoint Reference

Version: v1.0
Date: 2026-04-04
Language: Engineering Documentation (工程語言)
Audience: Developers, QA Testers, Integration Partners

Table of Contents

1. Base URL & Access
2. Public Endpoints
3. Admin Endpoints
4. Cron Jobs
5. Global Endpoints
6. Authentication
7. Rate Limits
8. Response Format
9. Constants Reference
10. Level System
11. Carbon Coefficients
12. Three-Tier Authorization

Base URL & Access

Production Environment

• Primary: https://api.paulkuo.tw
• Alternative: https://mazu.today (reverse proxy)

All API requests must use HTTPS. Requests to HTTP endpoints will fail.

Public Endpoints

No authentication required for these endpoints.

Payload Limits

All POST /api/formosa/* requests accept a maximum content-length of 102,400 bytes (100 KB). Requests exceeding this limit return HTTP 413 Payload Too Large.

Admin Endpoints

Require X-Admin-Token header with valid admin, manager, or owner token.

Cron Jobs

Internal scheduled tasks (no HTTP endpoint exposure).

Global Endpoints

System Health Check

GET /health

Returns system health status including Formosa subsystem details:

• D1 database status
• KV store status
• Pending KV keys count
• Last flush timestamp

Authentication

Header Format

X-Admin-Token: <token_value>

All admin endpoints require this header. Requests without valid authentication return HTTP 401 Unauthorized.

Token Types

Three authorization tiers are supported:

Source: formosa.js:19–44

Rate Limits

All rate limits are enforced per userId or admin token via KV store.

Source: formosa.js:332–340, checkRateLimitKV function

Line References:

• Checkin: formosa.js:366
• Survey: formosa.js:257
• Track sync: formosa.js:480
• Admin: formosa.js:68, 632, 979, 1019, 1104, 1135, 1217

Response Format

Success Response

{
  "ok": true,
  "data": { /* endpoint-specific data */ }
}

Error Response

{
  "error": "Human-readable error message"
}

HTTP status codes:

• 200 OK — Standard successful response
• 202 Accepted — Asynchronous operation queued (e.g., checkin via KV buffer)
• 204 No Content — OPTIONS CORS preflight
• 400 Bad Request — Invalid request payload
• 401 Unauthorized — Missing or invalid authentication token
• 413 Payload Too Large — Request body exceeds 100 KB
• 429 Too Many Requests — Rate limit exceeded

Asynchronous Operations

Checkin requests return HTTP 202 Accepted with an 8-second timeout for async KV writes via ctx.waitUntil(). Callers should not wait for completion before responding to the user.

Constants Reference

KV Store TTLs (Time-to-Live)

All values in seconds. Source: formosa.js

Speed-Based Transport Mode Inference

Source: formosa.js:877–886

GPS Noise Filters:

• Skip if speed > 300 km/h (satellite/noise error)
• Skip if distance < 10 m or elapsed time < 30 seconds (static/erratic)
• Source: formosa.js:919

Payload Size Constraints

Level System

Achievement Titles (TITLES Array)

Source: formosa.js:846–856

Users progress through 9 levels based on cumulative distance (km) AND check-in count. Both thresholds must be met simultaneously.

Rank Computation

computeRank(km, checkins)

Iterates TITLES array from highest to lowest level. Returns the first level where both conditions are true:

• km >= levelThreshold
• checkins >= levelThreshold

Source: formosa.js:858

Achievement Card Unlock Conditions

Three conditions must ALL be satisfied:

1. Checkins ≥ 3 — Minimum participation threshold
2. Survey Completed = 1 — Must have submitted survey (Q1–Q10)
3. Phone IS NOT NULL — Phone number on file

If any condition fails, the achievement card remains locked.

Carbon Coefficients

GWP Factors (Global Warming Potential)

Source: formosa.js:1907–1911

Standard emission coefficients for transportation modes, measured in kg CO₂ equivalent per km (except noted).

Inference: Unknown modes default to bus coefficient (0.47515 kg CO₂e/km) for conservative estimation.

Three-Tier Authorization

Role Levels & Permissions

Source: formosa.js:19–44

Three-tier role system controls API access:

ROLE_LEVEL = {
  owner: 3,
  manager: 2,
  volunteer: 1
}

Role Definitions

Authorization Functions

requireAdmin()
Requires role level ≥ 2 (owner or manager). Used for sensitive operations like survey list, carbon aggregates, user list, status changes, role management.

requireAnyRole()
Requires any valid token (level ≥ 1). Used for read-only volunteer access.

Appendix: Source Code References

All constants, line numbers, and behavioral specifications in this document are derived from:

• index.js — Route handler definitions (commit 99e8fcc, main branch)
• formosa.js — Business logic, constants, rate limiting (commit 99e8fcc, main branch)

For verification of any value or implementation detail, consult the source files directly.

Last Updated: 2026-04-04 by Formosa Engineering Team
Next Review: 2026-05-04