Skip to content

API.md

Latest commit

 

History

History
2934 lines (2464 loc) · 48.1 KB

API.md

File metadata and controls

2934 lines (2464 loc) · 48.1 KB
Raw

Trackeep API Documentation

Overview

Trackeep provides a RESTful API for managing bookmarks, tasks, files, and notes. All API endpoints (except authentication) require a valid JWT token. The application also integrates with AI services (Mistral and LongCat) for enhanced functionality.

Base URL: http://localhost:8080/api/v1

Authentication: Bearer Token (JWT)

AI Services Integration

Trackeep integrates with multiple AI providers to enhance functionality:

Mistral AI

  • Purpose: General AI tasks and text processing
  • Model: mistral-small-latest (configurable)
  • Environment Variables:
    • MISTRAL_API_KEY: Your Mistral API key
    • MISTRAL_MODEL: The model to use (default: mistral-small-latest)

LongCat AI

  • Purpose: Advanced AI features and specialized tasks
  • API Documentation: https://longcat.chat/platform/docs/
  • Environment Variables:
  • API Key Format: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Supported Formats: OpenAI API Format and Anthropic API Format
  • Endpoints:
    • OpenAI Format: https://api.longcat.chat/openai
    • Anthropic Format: https://api.longcat.chat/anthropic
  • Supported Models: LongCat-Flash-Chat and others
  • Authentication: Bearer token in Authorization header

Environment Configuration

To use AI features, configure the following environment variables in your .env file:

# Mistral AI Configuration
MISTRAL_API_KEY=your_mistral_api_key_here
MISTRAL_MODEL=mistral-small-latest

# LongCat AI Configuration
LONGCAT_API_KEY=ak_2886WQ2oE7rX3Ll3XD3pj1oM8iB4u
LONGCAT_BASE_URL=https://api.longcat.chat

Authentication

Register User

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123",
  "name": "John Doe"
}

Response:

{
  "message": "User created successfully",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Login

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Get Current User

GET /auth/me
Authorization: Bearer <token>

Response:

{
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2024-01-01T00:00:00Z"
}

Login with TOTP

POST /auth/login-totp
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123",
  "token": "123456"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Check Users Exist

GET /auth/check-users

Response:

{
  "hasUsers": true,
  "count": 5
}

Request Password Reset

POST /auth/password-reset
Content-Type: application/json

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

Response:

{
  "message": "Password reset email sent"
}

Confirm Password Reset

POST /auth/password-reset/confirm
Content-Type: application/json

{
  "token": "reset_token_here",
  "new_password": "newpassword123"
}

Response:

{
  "message": "Password reset successfully"
}

GitHub App Sign-In

GET /auth/github

GitHub App Sign-In Callback

GET /auth/github/callback?code=github_code_here

Update Profile

PUT /auth/profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Name",
  "email": "updated@example.com"
}

Change Password

PUT /auth/password
Authorization: Bearer <token>
Content-Type: application/json

{
  "current_password": "oldpassword",
  "new_password": "newpassword123"
}

Two-Factor Authentication (2FA)

Setup TOTP

POST /auth/2fa/setup
Authorization: Bearer <token>

Response:

{
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "secret": "JBSWY3DPEHPK3PXP",
  "backup_codes": ["123456", "789012", "345678", "901234", "567890"]
}

Verify TOTP

POST /auth/2fa/verify
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "123456"
}

Enable TOTP

POST /auth/2fa/enable
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "123456"
}

Disable TOTP

POST /auth/2fa/disable
Authorization: Bearer <token>
Content-Type: application/json

{
  "password": "userpassword"
}

Get TOTP Status

GET /auth/2fa/status
Authorization: Bearer <token>

Response:

{
  "enabled": true,
  "setup_completed": true
}

Verify Backup Code

POST /auth/2fa/backup-codes/verify
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "123456"
}

Regenerate Backup Codes

POST /auth/2fa/backup-codes/regenerate
Authorization: Bearer <token>
Content-Type: application/json

{
  "password": "userpassword"
}

Response:

{
  "backup_codes": ["123456", "789012", "345678", "901234", "567890"]
}

Encryption

Encrypt Note Content

POST /auth/encrypt/content
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Sensitive note content"
}

Response:

{
  "encrypted_content": "U2FsdGVkX1+vupppZksvRf5pq5g5XjFRIipRkwB0K1Y96Qsv2Lm+31cmzaAILwyt"
}

Decrypt Note Content

POST /auth/decrypt/content
Authorization: Bearer <token>
Content-Type: application/json

{
  "encrypted_content": "U2FsdGVkX1+vupppZksvRf5pq5g5XjFRIipRkwB0K1Y96Qsv2Lm+31cmzaAILwyt"
}

Response:

{
  "content": "Sensitive note content"
}

Get Encryption Status

GET /auth/encryption/status
Authorization: Bearer <token>

Response:

{
  "encryption_enabled": true,
  "key_initialized": true
}

AI Settings

Get AI Settings

GET /auth/ai/settings
Authorization: Bearer <token>

Response:

