7 API Surface

jlightner edited this page 2026-04-04 10:31:50 -05:00

Unescape Escape

Table of Contents

• API Surface
• Public Endpoints (11)
• Technique Detail Fields (22)
• Browse Endpoints (5)
• Chat Endpoint (1)
• Auth Endpoints (4)
• Follow Endpoints (4) — M022/S02
• Creator Highlight Endpoints (4) — M022/S01
• Consent Endpoints (5)
• Posts Endpoints (5) — M023/S01
• File Endpoints (2) — M023/S01
• Report Endpoints (3)
• Admin Endpoints
• Pipeline Admin (20+)
• Highlight Admin (4)
• Personality Extraction (1) — M022/S06
• Shorts Admin (3) — M023/S03
• Shorts Template Admin (2) — M024/S04
• Other Endpoints (2)
• Response Conventions
• Notifications (M025/S01)
• Creator Transparency & Export (M025/S05, S07)
• Onboarding (M025/S03)
• Usage & Rate Limiting (M025/S04)
• Authentication

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

API Surface

74 API endpoints grouped by domain. All served by FastAPI under /api/v1/.

Public Endpoints (11)

Method	Path	Response Shape	Notes
GET	/health	{status, service, version, database}	Health check
GET	/api/v1/stats	{technique_count, creator_count}	Homepage stats
GET	/api/v1/search?q=&creator=	{items, partial_matches, total, query, fallback_used, cascade_tier}	LightRAG primary + Qdrant fallback, optional creator cascade (D039, D040)
GET	/api/v1/search/suggestions?q=	{suggestions: [{text, type}]}	Typeahead autocomplete
GET	/api/v1/search/popular	{items: [{query, count}]}	Popular searches (D025)
GET	/api/v1/techniques?limit=&offset=	{items, total, offset, limit}	Paginated technique list
GET	/api/v1/techniques/random	{slug}	Returns JSON slug (not redirect)
GET	/api/v1/techniques/{slug}	22-field object	Full technique detail with relations
GET	/api/v1/techniques/{slug}/versions	{items, total}	Version history
GET	/api/v1/techniques/{slug}/versions/{n}	Version detail	Single version
GET	/api/v1/public/shorts/{share_token}	{format, dimensions, duration, creator_name, highlight_title, download_url}	Unauthenticated. Returns metadata + presigned MinIO URL. 404 for missing/non-complete shorts (M024/S01)

Technique Detail Fields (22)

title, slug, topic_category, topic_tags, summary, body_sections, body_sections_format, signal_chains, plugins, id, creator_id, creator_name, creator_slug, source_quality, view_count, key_moment_count, created_at, updated_at, key_moments, creator_info, related_links, version_count, source_videos.

Browse Endpoints (5)

Method	Path	Response Shape	Notes
GET	/api/v1/creators?sort=&genre=	{items, total, offset, limit}	sort: random|alpha|views
GET	/api/v1/creators/{slug}	16-field object	Includes genre_breakdown, techniques, social_links, follower_count, personality_profile
GET	/api/v1/topics	[{name, description, sub_topics}]	⚠️ Bare list (not paginated)
GET	/api/v1/topics/{cat}/{sub}	{items, total, offset, limit}	Subtopic techniques
GET	/api/v1/topics/{cat}	{items, total, offset, limit}	Category techniques

Chat Endpoint (1)

Method	Path	Auth	Purpose
POST	/api/v1/chat	None	Streaming Q&A — SSE response with sources, tokens, done event. See Chat-Engine

Request fields: query (required, 1-1000 chars), creator (optional slug/UUID), conversation_id (optional UUID for multi-turn threading)

Auth Endpoints (4)

All under prefix /api/v1/auth/. JWT-protected except registration and login.

Method	Path	Auth	Purpose
POST	/auth/register	None (invite code required)	Create account with invite code, email, password, display_name. Optional creator_slug links to Creator. Returns UserResponse (201).
POST	/auth/login	None	Email + password → JWT access token (HS256, 24h expiry). Returns {access_token, token_type}.
GET	/auth/me	Bearer JWT	Current user profile. Returns UserResponse.
PUT	/auth/me	Bearer JWT	Update display_name and/or password (requires current_password for password changes). Returns UserResponse.

Follow Endpoints (4) — M022/S02

All require Bearer JWT.

