# API Inventory ## Phạm vi Nguồn audit: AutoCode Video `codex/hf-prod-sync` tại `595ccdfaf45ff83473f2da8fd2c71d491828e5f5`. Xác định **82 endpoint HTTP**. Đây là inventory count, không phải bằng chứng completeness: - 78 endpoint thuộc Node app: 77 router declaration cộng Node `/health`. - Hai font route nằm trong 77 declaration được đếm nhưng có implementation status `UNREACHABLE` vì router không được mount. - Bốn endpoint thuộc Modal gateway; Modal `/health` là endpoint riêng, không phải Node `/health` bị đếm hai lần. - Dynamic API nội bộ do HyperFrames preview cung cấp không được đếm vì surface phụ thuộc package runtime. Cột `Status / evidence` mô tả implementation status/reachability trong source. `Active` trong bảng cũ phải được đọc là `SOURCE_VERIFIED` ở mức source, không phải xác minh runtime. Mọi endpoint là `NOT_RUNTIME_VERIFIED` trong Phase 0; không endpoint nào được gán `RUNTIME_VERIFIED` hoặc `PARTIAL_RUNTIME_EVIDENCE`. Auth mặc định cho các route `/api/**` ngoài auth là “session nếu `AUTOCODE_AUTH_ENABLED=true`; mở/local-admin nếu false”. Evidence mount: `server.js`. Không sao chép implementation route. ## Health và authentication (16) | Method | Path | Authentication | Request | Response | Side effect | Storage | Frontend consumer | Status / evidence | | ------ | --------------------------- | -------------------------------- | -------------------------------- | ------------------------------- | ---------------------------------------------- | ---------------------------------------- | --------------------------- | ----------------------------------------------- | | GET | `/health` | Public hoặc optional Basic Auth | Không | Service/render/delivery summary | Không | Env | Ops | Active; `server.js` | | POST | `/api/auth/test-login` | Internal bearer + feature flag | Test token context | Session + test user | Tạo/upsert test admin/session | SQLite | Test/smoke | Test-only; `auth.js` | | POST | `/api/auth/waitlist` | Public | name, email | success | Tạo/update pending user | SQLite | Landing | Active; `auth.js`, `public/landing.js` | | POST | `/api/auth/register` | Public nhưng flag local-password | name, email, password | user + session | Tạo user/session | SQLite | Không thấy consumer hosted | Legacy/local; `auth.js` | | POST | `/api/auth/login` | Public nhưng flag local-password | email, password | user + session | Cập nhật login/session | SQLite | Không thấy form chính | Legacy/local; `auth.js` | | POST | `/api/auth/logout` | Session optional | Cookie | success | Xóa session/cookie | SQLite | Account menu | Active; `auth.js`, `public/app.js` | | GET | `/api/auth/me` | Cookie optional | Không | authenticated + user | Có thể làm mới lookup cache | SQLite/cache | Bootstrap | Active; `auth.js` | | GET | `/api/auth/status` | Cookie/internal token optional | Không | auth mode + user | Không | SQLite/env/cache | Landing/dashboard, CF smoke | Active; `auth.js` | | GET | `/api/auth/admin/users` | Admin session | Không | users | Không | SQLite | Admin | Active; `auth.js`, `public/app.js` | | PATCH | `/api/auth/admin/users/:id` | Admin session | role/status/name/email | updated user | Update user, approval fields | SQLite | Admin editor | Active; `auth.js`, `public/app.js` | | DELETE | `/api/auth/admin/users/:id` | Admin session | user ID | deleted ID | Xóa user/session có guard last/protected admin | SQLite transaction | Admin editor | Active, destructive; `auth.js`, `public/app.js` | | GET | `/api/auth/admin/stats` | Admin session | Không | user/job/activity aggregates | Không | SQLite + activity DB + disk-derived data | Admin overview | Active/partial; `auth.js`, `public/app.js` | | GET | `/api/auth/google` | Public | optional login_hint/state cookie | Redirect Google | Set OAuth state cookie | Cookie/env | Landing | Active; `auth.js` | | GET | `/api/auth/google/callback` | OAuth state | code, state | Redirect dashboard/error | Upsert user, session, last login | SQLite | Google redirect | Active; `auth.js` | | GET | `/api/auth/github` | Public | State cookie | Redirect GitHub | Set state cookie | Cookie/env | Không thấy CTA chính | Unclear; `auth.js` | | GET | `/api/auth/github/callback` | OAuth state | code, state | Redirect/error | Upsert user/session | SQLite | GitHub redirect | Unclear; `auth.js` | ## Admin operations (4) | Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence | | ------ | --------------------- | -------------- | -------------------------------- | -------------------------- | ----------------------------------------------------- | --------------------------- | ------------- | --------------------------------- | | GET | `/api/admin/pricing` | Admin | Không | pricing | Có thể refresh Modal price projection | AppSetting/web price | Admin pricing | Active/partial; `routes/admin.js` | | PATCH | `/api/admin/pricing` | Admin | pricing | normalized pricing | Lưu token/provider prices; Modal portion auto-derived | AppSetting | Admin pricing | Active; `routes/admin.js` | | GET | `/api/admin/jobs` | Admin | userId/status/query/limit/offset | paged jobs + costs/summary | Không | SQLite + project files | Admin jobs | Active/partial; `routes/admin.js` | | GET | `/api/admin/jobs/:id` | Admin | job ID | detail + cost | Không | SQLite + project files/logs | Job detail | Active/partial; `routes/admin.js` | ## Asset library và BGM (12) | Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence | | ------ | -------------------------------------- | -------------------------------------------- | --------------------------------------- | ------------------------ | ---------------------------------- | --------------------------------- | ----------------- | --------------------------------------------- | | GET | `/api/assets/library` | Conditional session | Không | Sanitized asset catalog | Warm/read cache | Shared files/sidecars | DAM/asset lock | Active; `routes/assets.js` | | GET | `/api/assets/scan-duplicates` | Admin hosted | Không | Exact duplicate groups | Đọc/hash | Shared files | DAM scanner | Active; `routes/assets.js` | | GET | `/api/assets/scan-semantic-duplicates` | Admin hosted | threshold | Similarity groups | Không | Sidecar embeddings | DAM scanner | Active/partial; `routes/assets.js` | | POST | `/api/assets/update-metadata` | Admin hosted | filename/type + patch | updated metadata | Ghi sidecar, invalidate cache | Shared files | DAM metadata/bulk | Active; `routes/assets.js` | | POST | `/api/assets/delete-library` | Admin hosted | filename, type | success | Xóa media + sidecar | Shared files | DAM | Active, permanent; `routes/assets.js` | | POST | `/api/assets/use-asset` | Conditional session | projectId, filename, type | project-relative path | Copy asset/sidecar vào project | Shared + project files | Asset lock/detail | Active; `routes/assets.js` | | POST | `/api/assets/upload-library` | Admin hosted | Raw bytes; filename/type/config headers | metadata | Lưu file/sidecar, enqueue analysis | Shared files + RAM analysis queue | DAM upload | Active/partial; `routes/assets.js` | | POST | `/api/assets/analyze-library` | Admin hosted | filename/type/guidance/config | pending/current metadata | Enqueue AI analysis | Shared sidecar + RAM queue | Re-analyze | Active/partial; `routes/assets.js` | | GET | `/api/assets/bgm` | Conditional session | Không | Tracks | Đọc metadata | Shared audio | BGM modal | Active; `routes/bgm.js` | | POST | `/api/assets/upload-music` | Conditional session, không admin guard riêng | Raw audio + headers | metadata | Ghi shared BGM + enqueue analysis | Shared files | BGM upload | Active nhưng permission lệch; `routes/bgm.js` | | POST | `/api/assets/delete-music` | Conditional session, không admin guard riêng | filename | success | Xóa shared BGM | Shared files | BGM modal | Active, destructive; `routes/bgm.js` | | POST | `/api/assets/select-bgm` | Conditional session | projectId, filename/none | project path/success | Copy/xóa project BGM | Shared + project files | Create/Studio | Active; `routes/bgm.js` | ## Composition, generation, TTS và direct render (9) | Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence | | ------ | ------------------------------- | ----------------------------------- | --------------------------------- | ------------------------------- | ------------------------------------------- | ------------------------ | ----------------------------- | -------------------------------------------------------- | | GET | `/api/composition/document` | Conditional session + project scope | projectId | HTML, revision, project info | Không | Project `index.html` | Studio editor | Active; `routes/composition.js`, `src/studio-editor.jsx` | | PUT | `/api/composition/document` | Conditional session + scope | projectId, HTML, revision | new revision | Sanitize/write HTML/checkpoint/job preview | Project files/meta | Studio editor | Active; `routes/composition.js` | | POST | `/api/composition/upload-image` | Conditional session + scope | Raw image + headers/project | URL | Write project asset | Project files | Dashboard/editor | Active; `routes/composition.js`, `public/app.js` | | POST | `/api/composition/upload-media` | Conditional session + scope | Raw media + headers/project | URL/type | Write project asset | Project files | Studio editor | Active; `routes/composition.js`, `src/studio-editor.jsx` | | POST | `/api/composition/update-scene` | Conditional session + scope | sceneId, narration, innerHTML | success | Mutate/sanitize HTML/checkpoint/job preview | Project files/meta | Quick scene edit | Active/partial; `routes/composition.js`, `public/app.js` | | POST | `/api/generate` | Conditional session | prompt/url/openai config | composition result/assets | Capture/scrape/write project | Project/shared files | Không thấy dashboard consumer | Legacy/duplicate; `routes/generate.js` | | POST | `/api/compile` | Conditional session | narration/duration/caption/config | timed words/compiled result | Transcribe/inject/write composition assets | Project files | Không thấy dashboard consumer | Legacy/duplicate; `routes/compile.js` | | POST | `/api/tts/create` | Conditional session | text/Omnivoice config | external job ID | Tạo TTS job | Provider | Không thấy dashboard consumer | Legacy/duplicate; `routes/tts.js` | | GET | `/api/tts/status/:jobId` | Conditional session | baseUrl/token/target LUFS | status/progress hoặc audio path | Poll/download/normalize narration | Provider + project files | Không thấy dashboard consumer | Legacy, token in query; `routes/tts.js` | ## Direct render và Forge lifecycle (10) | Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence | | ------ | -------------------------- | ------------------------------------- | ------------------------------- | -------------------------- | ---------------------------------------- | ---------------------------- | ----------------------------- | ----------------------------------------------- | | GET | `/api/render` | Conditional session + project context | projectId qua context/referer | SSE log + video URL/error | Materialize registry, render MP4 | Project files, local/Modal | Không thấy dashboard consumer | Legacy/duplicate; `routes/render.js` | | POST | `/api/forge/start` | Conditional session + scope | prompt/project/config/assets | 202 project/job/queue info | Tạo project nếu cần, checkpoint, enqueue | RAM + SQLite + project files | Main Create | Active core; `routes/forge.js`, `public/app.js` | | POST | `/api/forge/edit` | Conditional session + scope | prompt/renderOnly/config/assets | accepted job | Enqueue edit/rerender | RAM + SQLite + project files | Studio AI edit/quick rerender | Active; `routes/forge.js` | | GET | `/api/forge/events` | Conditional session + scope | projectId | SSE status/log/stats | Add/remove event listener | RAM job events | Studio progress | Active; `routes/forge.js` | | GET | `/api/forge/status` | Conditional session + scope | projectId, summary/mode | live/persisted status | Có thể load job from disk | RAM/meta/log/DB | Poll fallback/render dock | Active; `routes/forge.js` | | GET | `/api/forge/report` | Conditional session + scope | projectId, section | report section | Đọc/parse artifacts | Project files | Report modal | Active; `routes/forge.js` | | POST | `/api/forge/cancel` | Conditional session + scope | projectId | success | Remove queued/abort/kill, mark failed | RAM + meta/DB/log | Studio | Active; `routes/forge.js` | | POST | `/api/forge/resume` | Conditional session + scope | projectId + provider configs | accepted/resume info | Enqueue from checkpoint | RAM + meta/DB/files | Studio retry | Active; `routes/forge.js` | | POST | `/api/forge/pause` | Conditional session + scope | projectId | success | Mark paused/kill process | RAM + meta/DB/log | Studio | Active/partial; `routes/forge.js` | | POST | `/api/forge/resume-paused` | Conditional session + scope | projectId | success/conflict | Re-enqueue paused job | RAM + meta/DB | Studio | Active/partial; `routes/forge.js` | ## Projects (11) | Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence | | ------ | ------------------------------- | ---------------------------------- | ------------------------------------- | ----------------------------- | ---------------------------------------- | ------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------- | | GET | `/api/projects` | Conditional session + owner filter | paging/search/status/tags/model/ratio | paged projects + totals | Disk fallback/sync read | SQLite + disk | Projects/render dock | Active; `routes/projects.js` | | GET | `/api/projects/:id` | Conditional session + ownership | ID | project detail | Load disk/job state | SQLite + disk + RAM | Select Studio | Active; `routes/projects.js` | | GET | `/api/projects/:id/diagnostics` | Conditional session + ownership | ID | lint/animation/error markdown | Có thể generate diagnostics | Project files/subprocess | Error/report UI | Active/partial; `routes/projects.js` | | POST | `/api/projects` | Conditional session | name, description | projectId/name | Tạo folders/config/meta + DB record | Filesystem + SQLite | Không thấy current dashboard call; CF smoke mong contract khác | Alternate/legacy; `routes/projects.js` | | POST | `/api/projects/select` | Conditional session + ownership | projectId | resolved IDs | Không | Filesystem | Project selection | Active; `routes/projects.js` | | POST | `/api/projects/bulk-delete` | Conditional session + ownership | IDs | deleted + errors | DB delete + recursive delete | SQLite + filesystem | Project manage | Active, critical destructive risk; `routes/projects.js` | | DELETE | `/api/projects/:id` | Conditional session + ownership | ID | success | DB delete + recursive delete | SQLite + filesystem | Không thấy direct UI consumer | Active alternate/destructive; `routes/projects.js` | | POST | `/api/projects/clone` | Conditional session + ownership | source ID | new project | Copy tree/reset meta/history + DB create | Filesystem + SQLite | Project quick menu | Active; `routes/projects.js` | | POST | `/api/projects/toggle-favorite` | Conditional session + ownership | ID | favorite | Write meta + sync DB | Filesystem + SQLite | Project quick menu | Active; `routes/projects.js` | | POST | `/api/projects/toggle-posted` | Conditional session + ownership | ID | posted | Write meta + sync DB | Filesystem + SQLite | Project quick menu | `SOURCE_VERIFIED`, legacy semantics; không thuộc Oloka MVP; `routes/projects.js` | | GET | `/api/projects/:id/thumbnail` | Conditional session + ownership | ID | PNG or generated SVG | Có thể enqueue/generate thumbnail | Project files/process | Project cards | Active/partial; `routes/projects.js` | ## Status, media và settings (7) | Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence | | ------ | ------------------------------- | --------------------------- | ------------------- | ------------------------------------ | --------------------- | -------------------------- | --------------------- | ------------------------------------------- | | GET | `/api/status` | Conditional session + scope | projectId | composition/video flags, URL/version | Disk fallback | SQLite + files | Studio selection | Active; `routes/status.js` | | GET | `/api/status/modal-render` | Conditional session | Không | provider config + gateway health | Gọi Modal health | Env/provider | Settings | Active; `routes/status.js`, `public/app.js` | | GET | `/api/media/video` | Conditional session + scope | projectId, renderId | 307 redirect | Sinh/cache signed URL | Env + expected object path | Video player/download | Active; `routes/media.js` | | GET | `/api/settings/shared` | Conditional session | Không | masked config + edit capability | Không | AppSetting | Settings/bootstrap | Active; `routes/settings.js` | | PATCH | `/api/settings/shared` | Admin hosted | config | masked saved config | Upsert config/secrets | AppSetting SQLite | Settings save | Active; `routes/settings.js` | | POST | `/api/settings/list-models` | Admin hosted | baseUrl, apiKey | models/capabilities | External request | Provider | Model selector | Active/partial; `routes/settings.js` | | POST | `/api/settings/test-connection` | Admin hosted | type, config | success/error | External probe | Provider | Settings | Active/partial; `routes/settings.js` | ## Quality và social (7) | Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence | | ------ | -------------------------- | --------------------------- | ----------------------------------------------- | -------------------- | ---------------------------------------- | ------------------------ | --------------------------- | -------------------------------------------- | | GET | `/api/quality/report` | Conditional session + scope | projectId | report | Không | Project JSON | Report UI | Active; `routes/quality.js` | | GET | `/api/quality/memory` | Conditional session | aspectRatio | verified rules | Không | `quality-memory/**` | Không thấy main consumer rõ | Active/unclear; `routes/quality.js` | | GET | `/api/quality/codex-brief` | Conditional session + scope | projectId | markdown/path/scan | Ghi repair brief | Project files | Error copy/report | Active; `routes/quality.js`, `public/app.js` | | POST | `/api/quality/config` | Conditional session | recognition configs | configured flags | Ghi config vào RAM process | RAM | Settings sync | Active/ephemeral; `routes/quality.js` | | POST | `/api/quality/analyze` | Conditional session + scope | projectId + vision configs | quality report | Sample/analyze video, persist job/report | Project files/meta | Manual QA | Active/partial; `routes/quality.js` | | POST | `/api/quality/feedback` | Conditional session + scope | finding | updated report | Ghi feedback/memory/report | Project + quality memory | Report UI/ops | Active/partial; `routes/quality.js` | | POST | `/api/social/publish` | Conditional session + scope | projectId, platforms, config, title/description | per-platform results | Upload external video | Project file + platform | Publish modal | Active/partial; `routes/socialPublish.js` | ## Font routes chưa được mount (2) | Method | Intended path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence | | ------ | --------------------- | ------------------------------ | ------- | -------------- | ----------- | ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------ | | GET | `/api/fonts` | Nếu mount: conditional session | Không | font inventory | Scan files | Font inputs/assets | Caption font selector | **Unreachable/unclear:** router tồn tại, frontend gọi, `server.js` không mount; `routes/fonts.js`, `public/app.js` | | GET | `/api/fonts/file/:id` | Nếu mount: conditional session | Font ID | font bytes | Không | Font files | Browser font loader | **Unreachable/unclear**; `routes/fonts.js`, `services/fontInventoryService.js` | ## Modal gateway (4) | Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence | | ------ | ----------------------- | ---------------------------- | ------------------------------- | --------------------------- | ----------------------- | ---------------- | -------------------------- | -------------------------------------- | | GET | `/health` | Public trong gateway | Không | HyperFrames version/timeout | Không | Runtime | Node health route/operator | Active; `deploy/modal-renderer/app.py` | | POST | `/api/render` | Bearer nếu secret configured | projectId, preset, base64 files | call_id | Spawn Modal function | Modal job/volume | Node Modal provider | Active; `deploy/modal-renderer/app.py` | | GET | `/api/render/{call_id}` | Bearer nếu configured | call ID | running/done/failed | Poll function | Modal call | Node Modal provider | Active; `deploy/modal-renderer/app.py` | | GET | `/renders/{name}` | Bearer nếu configured | Safe filename | MP4 | Reload volume/read file | Modal Volume | Node download step | Active; `deploy/modal-renderer/app.py` | ## API conclusions cho Oloka - Giữ một command API cho generation/edit/render, không duy trì direct pipeline endpoints trùng Forge. - Tách command acceptance (`202`) khỏi durable job/read model/events. - Mọi resource dùng opaque ID và tenant scope; không để filename/path làm identity. - Upload/download dùng object storage URL có checksum/quota, không raw body qua app cho file lớn. - Sinh OpenAPI/typed contracts và route reachability tests để tránh router tồn tại nhưng không mount. - Admin/provider/social APIs cần authorization policy thống nhất và idempotency/audit.