{
  "mistral_enabled": true,
  "mistral_api_key": "set",
  "mistral_model": "mistral-small-latest",
  "longcat_enabled": true,
  "longcat_api_key": "set",
  "longcat_base_url": "https://api.longcat.chat"
}

Update AI Settings

PUT /auth/ai/settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "mistral_enabled": true,
  "mistral_api_key": "new_mistral_key",
  "mistral_model": "mistral-small-latest",
  "longcat_enabled": true,
  "longcat_api_key": "new_longcat_key",
  "longcat_base_url": "https://api.longcat.chat"
}

Test AI Connection

POST /auth/ai/test-connection
Authorization: Bearer <token>
Content-Type: application/json

{
  "provider": "mistral"
}

Response:

{
  "success": true,
  "message": "Connection successful",
  "provider": "mistral"
}

Test AI Settings (No Auth)

GET /test-ai-settings

Logout

POST /auth/logout
Authorization: Bearer <token>

Bookmarks

Get All Bookmarks

GET /bookmarks?page=1&limit=20&search=example&tag=important
Authorization: Bearer <token>

Query Parameters:

  • page (int): Page number (default: 1)
  • limit (int): Items per page (default: 20)
  • search (string): Search in title and description
  • tag (string): Filter by tag

Response:

{
  "bookmarks": [
    {
      "id": 1,
      "title": "Example Bookmark",
      "url": "https://example.com",
      "description": "An example bookmark",
      "tags": ["important", "reference"],
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Create Bookmark

POST /bookmarks
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "New Bookmark",
  "url": "https://example.com",
  "description": "A new bookmark",
  "tags": ["new", "example"]
}

Get Bookmark

GET /bookmarks/{id}
Authorization: Bearer <token>

Update Bookmark

PUT /bookmarks/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Bookmark",
  "description": "Updated description",
  "tags": ["updated", "example"]
}

Delete Bookmark

DELETE /bookmarks/{id}
Authorization: Bearer <token>

Refresh Bookmark Metadata

POST /bookmarks/{id}/refresh-metadata
Authorization: Bearer <token>

Response:

{
  "id": 1,
  "title": "Updated Title",
  "description": "Updated description",
  "metadata_updated": true
}

Get Bookmark Metadata

POST /bookmarks/metadata
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://example.com"
}

Response:

{
  "title": "Example Domain",
  "description": "This domain is for use in illustrative examples",
  "image": "https://example.com/image.jpg",
  "favicon": "https://example.com/favicon.ico"
}

Get Bookmark Content

POST /bookmarks/content
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://example.com"
}

Response:

{
  "content": "Extracted content from the webpage...",
  "word_count": 250,
  "reading_time": "1 min"
}

GitHub Integration

Get GitHub Repositories

GET /github/repos
Authorization: Bearer <token>

Response:

