API Reference Overview

The Ever Works provides a comprehensive REST API built with Next.js API routes. This section documents all available endpoints, authentication methods, and usage examples.

Base URL

Development: http://localhost:3000/api
Production: https://yourdomain.com/api

Authentication

The API supports multiple authentication methods:

1. Session-based Authentication

Used for web application requests:

// Automatic for browser requests with valid session
fetch('/api/items', {
  credentials: 'include'
})

2. API Key Authentication

For server-to-server requests:

fetch('/api/items', {
  headers: {
    'Authorization': 'Bearer your-api-key'
  }
})

3. JWT Token Authentication

For mobile or SPA applications:

fetch('/api/items', {
  headers: {
    'Authorization': 'Bearer your-jwt-token'
  }
})

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0.0"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0.0"
  }
}

Paginated Response

{
  "success": true,
  "data": [
    // Array of items
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0.0"
  }
}

HTTP Status Codes

Code	Description
200	OK - Request successful
201	Created - Resource created successfully
400	Bad Request - Invalid request data
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
409	Conflict - Resource already exists
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Rate Limiting

API endpoints are rate-limited to prevent abuse:

Endpoint Type	Limit	Window
Public endpoints	100 requests	15 minutes
Authenticated endpoints	1000 requests	15 minutes
Admin endpoints	5000 requests	15 minutes
Webhook endpoints	10000 requests	15 minutes

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642234567

API Endpoints Overview

Public Endpoints

Items

• GET /api/items - List items with filtering
• GET /api/items/[id] - Get item details
• GET /api/items/[slug] - Get item by slug

Categories

• GET /api/categories - List all categories
• GET /api/categories/[slug] - Get category details

Tags

• GET /api/tags - List all tags
• GET /api/tags/[slug] - Get tag details

Search

• GET /api/search - Search items, categories, and tags

Authentication Endpoints

Auth

• POST /api/auth/signin - Sign in user
• POST /api/auth/signout - Sign out user
• GET /api/auth/session - Get current session
• POST /api/auth/signup - Register new user

User Management

• GET /api/user/profile - Get user profile
• PUT /api/user/profile - Update user profile
• POST /api/user/change-password - Change password

Protected Endpoints

Favorites

• GET /api/favorites - Get user favorites
• POST /api/favorites - Add item to favorites
• DELETE /api/favorites/[slug] - Remove from favorites

Submissions

• POST /api/submit - Submit new item
• GET /api/submissions - Get user submissions
• PUT /api/submissions/[id] - Update submission

Admin Endpoints

Admin Items

• GET /api/admin/items - List all items (admin view)
• POST /api/admin/items - Create new item
• PUT /api/admin/items/[id] - Update item
• DELETE /api/admin/items/[id] - Delete item
• POST /api/admin/items/[id]/approve - Approve item
• POST /api/admin/items/[id]/reject - Reject item

Admin Users

• GET /api/admin/users - List all users
• GET /api/admin/users/[id] - Get user details
• PUT /api/admin/users/[id] - Update user
• DELETE /api/admin/users/[id] - Delete user
• POST /api/admin/users/[id]/ban - Ban user

Admin Analytics

• GET /api/admin/stats - Get dashboard statistics
• GET /api/admin/analytics - Get detailed analytics
• GET /api/admin/export - Export data

Payment Endpoints

Stripe

• POST /api/stripe/checkout - Create checkout session
• POST /api/stripe/webhook - Handle Stripe webhooks
• GET /api/stripe/subscription - Get subscription details
• POST /api/stripe/cancel - Cancel subscription

LemonSqueezy

• POST /api/lemonsqueezy/checkout - Create checkout
• POST /api/lemonsqueezy/webhook - Handle webhooks
• GET /api/lemonsqueezy/subscription - Get subscription

Utility Endpoints

System

• GET /api/version - Get API version
• GET /api/health - Health check
• POST /api/verify-recaptcha - Verify reCAPTCHA

Content Sync

• POST /api/sync - Trigger content sync
• GET /api/sync/status - Get sync status

Query Parameters

Common Parameters

Pagination

?page=1&limit=20

Sorting

?sortBy=name&sortOrder=asc

Filtering

?category=productivity&tags=tools,apps

Search

?search=awesome%20tool

Items Endpoint Parameters

Parameter	Type	Description	Default
page	number	Page number	1
limit	number	Items per page	20
sortBy	string	Sort field	updated_at
sortOrder	string	Sort direction	desc
category	string	Filter by category	-
tags	string	Filter by tags (comma-separated)	-
search	string	Search query	-
featured	boolean	Show only featured items	-
status	string	Filter by status	approved

Example Requests

Get Featured Items

curl "https://yourdomain.com/api/items?featured=true&limit=10"

Search Items

curl "https://yourdomain.com/api/items?search=productivity&category=tools"

Get Items by Category

curl "https://yourdomain.com/api/items?category=development&sortBy=name"

Error Codes

Common Error Codes

Code	Description
VALIDATION_ERROR	Request validation failed
AUTHENTICATION_REQUIRED	User must be authenticated
INSUFFICIENT_PERMISSIONS	User lacks required permissions
RESOURCE_NOT_FOUND	Requested resource doesn't exist
RESOURCE_CONFLICT	Resource already exists
RATE_LIMIT_EXCEEDED	Too many requests
INTERNAL_ERROR	Server error occurred

Validation Errors

Validation errors include detailed field information:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "fields": {
        "email": "Invalid email format",
        "password": "Password must be at least 8 characters"
      }
    }
  }
}

SDK and Client Libraries

JavaScript/TypeScript Client

import { ApiClient } from '@ever-works/api-client';

const client = new ApiClient({
  baseUrl: 'https://yourdomain.com/api',
  apiKey: 'your-api-key'
});

// Get items
const items = await client.items.list({
  category: 'productivity',
  limit: 10
});

// Submit item
const submission = await client.items.submit({
  name: 'Awesome Tool',
  description: 'An amazing productivity tool',
  sourceUrl: 'https://example.com'
});

React Hooks

import { useItems, useSubmitItem } from '@ever-works/react-hooks';

function ItemsList() {
  const { data: items, loading, error } = useItems({
    category: 'productivity'
  });

  const { submitItem, loading: submitting } = useSubmitItem();

  // Component implementation
}

Webhooks

The API supports webhooks for real-time notifications:

Supported Events

• item.created - New item submitted
• item.approved - Item approved by admin
• item.rejected - Item rejected by admin
• user.registered - New user registered
• payment.completed - Payment processed

Webhook Format

{
  "event": "item.created",
  "data": {
    "id": "item-123",
    "name": "New Tool",
    "submittedBy": "user-456"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "sha256=..."
}

Next Steps

• Authentication API - Detailed auth endpoints
• Items API - Complete items API reference
• Users API - User management endpoints
• Admin API - Administrative endpoints
• Webhooks API - Webhook configuration