Method	Path	Purpose
POST	/api/v1/follows/{creator_id}	Follow a creator (idempotent via INSERT ON CONFLICT DO NOTHING)
DELETE	/api/v1/follows/{creator_id}	Unfollow a creator
GET	/api/v1/follows/{creator_id}/status	Check if current user follows this creator
GET	/api/v1/follows/me	List creators the current user follows

Creator Highlight Endpoints (4) — M022/S01

Creator-scoped highlight review. Requires Bearer JWT with creator ownership.

Method	Path	Purpose
GET	/api/v1/creator/highlights	List highlights for authenticated creator (status/shorts_only filters)
GET	/api/v1/creator/highlights/{id}	Detail with score_breakdown and key_moment
PATCH	/api/v1/creator/highlights/{id}/status	Update status (approve/reject)
PATCH	/api/v1/creator/highlights/{id}/trim	Update trim_start/trim_end

Consent Endpoints (5)

All under prefix /api/v1/consent/. All require Bearer JWT.

Method	Path	Auth	Purpose
GET	/consent/videos	Creator or Admin	List consent records for current creator's videos. Admin sees all. Paginated (offset, limit).
GET	/consent/videos/{video_id}	Creator (owner) or Admin	Single video consent status. Returns defaults if no consent record exists.
PUT	/consent/videos/{video_id}	Creator (owner) or Admin	Upsert consent flags (partial update). Creates audit log entries for each changed field.
GET	/consent/videos/{video_id}/history	Creator (owner) or Admin	Versioned audit trail of consent changes for a video.
GET	/consent/admin/summary	Admin only	Aggregate consent flag counts across all videos.

Posts Endpoints (5) — M023/S01

All under prefix /api/v1/posts/. Public list/get; create/update/delete require Bearer JWT with creator ownership.

Method	Path	Auth	Purpose
GET	/api/v1/posts?creator_id=	Public (auth-aware)	List published posts; shows drafts to owner
GET	/api/v1/posts/{id}	Public (auth-aware)	Single post detail
POST	/api/v1/posts	Bearer JWT (creator)	Create post with title, body (Tiptap JSON), is_published
PUT	/api/v1/posts/{id}	Bearer JWT (creator owner)	Update post fields
DELETE	/api/v1/posts/{id}	Bearer JWT (creator owner)	Delete post + cascade delete attachments from MinIO

File Endpoints (2) — M023/S01

Method	Path	Auth	Purpose
POST	/api/v1/files/upload	Bearer JWT	Multipart file upload to MinIO, returns PostAttachment
GET	/api/v1/files/{attachment_id}/download	Public	Presigned MinIO download URL (redirect)

Report Endpoints (3)

Method	Path	Purpose
POST	/api/v1/reports	Submit content report
GET	/api/v1/admin/reports	List all reports
PATCH	/api/v1/admin/reports/{id}	Update report status

Admin Endpoints

Pipeline Admin (20+)

All under prefix /api/v1/admin/pipeline/.

Method	Path	Purpose
GET	/admin/pipeline/videos	Paginated video list with pipeline status
POST	/admin/pipeline/trigger/{video_id}	Trigger pipeline for video
POST	/admin/pipeline/clean-retrigger/{video_id}	Wipe output + reprocess
POST	/admin/pipeline/revoke/{video_id}	Revoke active pipeline task
POST	/admin/pipeline/rerun-stage/{video_id}	Re-run specific stage
GET	/admin/pipeline/events	Pipeline event log
GET	/admin/pipeline/runs	Pipeline run history
GET	/admin/pipeline/chunking-inspector/{video_id}	Inspect chunking results
GET	/admin/pipeline/embed-status	Embedding/Qdrant health
GET	/admin/pipeline/debug-mode	Get debug mode state
POST	/admin/pipeline/debug-mode	Set debug mode state
GET	/admin/pipeline/token-summary	Token usage summary
GET	/admin/pipeline/stale-pages	Pages needing regeneration
POST	/admin/pipeline/bulk-resynthesize	Regenerate all technique pages
POST	/admin/pipeline/wipe-all-output	Delete all pipeline output
POST	/admin/pipeline/optimize-prompt	Trigger prompt optimization
POST	/admin/pipeline/reindex-all	Rebuild Qdrant index
GET	/admin/pipeline/worker-status	Celery worker health
GET	/admin/pipeline/recent-activity	Recent pipeline events
POST	/admin/pipeline/creator-profile/{creator_id}	Update creator profile
POST	/admin/pipeline/avatar-fetch/{creator_id}	Fetch creator avatar