{
  "repos": [
    {
      "id": 123456789,
      "name": "trackeep",
      "full_name": "username/trackeep",
      "description": "A comprehensive productivity tool",
      "language": "Go",
      "stars": 42,
      "forks": 8,
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Tasks

Get All Tasks

GET /tasks?page=1&limit=20&status=pending&priority=high
Authorization: Bearer <token>

Query Parameters:

  • page (int): Page number
  • limit (int): Items per page
  • status (string): Filter by status (pending, in_progress, completed)
  • priority (string): Filter by priority (low, medium, high)

Response:

{
  "tasks": [
    {
      "id": 1,
      "title": "Complete project",
      "description": "Finish the Trackeep project",
      "status": "in_progress",
      "priority": "high",
      "due_date": "2024-01-15T00:00:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Create Task

POST /tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "New Task",
  "description": "Task description",
  "status": "pending",
  "priority": "medium",
  "due_date": "2024-01-15T00:00:00Z"
}

Get Task

GET /tasks/{id}
Authorization: Bearer <token>

Update Task

PUT /tasks/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Task",
  "status": "completed",
  "priority": "high"
}

Delete Task

DELETE /tasks/{id}
Authorization: Bearer <token>

Files

Get All Files

GET /files?page=1&limit=20&type=image
Authorization: Bearer <token>

Query Parameters:

  • page (int): Page number
  • limit (int): Items per page
  • type (string): Filter by file type

Response:

{
  "files": [
    {
      "id": 1,
      "filename": "document.pdf",
      "original_name": "My Document.pdf",
      "file_size": 1024000,
      "file_type": "application/pdf",
      "description": "Important document",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Upload File

POST /files/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <binary data>
description: "File description"

Get File

GET /files/{id}
Authorization: Bearer <token>

Download File

GET /files/{id}/download
Authorization: Bearer <token>

Delete File

DELETE /files/{id}
Authorization: Bearer <token>

Upload Encrypted File

POST /files/upload/encrypted
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <binary data>
description: "Encrypted file description"
encryption_key: "optional_encryption_key"

Download Encrypted File

GET /files/{id}/download/encrypted
Authorization: Bearer <token>

Response: Encrypted file data

YouTube Integration

Search YouTube

POST /youtube/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "golang tutorial",
  "max_results": 10
}

Response:

{
  "videos": [
    {
      "id": "dQw4w9WgXcQ",
      "title": "Never Gonna Give You Up",
      "description": "Official music video",
      "channel": "RickAstleyVEVO",
      "published_at": "2009-10-25T06:57:33Z",
      "duration": "3:33",
      "view_count": 1400000000,
      "thumbnail": "https://img.youtube.com/vi/dQw4w9WgXcQ/default.jpg"
    }
  ]
}

Get YouTube Video Details

POST /youtube/video-details
Authorization: Bearer <token>
Content-Type: application/json

{
  "video_id": "dQw4w9WgXcQ"
}

Get YouTube Channel Videos

POST /youtube/channel-videos
Authorization: Bearer <token>
Content-Type: application/json

{
  "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "max_results": 10
}

Get YouTube Channel Videos from URL

POST /youtube/channel-from-url
Authorization: Bearer <token>
Content-Type: application/json

{
  "channel_url": "https://www.youtube.com/c/RickAstleyVEVO"
}

Get YouTube Trending Videos

GET /youtube/trending
Authorization: Bearer <token>

Get Predefined Channel Videos

GET /youtube/predefined-channels
Authorization: Bearer <token>

Get Fireship Videos

GET /youtube/fireship
Authorization: Bearer <token>

Get NetworkChuck Videos

GET /youtube/network-chuck
Authorization: Bearer <token>

Get Channel Videos

POST /youtube/channel
Authorization: Bearer <token>
Content-Type: application/json

{
  "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw"
}

Video Bookmarks

Save Video Bookmark

POST /video-bookmarks
Authorization: Bearer <token>
Content-Type: application/json

{
  "video_id": "dQw4w9WgXcQ",
  "title": "Never Gonna Give You Up",
  "description": "Classic Rick Astley video",
  "channel": "RickAstleyVEVO",
  "thumbnail": "https://img.youtube.com/vi/dQw4w9WgXcQ/default.jpg",
  "duration": "3:33",
  "tags": ["music", "classic", "80s"]
}

Get User Bookmarks

GET /video-bookmarks?page=1&limit=20&search=rick&channel=RickAstleyVEVO
Authorization: Bearer <token>

Query Parameters:

  • page (int): Page number
  • limit (int): Items per page
  • search (string): Search in title and description
  • channel (string): Filter by channel

Search Bookmarks

GET /video-bookmarks/search?q=rick&channel=RickAstleyVEVO
Authorization: Bearer <token>

Get Bookmark Stats

GET /video-bookmarks/stats
Authorization: Bearer <token>

Response:

{
  "total_bookmarks": 25,
  "total_channels": 8,
  "total_watch_time": "2h 15m",
  "recent_bookmarks": 5,
  "top_channels": [
    {"channel": "RickAstleyVEVO", "count": 5},
    {"channel": "Fireship", "count": 3}
  ]
}

Get Bookmark by ID

GET /video-bookmarks/{id}
Authorization: Bearer <token>

Update Bookmark

PUT /video-bookmarks/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Title",
  "description": "Updated description",
  "tags": ["updated", "tags"]
}

Delete Bookmark

DELETE /video-bookmarks/{id}
Authorization: Bearer <token>

Toggle Watched Status

POST /video-bookmarks/{id}/toggle-watched
Authorization: Bearer <token>

Toggle Favorite Status

POST /video-bookmarks/{id}/toggle-favorite
Authorization: Bearer <token>

Notes

Get All Notes

GET /notes?page=1&limit=20&search=example&tag=important
Authorization: Bearer <token>

Response:

{
  "notes": [
    {
      "id": 1,
      "title": "Meeting Notes",
      "content": "Important meeting notes...",
      "tags": ["meeting", "important"],
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Create Note

POST /notes
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "New Note",
  "content": "Note content",
  "tags": ["new", "example"]
}

Get Note

GET /notes/{id}
Authorization: Bearer <token>

Update Note

PUT /notes/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Note",
  "content": "Updated content",
  "tags": ["updated", "example"]
}

Delete Note

DELETE /notes/{id}
Authorization: Bearer <token>

Create Encrypted Note

POST /notes/encrypted
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Encrypted Note",
  "content": "Sensitive content",
  "tags": ["encrypted", "secret"]
}

Get Encrypted Note

GET /notes/{id}/encrypted
Authorization: Bearer <token>

Search

Web Search

POST /search/web
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "golang best practices",
  "limit": 10
}

News Search

POST /search/news
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "technology news",
  "limit": 10
}

Get Search Suggestions

GET /search/suggestions?q=golang
Authorization: Bearer <token>

Enhanced Search

POST /search/enhanced
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "project management",
  "filters": {
    "type": ["notes", "bookmarks"],
    "tags": ["work"],
    "date_range": "last_30_days"
  }
}

Save Search

POST /search/save
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Work Projects",
  "query": "project management",
  "filters": {"tags": ["work"]}
}

Get Search Analytics

GET /search/analytics
Authorization: Bearer <token>

Saved Searches

Create Saved Search

POST /search/saved
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Daily Review",
  "query": "status:pending priority:high",
  "tags": ["daily", "review"]
}

Get User Saved Searches

GET /search/saved
Authorization: Bearer <token>

Get Saved Search

GET /search/saved/{id}
Authorization: Bearer <token>

Update Saved Search

