Skip to main content

🔌 API Reference

Complete reference for MongoDB Minute REST API endpoints.

Base URL​

  • Development: http://localhost:3001/api
  • Production: https://<your-domain>/api

Authentication​

Most admin endpoints require JWT authentication via magic link:

  1. Request magic link: POST /api/auth/request-link
  2. Verify token: GET /api/auth/verify
  3. Use session cookie for subsequent requests

Episode Endpoints​

List Episodes​

GET /api/episodes

Returns all episodes.

Query Parameters: None (currently returns all episodes)

Response:

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "episodeNumber": 1,
    "title": "Understanding Embedded Documents",
    "slug": "understanding-embedded-documents",
    "category": "Data Modeling",
    "difficulty": "Beginner",
    "status": "published",
    "hook": "Did you know most MongoDB performance issues...",
    "workflow": {
      "currentStage": "approved"
    },
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z"
  }
]

Get Single Episode​

GET /api/episodes/[id]

Get episode by MongoDB ObjectId.

Response: Single episode object or 404

Create Episode​

POST /api/episodes

Create new episode with workflow initialization.

Request Body:

{
  "episodeNumber": 1,
  "title": "Understanding Embedded Documents",
  "category": "Data Modeling",
  "difficulty": "Beginner",
  "status": "draft",
  "hook": "Did you know...",
  "problem": "When designing schemas...",
  "tip": "Use embedded documents when...",
  "quickWin": "This reduces query complexity...",
  "cta": "Subscribe for more tips!"
}

Response: Created episode with 201 status

Note: Workflow is automatically initialized on creation.

Update Episode​

PUT /api/episodes/[id]

Update existing episode.

Request Body: Partial or complete episode object

Response: Updated episode object

Delete Episode​

DELETE /api/episodes/[id]

Delete episode by ID.

Response: { "ok": true }

Workflow Endpoints​

Submit for Review​

POST /api/episodes/[id]/workflow/submit-review

Submit episode for technical review.

Authentication: Required (JWT)

Response:

{
  "success": true,
  "episode": {
    "workflow": {
      "currentStage": "tech-review",
      "submittedForReview": {
        "email": "user@mongodb.com",
        "name": "John Doe",
        "timestamp": "2025-01-15T10:00:00Z"
      }
    }
  }
}

Review Episode​

POST /api/episodes/[id]/workflow/review

Perform technical review (approve or request changes).

Authentication: Required (JWT)

Request Body:

{
  "decision": "approved",
  "notes": "Looks good, minor typo fixed"
}

Decision Values:

  • "approved": Approve and move to Approved stage
  • "changes-requested": Return to Draft with notes

Response:

{
  "success": true,
  "episode": {
    "workflow": {
      "currentStage": "approved",
      "reviewedBy": {
        "email": "reviewer@mongodb.com",
        "name": "Jane Smith",
        "timestamp": "2025-01-15T11:00:00Z",
        "notes": "Looks good, minor typo fixed",
        "decision": "approved"
      }
    }
  }
}

Final Approval​

POST /api/episodes/[id]/workflow/approve

Final approval for recording.

Authentication: Required (JWT)

Request Body:

{
  "notes": "Ready for recording"
}

Response:

{
  "success": true,
  "episode": {
    "workflow": {
      "currentStage": "approved",
      "approvedBy": {
        "email": "approver@mongodb.com",
        "name": "Admin User",
        "timestamp": "2025-01-15T12:00:00Z",
        "notes": "Ready for recording"
      }
    }
  }
}

QR Code Endpoint​

Generate QR Code​

GET /api/episodes/[id]/qrcode

Generate QR code for episode detail page.

Query Parameters:

  • size (number, optional): QR code size in pixels (default: 256)

Response: QR code as SVG image

Example:

GET /api/episodes/507f1f77bcf86cd799439011/qrcode?size=512

User Settings Endpoints​

Get User Settings​

GET /api/user/settings

Get current user settings.

Authentication: Required (JWT)

Response:

{
  "email": "user@mongodb.com",
  "settings": {
    "openaiApiKey": "sk-...",
    "socialHandles": {
      "youtube": "@username",
      "tiktok": "@username",
      "linkedin": "username",
      "instagram": "@username",
      "x": "@username"
    }
  }
}

Update User Settings​

PUT /api/user/settings

Update user settings.

Authentication: Required (JWT)

Request Body:

{
  "openaiApiKey": "sk-...",
  "socialHandles": {
    "youtube": "@newusername",
    "tiktok": "@newusername"
  }
}

Response: Updated user settings object

Authentication Endpoints​

POST /api/auth/request-link

Request magic link for passwordless login.

Request Body:

{
  "email": "user@mongodb.com"
}

Response:

{
  "success": true,
  "message": "Magic link sent to email"
}

Note: Only MongoDB.com email addresses are accepted.

GET /api/auth/verify

Verify magic link token and create session.

Query Parameters:

  • token (string, required): JWT token from magic link

Response: Redirects to admin dashboard on success

Logout​

POST /api/auth/logout

Logout current user.

Response: { "success": true }

Error Responses​

All endpoints may return error responses:

400 Bad Request:

{
  "error": "Validation error",
  "details": "Title is required"
}

401 Unauthorized:

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

404 Not Found:

{
  "error": "Not found",
  "message": "Episode not found"
}

500 Internal Server Error:

{
  "error": "Internal server error",
  "message": "Database connection failed"
}

Rate Limiting​

Currently, no rate limiting is implemented. Consider adding rate limiting for production deployments.

CORS​

CORS is configured for the application domain. For API access from external domains, configure CORS headers appropriately.

Data Models​

Episode Schema​

See Project Summary for complete schema documentation.

User Schema​

{
  _id: ObjectId,
  email: String, // MongoDB.com email (unique)
  settings: {
    openaiApiKey: String, // Encrypted
    socialHandles: {
      youtube: String,
      tiktok: String,
      linkedin: String,
      instagram: String,
      x: String
    }
  },
  createdAt: Date,
  updatedAt: Date
}

Integration Examples​

JavaScript/TypeScript​

// List episodes
const response = await fetch('/api/episodes');
const episodes = await response.json();

// Create episode
const newEpisode = await fetch('/api/episodes', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'New Episode',
    category: 'Data Modeling',
    difficulty: 'Beginner',
    // ... other fields
  })
});

// Submit for review
await fetch(`/api/episodes/${episodeId}/workflow/submit-review`, {
  method: 'POST',
  credentials: 'include' // Include session cookie
});

cURL Examples​

# List episodes
curl http://localhost:3001/api/episodes

# Create episode
curl -X POST http://localhost:3001/api/episodes \
  -H "Content-Type: application/json" \
  -d '{"title":"New Episode","category":"Data Modeling"}'

# Submit for review (requires auth)
curl -X POST http://localhost:3001/api/episodes/ID/workflow/submit-review \
  -H "Cookie: session=TOKEN"

Next Steps​