docs/reference/API_INVENTORY.md

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.