PUT /search/saved/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Search",
  "query": "updated query"
}

Delete Saved Search

DELETE /search/saved/{id}
Authorization: Bearer <token>

Run Saved Search

POST /search/saved/{id}/run
Authorization: Bearer <token>

Get Saved Search Tags

GET /search/saved/tags
Authorization: Bearer <token>

Semantic Search

Semantic Search

POST /search/semantic
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "machine learning algorithms",
  "content_types": ["notes", "bookmarks"],
  "limit": 10
}

Generate Embedding

POST /search/embeddings/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Text to generate embedding for"
}

Reindex Content

POST /search/reindex
Authorization: Bearer <token>
Content-Type: application/json

{
  "content_types": ["notes", "bookmarks"]
}

Get Note Statistics

GET /notes/stats
Authorization: Bearer <token>

Response:

{
  "total_notes": 42,
  "total_tags": 15,
  "recent_notes": 5,
  "popular_tags": [
    {"tag": "important", "count": 10},
    {"tag": "work", "count": 8}
  ]
}

Time Tracking

Get Time Entries

GET /time-entries?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31
Authorization: Bearer <token>

Query Parameters:

  • page (int): Page number
  • limit (int): Items per page
  • start_date (string): Filter by start date
  • end_date (string): Filter by end date

Response:

{
  "time_entries": [
    {
      "id": 1,
      "description": "Working on Trackeep API",
      "start_time": "2024-01-01T09:00:00Z",
      "end_time": "2024-01-01T11:00:00Z",
      "duration": "2h 0m",
      "project": "Trackeep",
      "tags": ["development", "api"]
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Create Time Entry

POST /time-entries
Authorization: Bearer <token>
Content-Type: application/json

{
  "description": "Meeting with team",
  "start_time": "2024-01-01T14:00:00Z",
  "end_time": "2024-01-01T15:00:00Z",
  "project": "Trackeep",
  "tags": ["meeting", "team"]
}

Get Time Stats

GET /time-entries/stats?period=week&project=Trackeep
Authorization: Bearer <token>

Response:

{
  "total_time": "40h 30m",
  "total_entries": 25,
  "average_duration": "1h 37m",
  "project_breakdown": [
    {"project": "Trackeep", "time": "30h 15m"},
    {"project": "Other", "time": "10h 15m"}
  ]
}

Get Time Entry

GET /time-entries/{id}
Authorization: Bearer <token>

Update Time Entry

PUT /time-entries/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "description": "Updated description",
  "end_time": "2024-01-01T16:00:00Z"
}

Stop Time Entry

POST /time-entries/{id}/stop
Authorization: Bearer <token>

Delete Time Entry

DELETE /time-entries/{id}
Authorization: Bearer <token>

Calendar

Get Events

GET /calendar?start_date=2024-01-01&end_date=2024-01-31
Authorization: Bearer <token>

Response:

{
  "events": [
    {
      "id": 1,
      "title": "Team Meeting",
      "description": "Weekly team sync",
      "start_time": "2024-01-01T10:00:00Z",
      "end_time": "2024-01-01T11:00:00Z",
      "location": "Conference Room",
      "is_completed": false,
      "reminder": "15m"
    }
  ]
}

Get Event

GET /calendar/{id}
Authorization: Bearer <token>

Create Event

POST /calendar
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Project Review",
  "description": "Review project progress",
  "start_time": "2024-01-15T14:00:00Z",
  "end_time": "2024-01-15T15:30:00Z",
  "location": "Meeting Room A",
  "reminder": "30m"
}

Update Event

PUT /calendar/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Event",
  "description": "Updated description"
}

Delete Event

DELETE /calendar/{id}
Authorization: Bearer <token>

Get Upcoming Events

GET /calendar/upcoming?limit=10
Authorization: Bearer <token>

Get Today's Events

GET /calendar/today
Authorization: Bearer <token>

Get Deadlines

GET /calendar/deadlines?days=7
Authorization: Bearer <token>

Toggle Event Completion

PUT /calendar/{id}/toggle-complete
Authorization: Bearer <token>

Export/Import

Export Data

GET /export
Authorization: Bearer <token>

Response: JSON file containing all user data

Import Data

POST /import
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <json data file>

AI Features

Get AI Providers

GET /ai/providers
Authorization: Bearer <token>

Response:

{
  "providers": [
    {
      "name": "mistral",
      "display_name": "Mistral AI",
      "enabled": true,
      "models": ["mistral-small-latest", "mistral-medium-latest"]
    },
    {
      "name": "longcat",
      "display_name": "LongCat AI",
      "enabled": true,
      "models": ["longcat-flash-chat"]
    }
  ]
}

Summarize Content

POST /ai/summarize
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Long text to summarize...",
  "provider": "mistral",
  "max_length": 150
}

Response:

{
  "summary": "Concise summary of the content...",
  "provider": "mistral",
  "word_count": 45
}

Get AI Summaries

GET /ai/summaries?page=1&limit=20
Authorization: Bearer <token>

Get Task Suggestions

POST /ai/tasks/suggest
Authorization: Bearer <token>
Content-Type: application/json

{
  "context": "Working on web development project",
  "current_tasks": ["Setup database", "Create API endpoints"],
  "priority": "high"
}

