Official REST API specification for Tenimal. Architected for scalable communities, interactive video courses, watch progress metrics, creator analytics, and Supabase Row Level Security.
Core architectural parameters for integrating with the Tenimal API ecosystem.
Clear separation between Phase 1 Core API specification and Phase 2 Future extensions.
Detailed specs for every endpoint: Description, Authentication requirement, Roles, and Standardized JSON Response.
{
"success": true,
"data": {
"id": "usr_94f812a4",
"username": "alex_dev",
"email": "alex@tenimal.info",
"bio": "Building next-gen open source education & tech communities.",
"avatar_url": "https://tenimal.info/avatars/alex.png",
"account_preferences": {
"theme": "dark",
"notifications_enabled": true,
"email_digest": "weekly"
},
"public_profile": true,
"role": "creator",
"created_at": "2026-01-15T10:30:00Z"
}
}{
"bio": "Full-stack developer building AI apps on Tenimal.",
"avatar_url": "https://tenimal.info/avatars/alex_v2.png",
"account_preferences": {
"theme": "system",
"notifications_enabled": true
}
}{
"success": true,
"data": {
"id": "usr_94f812a4",
"username": "alex_dev",
"bio": "Full-stack developer building AI apps on Tenimal.",
"avatar_url": "https://tenimal.info/avatars/alex_v2.png",
"updated_at": "2026-08-26T01:10:00Z"
}
}{
"success": true,
"data": {
"id": "usr_94f812a4",
"username": "alex_dev",
"bio": "Full-stack developer building AI apps on Tenimal.",
"avatar_url": "https://tenimal.info/avatars/alex.png",
"public_profile": true,
"joined_at": "2026-01-15T10:30:00Z"
}
}{
"success": true,
"data": {
"courses": [
{
"id": "course_123",
"title": "JavaScript Mastery",
"slug": "javascript-mastery",
"description": "Master modern ES6+, async patterns, V8 engine internals & web APIs.",
"category": "Programming",
"difficulty_level": "Intermediate",
"status": "published",
"lessons_count": 20,
"is_featured": true,
"creator_id": "usr_94f812a4"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total_items": 42,
"total_pages": 5
}
}
}{
"success": true,
"data": {
"id": "course_123",
"title": "JavaScript Mastery",
"slug": "javascript-mastery",
"description": "Master modern ES6+, async patterns, V8 engine internals & web APIs.",
"category": "Programming",
"difficulty_level": "Intermediate",
"status": "published",
"lessons_count": 20,
"total_duration_sec": 28800,
"is_featured": true,
"creator": {
"id": "usr_94f812a4",
"username": "alex_dev",
"avatar_url": "https://tenimal.info/avatars/alex.png"
}
}
}{
"title": "Building Real-Time Apps with Supabase & React",
"category": "Programming",
"difficulty_level": "Intermediate",
"description": "Learn RLS, WebSockets, and Postgres functions step-by-step.",
"status": "draft"
}{
"success": true,
"data": {
"id": "course_456",
"title": "Building Real-Time Apps with Supabase & React",
"status": "draft",
"creator_id": "usr_94f812a4",
"created_at": "2026-08-26T01:12:00Z"
}
}{
"status": "published",
"is_featured": true
}{
"success": true,
"data": {
"id": "course_123",
"status": "published",
"updated_at": "2026-08-26T01:15:00Z"
}
}{
"success": true,
"data": {
"deleted": true,
"id": "course_123",
"message": "Course deleted successfully"
}
}{
"success": true,
"data": {
"course_id": "course_123",
"lessons": [
{
"id": "les_01",
"order": 1,
"title": "Introduction to V8 & Event Loop",
"duration_sec": 720,
"is_free": true
},
{
"id": "les_02",
"order": 2,
"title": "Promises & Async/Await",
"duration_sec": 1140,
"is_free": false
}
]
}
}{
"title": "Closures & Garbage Collection",
"description": "Memory allocation and lexical environments in JS.",
"order": 3,
"duration_sec": 900,
"is_free": false,
"video_url": "https://tenimal.info/videos/les_03.mp4"
}{
"success": true,
"data": {
"id": "les_03",
"course_id": "course_123",
"order": 3,
"title": "Closures & Garbage Collection"
}
}{
"success": true,
"data": {
"id": "les_03",
"title": "Closures & Garbage Collection (Updated)",
"updated_at": "2026-08-26T01:20:00Z"
}
}{
"success": true,
"data": {
"deleted": true,
"id": "les_03"
}
}{
"success": true,
"data": {
"course_id": "course_123",
"course_title": "JavaScript Mastery",
"total_lessons": 20,
"completed_lessons": 13,
"completion_percentage": 65,
"last_position_sec": 14520,
"last_watched_lesson": {
"id": "les_13",
"title": "Async Generators"
}
}
}{
"success": true,
"data": {
"lesson_id": "les_13",
"status": "in_progress",
"started_at": "2026-08-26T01:22:00Z"
}
}{
"watch_time_sec": 840,
"last_position_sec": 840,
"completed": true
}{
"success": true,
"data": {
"lesson_id": "les_13",
"completed": true,
"course_progress": {
"completed_lessons": 14,
"total_lessons": 20,
"completion_percentage": 70
}
}
}{
"success": true,
"data": [
{
"id": "usr_94f812a4",
"username": "alex_dev",
"bio": "Software Architect & Educator",
"courses_count": 5,
"students_count": 12450
}
]
}{
"success": true,
"data": {
"id": "usr_94f812a4",
"username": "alex_dev",
"bio": "Software Architect & Educator",
"stats": {
"total_courses": 5,
"total_students": 12450,
"avg_rating": 4.9
},
"courses": [
{
"id": "course_123",
"title": "JavaScript Mastery",
"students": 4800
}
]
}
}{
"success": true,
"data": {
"creator_id": "usr_94f812a4",
"updated": true
}
}{
"success": true,
"data": {
"period": "monthly",
"metrics": {
"total_views": 184500,
"active_students": 8920,
"overall_completion_rate": "78.4%",
"avg_lesson_retention": "84.2%"
}
}
}{
"success": true,
"data": {
"query": "javascript",
"results": {
"courses": [
{
"id": "course_123",
"title": "JavaScript Mastery"
}
],
"creators": [
{
"id": "usr_94f812a4",
"username": "alex_dev"
}
],
"lessons": [
{
"id": "les_01",
"title": "Intro to JS V8"
}
],
"categories": [
{
"id": "cat_prog",
"name": "Programming"
}
]
}
}
}{
"success": true,
"data": [
{
"id": "cat_prog",
"name": "Programming",
"slug": "programming"
},
{
"id": "cat_des",
"name": "Design",
"slug": "design"
},
{
"id": "cat_biz",
"name": "Business",
"slug": "business"
},
{
"id": "cat_ai",
"name": "AI",
"slug": "ai"
}
]
}{
"file_name": "lesson_14_hd.mp4",
"file_type": "video/mp4",
"bucket": "course-videos"
}{
"success": true,
"data": {
"upload_url": "https://xyz.supabase.co/storage/v1/object/upload/sign/course-videos/usr_94f812a4/lesson_14.mp4?token=...",
"expires_in_sec": 900
}
}Tenimal delegates authentication to Supabase Auth. Every API request carries a JWT bearer token evaluated directly against PostgreSQL Row Level Security (RLS).
Exact permissions matrix mapping roles to feature operations.
| Feature | Student | Creator | Admin |
|---|---|---|---|
| View courses | ✅ | ✅ | ✅ |
| Create course | ❌ | ✅ | ✅ |
| Edit own course | ❌ | ✅ | ✅ |
| Delete own course | ❌ | ✅ | ✅ |
| Manage users | ❌ | ❌ | ✅ |
| Analytics | ❌ | Own | All |
Standardized error response structure returned by all Tenimal API endpoints upon failure.
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
}Target rate limiting policies for production API access (Planned Policy).
Applies to unauthenticated requests like course discovery, category listing, and search.
Applies to authenticated requests carrying a valid Supabase JWT access token.
Simulated code snippets for cURL, JavaScript, Python, and TypeScript SDK.
curl -X GET "https://api.tenimal.com/api/v1/users/me" \ -H "Authorization: Bearer YOUR_SUPABASE_JWT_TOKEN"
Historical record of API contract revisions and planned future updates.
The step-by-step technical progression towards deploying api.tenimal.com to production.