Highlight Admin (4)

Method	Path	Purpose
POST	/admin/highlights/detect/{video_id}	Score all KeyMoments for a video
POST	/admin/highlights/detect-all	Score all videos
GET	/admin/highlights/candidates	Paginated candidate list
GET	/admin/highlights/candidates/{id}	Single candidate with score_breakdown

Personality Extraction (1) — M022/S06

Method	Path	Purpose
POST	/api/v1/admin/creators/{slug}/extract-profile	Queue personality profile extraction task

Shorts Admin (3) — M023/S03

Method	Path	Purpose
POST	/api/v1/admin/shorts/{highlight_id}/generate	Queue short generation for approved highlight (3 presets). Accepts captions boolean param (M024/S04) — 202 response
GET	/api/v1/admin/shorts/{highlight_id}	List generated shorts for a highlight with per-preset status
GET	/api/v1/admin/shorts/{short_id}/download	Presigned MinIO download URL for completed short

Shorts Template Admin (2) — M024/S04

Method	Path	Purpose
GET	/api/v1/admin/creators/{id}/shorts-template	Returns JSONB template config for creator
PUT	/api/v1/admin/creators/{id}/shorts-template	Updates template config with validation (hex color, duration 1.0–5.0)

Other Endpoints (2)

Method	Path	Notes
POST	/api/v1/ingest	Transcript upload
GET	/api/v1/videos	⚠️ Bare list (not paginated)

Response Conventions

Standard paginated response:

{
  "items": [...],
  "total": 83,
  "offset": 0,
  "limit": 20
}

Known inconsistencies:

• GET /topics returns bare list instead of paginated dict
• GET /videos returns bare list instead of paginated dict
• Search uses items key (not results)
• /techniques/random returns JSON {slug} (not HTTP redirect)

New endpoints should follow the {items, total, offset, limit} paginated pattern.

Notifications (M025/S01)

Method	Path	Auth	Notes
GET	/api/v1/notifications/preferences	Bearer JWT	Returns notification_preferences JSONB
PUT	/api/v1/notifications/preferences	Bearer JWT	Update digest frequency, enabled flags
GET	/api/v1/notifications/unsubscribe?token=	Public	JWT-signed token with expiry; renders styled HTML result

Creator Transparency & Export (M025/S05, S07)

Method	Path	Auth	Notes
GET	/api/v1/creator/transparency	Bearer JWT	Full entity graph: technique pages, key moments, cross-refs, source videos, tags
GET	/api/v1/creator/export	Bearer JWT	GDPR-style ZIP download (12 data tables + export_metadata.json)

Onboarding (M025/S03)

Method	Path	Auth	Notes
POST	/api/v1/auth/onboarding-complete	Bearer JWT	Sets onboarding_completed = true on User

Usage & Rate Limiting (M025/S04)

Method	Path	Auth	Notes
GET	/api/v1/admin/usage	Admin	Token consumption: period totals, top creators/users, daily counts

Chat requests are rate-limited per-user (30/hr), per-IP (10/hr), and per-creator (60/hr) via Redis sliding-window. Returns HTTP 429 with retry_after header when exceeded.

Authentication

JWT-based authentication added in M019. See Authentication for full details.

• Public endpoints (search, browse, techniques, chat) require no auth
• Auth endpoints (/auth/register, /auth/login) are open; /auth/me requires Bearer JWT
• Follow endpoints require Bearer JWT
• Creator endpoints (/creator/*) require Bearer JWT with creator ownership verification
• Consent endpoints require Bearer JWT with ownership verification
• Admin endpoints (/admin/*) are accessible to anyone with network access (auth planned for future milestone)

---

See also: Architecture, Data-Model, Frontend, Authentication

Chrysopedia Wiki

• Home
• Newcomer-Guide

Architecture

• Architecture
• Authentication
• Impersonation
• Data-Model
• Pipeline
• Player

Features

• Chat-Engine
• Search-Retrieval
• Highlights
• Personality-Profiles
• Posts (via Post Editor)

Reference

• API-Surface
• Frontend
• Configuration
• Decisions

Operations

• Deployment
• Monitoring
• Development-Guide
• Agent-Context