Response:

{
  "suggestions": [
    {
      "id": 1,
      "title": "Add input validation",
      "description": "Implement validation for API endpoints",
      "priority": "high",
      "estimated_time": "2h"
    }
  ]
}

Get Task Suggestions List

GET /ai/tasks/suggestions
Authorization: Bearer <token>

Accept Task Suggestion

POST /ai/tasks/suggestions/{id}/accept
Authorization: Bearer <token>

Dismiss Task Suggestion

POST /ai/tasks/suggestions/{id}/dismiss
Authorization: Bearer <token>

Generate Tag Suggestions

POST /ai/tags/suggest
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Article about machine learning algorithms",
  "existing_tags": ["ai", "technology"]
}

Response:

{
  "suggestions": ["machine-learning", "algorithms", "data-science", "ml"]
}

Generate Content

POST /ai/content/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "prompt": "Write a blog post about productivity tips",
  "type": "blog_post",
  "length": "medium",
  "tone": "professional"
}

Response:

{
  "content": "Generated content...",
  "word_count": 500,
  "provider": "mistral"
}

Chat

Send Message

POST /chat/send
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "Hello, how can you help me today?",
  "session_id": "optional_session_id",
  "provider": "mistral"
}

Response:

{
  "id": "msg_123",
  "message": "I'm here to help! What would you like to know?",
  "session_id": "session_456",
  "timestamp": "2024-01-01T10:00:00Z"
}

Get Chat Sessions

GET /chat/sessions?page=1&limit=20
Authorization: Bearer <token>

Get Session Messages

GET /chat/sessions/{id}/messages?page=1&limit=50
Authorization: Bearer <token>

Delete Session

DELETE /chat/sessions/{id}
Authorization: Bearer <token>

Messaging (Discord-like Communication)

Get Conversations

GET /messages/conversations?page=1&limit=20
Authorization: Bearer <token>

Create Conversation

POST /messages/conversations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Project Discussion",
  "type": "group",
  "member_ids": [2, 3, 4]
}

Get Conversation

GET /messages/conversations/{id}
Authorization: Bearer <token>

Update Conversation

PATCH /messages/conversations/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Conversation Name"
}

Add Conversation Member

POST /messages/conversations/{id}/members
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": 5
}

Remove Conversation Member

DELETE /messages/conversations/{id}/members/{userId}
Authorization: Bearer <token>

Get Conversation Messages

GET /messages/conversations/{id}/messages?page=1&limit=50
Authorization: Bearer <token>

Create Conversation Message

POST /messages/conversations/{id}/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Hello team!",
  "type": "text"
}

Update Message

PATCH /messages/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Updated message content"
}

Delete Message

DELETE /messages/{id}
Authorization: Bearer <token>

Add Message Reaction

POST /messages/{id}/reactions
Authorization: Bearer <token>
Content-Type: application/json

{
  "emoji": "👍"
}

Remove Message Reaction

DELETE /messages/{id}/reactions/{emoji}
Authorization: Bearer <token>

Search Messages

POST /messages/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "project deadline",
  "conversation_id": "optional_conversation_id"
}

Get Message Suggestions

GET /messages/{id}/suggestions
Authorization: Bearer <token>

Accept Message Suggestion

POST /messages/{id}/suggestions/{suggestionId}/accept
Authorization: Bearer <token>

Dismiss Message Suggestion

POST /messages/{id}/suggestions/{suggestionId}/dismiss
Authorization: Bearer <token>

Reveal Sensitive Message

POST /messages/{id}/reveal-sensitive
Authorization: Bearer <token>

Messages WebSocket

GET /messages/ws
Authorization: Bearer <token>

Password Vault

Get Password Vault Items

GET /messages/password-vault/items?page=1&limit=20
Authorization: Bearer <token>

Create Password Vault Item

POST /messages/password-vault/items
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "GitHub Account",
  "username": "myusername",
  "password": "encrypted_password",
  "url": "https://github.com",
  "notes": "Main GitHub account"
}

Share Password Vault Item

POST /messages/password-vault/items/{id}/share
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": 2,
  "expires_at": "2024-12-31T23:59:59Z"
}

Reveal Password Vault Item

POST /messages/password-vault/items/{id}/reveal
Authorization: Bearer <token>

Unshare Password Vault Item

POST /messages/password-vault/items/{id}/unshare
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": 2
}

Dashboard

Get Dashboard Stats

GET /dashboard/stats
Authorization: Bearer <token>

Response:

{
  "total_bookmarks": 150,
  "total_tasks": 25,
  "completed_tasks": 18,
  "total_notes": 42,
  "recent_activity": [
    {
      "type": "bookmark_created",
      "title": "New bookmark added",
      "timestamp": "2024-01-01T10:00:00Z"
    }
  ]
}

Learning Paths

Get Learning Path Categories

GET /learning-paths/categories

Response:

{
  "categories": [
    {
      "id": 1,
      "name": "Web Development",
      "description": "Learn modern web development",
      "path_count": 15
    }
  ]
}

Get Learning Paths

GET /learning-paths?page=1&limit=20&category=web-development&difficulty=intermediate
Authorization: Bearer <token>

