Skip to main content

🔌 API Reference

Complete API documentation and reference for Idling.app.

🌐 Base URL​

Development: http://localhost:3000/api
Production:  https://idling.app/api

🔐 Authentication​

Idling.app uses NextAuth.js for authentication with multiple providers.

Authentication Endpoints​

MethodEndpointDescription
GET/api/auth/signinSign in page
POST/api/auth/signinSign in with credentials
GET/api/auth/signoutSign out page
POST/api/auth/signoutSign out user
GET/api/auth/sessionGet current session

Example Request​

curl -X GET http://localhost:3000/api/auth/session \
  -H "Cookie: next-auth.session-token=..."

👥 User Management​

User Endpoints​

MethodEndpointDescription
GET/api/usersList all users
GET/api/users/[id]Get user by ID
POST/api/usersCreate new user
PUT/api/users/[id]Update user
DELETE/api/users/[id]Delete user

User Schema​

{
  "id": "string",
  "name": "string",
  "email": "string",
  "emailVerified": "datetime",
  "image": "string",
  "profile_public": "boolean",
  "bio": "string",
  "location": "string",
  "created_at": "datetime",
  "last_login": "datetime",
  "login_count": "number"
}

📝 Posts & Content​

Post Endpoints​

MethodEndpointDescription
GET/api/postsList posts
GET/api/posts/[id]Get post by ID
POST/api/postsCreate new post
PUT/api/posts/[id]Update post
DELETE/api/posts/[id]Delete post

Post Schema​

{
  "id": "string",
  "title": "string",
  "content": "string",
  "author_id": "string",
  "created_at": "datetime",
  "updated_at": "datetime",
  "published": "boolean",
  "tags": ["string"]
}

🔍 Search & Filtering​

Search Endpoints​

MethodEndpointDescription
GET/api/searchSearch content
GET/api/search/usersSearch users
GET/api/search/postsSearch posts

Query Parameters​

# Search with filters
GET /api/search?q=keyword&type=post&limit=10&offset=0

# Advanced filtering
GET /api/posts?author=user123&published=true&sort=created_at&order=desc

🏥 Health & Monitoring​

System Endpoints​

MethodEndpointDescription
GET/api/healthSystem health check
GET/api/versionAPI version info
GET/api/metricsSystem metrics

Health Check Response​

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0",
  "database": "connected",
  "uptime": "24h 30m 15s"
}

🔧 Admin Functions​

Admin Endpoints​

MethodEndpointDescription
GET/api/admin/usersAdmin user management
POST/api/admin/users/[id]/banBan user
POST/api/admin/users/[id]/unbanUnban user
GET/api/admin/statsSystem statistics

📊 Rate Limiting​

All API endpoints are rate-limited to prevent abuse:

  • Authenticated users: 1000 requests per hour
  • Unauthenticated users: 100 requests per hour
  • Admin endpoints: 500 requests per hour

Rate Limit Headers​

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

🚨 Error Handling​

Error Response Format​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  }
}

Common Error Codes​

CodeStatusDescription
UNAUTHORIZED401Authentication required
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
VALIDATION_ERROR422Invalid input data
RATE_LIMITED429Too many requests
SERVER_ERROR500Internal server error

📚 Interactive Documentation​

🔗 Related Resources​

This documentation is under development. Contribute to expand this documentation.