Create Learning Path

POST /learning-paths
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Advanced React Development",
  "description": "Master React with advanced patterns",
  "category_id": 1,
  "difficulty": "advanced",
  "estimated_hours": 40,
  "tags": ["react", "javascript", "frontend"]
}

Get Learning Path

GET /learning-paths/{id}
Authorization: Bearer <token>

Update Learning Path

PUT /learning-paths/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Learning Path",
  "description": "Updated description"
}

Delete Learning Path

DELETE /learning-paths/{id}
Authorization: Bearer <token>

Enroll in Learning Path

POST /learning-paths/{id}/enroll
Authorization: Bearer <token>

Get Learning Path Courses

GET /learning-paths/{id}/courses
Authorization: Bearer <token>

Courses

Get Courses

GET /courses?page=1&limit=20&category=programming&level=beginner
Authorization: Bearer <token>

Get Featured Courses

GET /courses/featured
Authorization: Bearer <token>

Get ZTM Courses

GET /courses/ztm
Authorization: Bearer <token>

Get Course Categories

GET /courses/categories
Authorization: Bearer <token>

Search Courses

POST /courses/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "react development",
  "category": "programming",
  "level": "intermediate"
}

Get Course

GET /courses/{id}
Authorization: Bearer <token>

Get Course by Slug

GET /courses/slug/{slug}
Authorization: Bearer <token>

Enrollments

Get User Enrollments

GET /enrollments?page=1&limit=20&status=active
Authorization: Bearer <token>

Update Progress

PUT /enrollments/{id}/progress
Authorization: Bearer <token>
Content-Type: application/json

{
  "progress_percentage": 75,
  "completed_lessons": [1, 2, 3],
  "notes": "Great progress on React hooks"
}

Rate Learning Path

POST /enrollments/{id}/rate
Authorization: Bearer <token>
Content-Type: application/json

{
  "rating": 5,
  "review": "Excellent learning path!"
}

Integrations

Get Integrations

GET /integrations?page=1&limit=20
Authorization: Bearer <token>

Create Integration

POST /integrations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "GitHub",
  "type": "github",
  "config": {
    "repository": "username/repo"
  }
}

Get Integration

GET /integrations/{id}
Authorization: Bearer <token>

Update Integration

PUT /integrations/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "config": {
    "repository": "username/new-repo"
  }
}

Delete Integration

DELETE /integrations/{id}
Authorization: Bearer <token>

Authorize Integration

POST /integrations/{id}/authorize
Authorization: Bearer <token>

Sync Integration

POST /integrations/{id}/sync
Authorization: Bearer <token>

Get Sync Logs

GET /integrations/{id}/sync-logs?page=1&limit=20
Authorization: Bearer <token>

OAuth Callback

GET /integrations/oauth/callback?provider=github&code=code_here&state=state_here

Analytics

Get Dashboard Analytics

GET /analytics/dashboard?period=30d
Authorization: Bearer <token>

Get Productivity Metrics

GET /analytics/productivity?start_date=2024-01-01&end_date=2024-01-31
Authorization: Bearer <token>

Get Learning Analytics

GET /analytics/learning?period=90d
Authorization: Bearer <token>

Get Content Analytics

GET /analytics/content?type=bookmarks&period=30d
Authorization: Bearer <token>

Get GitHub Analytics

GET /analytics/github?period=30d
Authorization: Bearer <token>

Get Goals

GET /analytics/goals?status=active
Authorization: Bearer <token>

Create Goal

POST /analytics/goals
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Complete React Course",
  "description": "Finish the advanced React development course",
  "target_date": "2024-03-01T00:00:00Z",
  "type": "learning"
}

Update Goal

PUT /analytics/goals/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "progress": 75,
  "status": "in_progress"
}

Delete Goal

DELETE /analytics/goals/{id}
Authorization: Bearer <token>

Generate Analytics Report

POST /analytics/reports
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "productivity",
  "period": "monthly",
  "format": "pdf"
}

Generate Daily Analytics

POST /analytics/generate-daily
Authorization: Bearer <token>

Health Check

GET /health

Response:

{
  "status": "ok",
  "message": "Trackeep API is running",
  "version": "1.0.0",
  "database": "connected",
  "timestamp": {
    "unix": 1704067200,
    "human": "2024-01-01T00:00:00Z"
  }
}

Readiness Check

GET /ready

Response:

{
  "status": "ready",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "ai_services": "ok"
  }
}

Liveness Check

GET /live

Response:

{
  "status": "alive",
  "timestamp": "2024-01-01T00:00:00Z"
}

Get API Config

GET /api/v1/config

Response:

{
  "version": "1.0.0",
  "features": {
    "ai_enabled": true,
    "encryption_enabled": true,
    "2fa_enabled": true
  },
  "limits": {
    "max_file_size": 104857600,
    "max_requests_per_minute": 100
  }
}

Get Demo Status

GET /api/demo/status

Response:

{
  "demo_mode": true,
  "features": ["bookmarks", "notes", "tasks"]
}

Get Version

GET /api/version

Response:

{
  "version": "1.0.0",
  "build": "2024.01.01.001",
  "commit": "abc123def456"
}

Update Management

Check for Updates

GET /api/updates/check

Response:

{
  "update_available": true,
  "current_version": "1.0.0",
  "latest_version": "1.1.0",
  "release_notes": "Bug fixes and new features..."
}

Install Update

POST /api/updates/install
Content-Type: application/json

{
  "version": "1.1.0"
}

Get Update Progress

GET /api/updates/progress

Response:

{
  "status": "downloading",
  "progress": 45,
  "message": "Downloading update..."
}

Update Progress WebSocket

GET /api/updates/ws

Social Features

Get User Profile

GET /social/users/{id}
Authorization: Bearer <token>

Update Profile

PUT /social/profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "bio": "Software developer passionate about learning",
  "location": "San Francisco",
  "website": "https://example.com"
}

Search Users

GET /social/users/search?q=john&limit=10
Authorization: Bearer <token>

Follow User

POST /social/users/{id}/follow
Authorization: Bearer <token>

Get Followers

GET /social/users/{id}/followers?page=1&limit=20
Authorization: Bearer <token>

Get Following

GET /social/users/{id}/following?page=1&limit=20
Authorization: Bearer <token>

Teams

Get Teams

GET /teams?page=1&limit=20
Authorization: Bearer <token>

Create Team

POST /teams
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Development Team",
  "description": "Main development team",
  "is_private": false
}

Get Team

GET /teams/{id}
Authorization: Bearer <token>

Update Team

PUT /teams/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Team Name",
  "description": "Updated description"
}

Delete Team

DELETE /teams/{id}
Authorization: Bearer <token>

Get Team Members

GET /teams/{id}/members?page=1&limit=20
Authorization: Bearer <token>

Remove Team Member

DELETE /teams/{id}/members/{memberId}
Authorization: Bearer <token>

Invite Team Member

POST /teams/{id}/invite
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "newmember@example.com",
  "role": "member"
}

Accept Team Invitation

POST /teams/invitations/{token}/accept
Authorization: Bearer <token>

Get Team Activity

GET /teams/{id}/activity?page=1&limit=20
Authorization: Bearer <token>

Get Team Stats

GET /teams/{id}/stats
Authorization: Bearer <token>

Marketplace

Get Marketplace Items

GET /marketplace/items?page=1&limit=20&category=templates&sort=popular
Authorization: Bearer <token>

Get Marketplace Item

GET /marketplace/items/{id}
Authorization: Bearer <token>

Get Marketplace Reviews

GET /marketplace/items/{id}/reviews?page=1&limit=20
Authorization: Bearer <token>

Get Marketplace Stats

GET /marketplace/stats
Authorization: Bearer <token>

Get My Marketplace Items

GET /marketplace/my-items?page=1&limit=20
Authorization: Bearer <token>

Create Marketplace Item

POST /marketplace/items
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Project Template",
  "description": "Complete project template for startups",
  "category": "templates",
  "price": 9.99,
  "files": ["template.zip"]
}

Update Marketplace Item

PUT /marketplace/items/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Template",
  "price": 14.99
}

Delete Marketplace Item

DELETE /marketplace/items/{id}
Authorization: Bearer <token>

Create Marketplace Review

POST /marketplace/items/{id}/reviews
Authorization: Bearer <token>
Content-Type: application/json

{
  "rating": 5,
  "review": "Excellent template!"
}

Get Content Shares

GET /marketplace/shares?page=1&limit=20
Authorization: Bearer <token>

Create Content Share

POST /marketplace/shares
Authorization: Bearer <token>
Content-Type: application/json

{
  "item_id": 123,
  "share_type": "public",
  "expires_at": "2024-12-31T23:59:59Z"
}

Delete Content Share

DELETE /marketplace/shares/{id}
Authorization: Bearer <token>

Get Shared Content (Public)

GET /shared/{token}

Community

Get Challenges

GET /community/challenges?page=1&limit=20&status=active
Authorization: Bearer <token>

Get Challenge

GET /community/challenges/{id}
Authorization: Bearer <token>

Create Challenge

POST /community/challenges
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "30-Day Coding Challenge",
  "description": "Code every day for 30 days",
  "rules": "Submit at least one commit per day",
  "rewards": "Certificate and badge"
}

Join Challenge

POST /community/challenges/{id}/join
Authorization: Bearer <token>

Update Challenge Progress

PUT /community/challenges/{id}/progress
Authorization: Bearer <token>
Content-Type: application/json

{
  "progress": 15,
  "notes": "Halfway there!"
}

Get My Challenges

GET /community/my-challenges?page=1&limit=20
Authorization: Bearer <token>

Get Mentorship Requests

GET /community/mentorship/requests?page=1&limit=20
Authorization: Bearer <token>

Create Mentorship Request

POST /community/mentorship/requests
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Need help with React",
  "description": "Looking for mentor to help with advanced React concepts",
  "goals": ["Master hooks", "Learn state management"]
}

Respond to Mentorship Request

PUT /community/mentorship/requests/{id}/respond
Authorization: Bearer <token>
Content-Type: application/json

{
  "response": "accepted",
  "message": "I'd be happy to help!"
}

Get My Mentorships

GET /community/mentorship/my-mentorships?page=1&limit=20
Authorization: Bearer <token>

Create Mentorship Session

POST /community/mentorship/{id}/sessions
Authorization: Bearer <token>
Content-Type: application/json

{
  "scheduled_at": "2024-01-15T14:00:00Z",
  "duration": 60,
  "notes": "Discuss React hooks"
}

Get Mentorship Sessions

GET /community/mentorship/{id}/sessions?page=1&limit=20
Authorization: Bearer <token>

Get Community Stats

GET /community/stats
Authorization: Bearer <token>

Admin Endpoints

Get All Learning Paths (Admin)

GET /admin/learning-paths?page=1&limit=50&status=pending
Authorization: Bearer <token>

Review Learning Path (Admin)

PUT /admin/learning-paths/{id}/review
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "approved",
  "feedback": "Great content structure!"
}

Delete Learning Path (Admin)

DELETE /admin/learning-paths/{id}
Authorization: Bearer <token>

Get Users (Admin)

GET /admin/users?page=1&limit=50&role=user
Authorization: Bearer <token>

Update User Role (Admin)

PUT /admin/users/{id}/role
Authorization: Bearer <token>
Content-Type: application/json

{
  "role": "admin"
}

Get Admin Stats

GET /admin/stats
Authorization: Bearer <token>

Get Audit Logs

GET /admin/audit-logs?page=1&limit=50&action=login&user_id=123
Authorization: Bearer <token>

Get Audit Log Stats

GET /admin/audit-logs/stats?period=30d
Authorization: Bearer <token>

Get Audit Log

GET /admin/audit-logs/{id}
Authorization: Bearer <token>

Export Audit Logs

GET /admin/audit-logs/export?format=csv&start_date=2024-01-01&end_date=2024-01-31
Authorization: Bearer <token>

Cleanup Audit Logs

DELETE /admin/audit-logs/cleanup?days=90
Authorization: Bearer <token>

Performance Monitoring

Get Database Stats

GET /performance/stats
Authorization: Bearer <token>

Response:

{
  "database_size": "2.5GB",
  "total_records": 150000,
  "active_connections": 25,
  "query_performance": {
    "avg_response_time": "45ms",
    "slow_queries": 3
  }
}

Monitor Performance

GET /performance/monitor?duration=60s
Authorization: Bearer <token>

Optimize Database

POST /performance/optimize
Authorization: Bearer <token>

Cleanup Old Audit Logs

POST /performance/cleanup-audit-logs
Authorization: Bearer <token>
Content-Type: application/json

{
  "days": 90
}

Browser Extension API

Generate API Key

POST /browser-extension/api-keys/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Chrome Extension",
  "permissions": ["bookmarks:read", "bookmarks:write"]
}

Response:

{
  "api_key": "ext_1234567890abcdef",
  "name": "Chrome Extension",
  "permissions": ["bookmarks:read", "bookmarks:write"],
  "expires_at": "2024-12-31T23:59:59Z"
}

Get API Keys

GET /browser-extension/api-keys
Authorization: Bearer <token>

Revoke API Key

DELETE /browser-extension/api-keys/{id}
Authorization: Bearer <token>

Register Browser Extension

POST /browser-extension/register
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Trackeep Extension",
  "version": "1.0.0",
  "browser": "chrome"
}

Get Browser Extensions

GET /browser-extension/extensions
Authorization: Bearer <token>

Revoke Browser Extension

DELETE /browser-extension/extensions/{id}
Authorization: Bearer <token>

Validate API Key (Public)

GET /browser-extension/validate?api_key=ext_1234567890abcdef

Response:

{
  "valid": true,
  "permissions": ["bookmarks:read", "bookmarks:write"],
  "expires_at": "2024-12-31T23:59:59Z"
}

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": "Invalid request data",
  "details": "Field 'title' is required"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing token"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Access denied"
}

404 Not Found

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

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "Something went wrong"
}

Rate Limiting

API requests are rate-limited to prevent abuse:

  • Default limit: 100 requests per minute
  • Burst limit: 200 requests per minute

Rate limit headers are included in responses:

  • X-RateLimit-Limit: Request limit per window
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Time when limit resets

Pagination

List endpoints support pagination with the following parameters:

  • page (int, default: 1): Page number
  • limit (int, default: 20, max: 100): Items per page

Pagination metadata is included in responses:

{
  "data": [...],
  "total": 150,
  "page": 1,
  "limit": 20,
  "pages": 8
}

Search and Filtering

Most list endpoints support search and filtering:

  • search (string): Search in relevant fields
  • tag (string): Filter by tags
  • status (string): Filter by status (for tasks)
  • priority (string): Filter by priority (for tasks)
  • type (string): Filter by file type (for files)

File Upload Limits

  • Maximum file size: 100MB
  • Allowed file types: Images, documents, archives
  • Storage location: Configurable (local/cloud)

Security Considerations

  • All sensitive endpoints require JWT authentication
  • Passwords are hashed using bcrypt
  • File uploads are scanned for security threats
  • CORS is configured for cross-origin requests
  • Rate limiting prevents abuse
  • Input validation prevents injection attacks