API Documentation

Complete reference for the FreelanceOS backend API

Introduction

FreelanceOS API is a RESTful backend built for African freelancers to manage clients, projects, invoices, and receive international payments via Raenest. Every endpoint follows a consistent response format and requires JWT authentication for protected routes.

Base URL

https://freelanceos-api.onrender.com/api/v1

For local development: http://localhost:5000/api/v1

Authentication

Most endpoints require a JWT token. Include it in the Authorization header:

Authorization: Bearer your_jwt_token_here

Tokens expire after 7 days. Obtain a token via POST /auth/login or POST /auth/register.

Response Format

All responses follow this structure:

{
                                "success": true,
                                "data": { ... }
                                }

Error responses:

{
                                "success": false,
                                "error": "Human-readable error message"
                                }

Authentication Endpoints

POST/auth/register

Create a new user account

Request:

{
                                "email": "user@example.com",
                                "password": "SecurePass123",
                                "firstName": "John",
                                "lastName": "Doe"
                                }

Response:

{
                                "success": true,
                                "data": {
                                    "token": "eyJhbGciOiJIUzI1NiIs...",
                                    "user": { ... }
                                }
                                }

POST/auth/login

Authenticate and receive JWT token

Request:

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

Response:

{
                                "success": true,
                                "data": {
                                    "token": "eyJhbGciOiJIUzI1NiIs...",
                                    "user": { ... }
                                }
                                }

GET/auth/me🔒 Auth required

Get current user profile

Response:

{
                                "success": true,
                                "data": {
                                    "id": "user_123",
                                    "email": "user@example.com",
                                    "firstName": "John",
                                    "lastName": "Doe",
                                    "currency": "USD",
                                    "timezone": "Africa/Lagos"
                                }
                                }

Clients

GET/clients🔒 Auth required

List all clients for authenticated user

Response:

{
                                "success": true,
                                "data": [...],
                                "total": 5,
                                "page": 1,
                                "pageSize": 10
                                }

POST/clients🔒 Auth required

Create a new client

Request:

{
                                "name": "TechStart Nigeria",
                                "email": "hello@techstart.ng",
                                "company": "TechStart Nigeria Ltd",
                                "phone": "+234 802 345 6789",
                                "country": "NG"
                                }

PUT/clients/:id🔒 Auth required

Update an existing client

DELETE/clients/:id🔒 Auth required

Delete a client (only if no active projects)

Projects

GET/projects🔒 Auth required??status=active&clientId=client_123

List all projects with optional filters

POST/projects🔒 Auth required

Create a new project

Request:

{
                                "clientId": "client_123",
                                "name": "E-commerce Redesign",
                                "description": "Complete website overhaul",
                                "budget": 4500,
                                "currency": "USD",
                                "status": "planning",
                                "deadline": "2026-04-15T00:00:00Z"
                                }

Invoices

GET/invoices🔒 Auth required

List invoices with status filtering

POST/invoices🔒 Auth required

Create a new invoice (auto-generates invoice number)

Request:

{
                                "clientId": "client_123",
                                "amount": 2250,
                                "currency": "USD",
                                "dueDate": "2026-04-15T00:00:00Z",
                                "items": [
                                    { "description": "UI Design", "quantity": 1, "rate": 1500 },
                                    { "description": "Development", "quantity": 1, "rate": 750 }
                                ],
                                "notes": "Payment due within 15 days"
                                }

POST/invoices/:id/send🔒 Auth required

Mark invoice as sent (changes status from draft to sent)

POST/invoices/:id/mark-paid🔒 Auth required

Mark invoice as paid (updates client total billed)

POST/invoices/:id/payment-link🔒 Auth required

Generate Raenest payment link (placeholder)

Response:

{
                                "success": true,
                                "data": {
                                    "link": "https://pay.raenest.com/fos-inv_123-abc123"
                                }
                                }

Dashboard

GET/dashboard/stats🔒 Auth required

Get key business metrics

Response:

{
                                "success": true,
                                "data": {
                                    "totalEarnings": 45250.75,
                                    "monthlyEarnings": 8750.5,
                                    "earningsGrowth": 23.5,
                                    "activeProjects": 4,
                                    "pendingInvoices": 3,
                                    "pendingInvoicesAmount": 12500,
                                    "overdueInvoices": 1,
                                    "overdueInvoicesAmount": 6500,
                                    "upcomingDeadlines": [...]
                                }
                                }

GET/dashboard/earnings🔒 Auth required??period=monthly

Get earnings over time (monthly/weekly)

GET/dashboard/activity🔒 Auth required??limit=20

Get recent activity feed

Error Codes

400Bad Request — Validation error, missing required field

401Unauthorized — Missing or invalid JWT token

403Forbidden — Authenticated but no permission (trying to access another user's data)

404Not Found — Resource doesn't exist

429Too Many Requests — Rate limit exceeded

500Internal Server Error — Something broke on our end

Rate Limits

All endpoints are rate-limited to 100 requests per 15 minutes per IP address. The response headers include:

X-RateLimit-Limit — Maximum requests allowed
X-RateLimit-Remaining — Requests remaining in window
X-RateLimit-Reset — Time when window resets

Environment Variables

Variable	Required	Default	Description
DATABASE_URL	✅ Yes	-	PostgreSQL connection string
JWT_SECRET	✅ Yes	-	Secret for signing JWTs (min 32 chars)
PORT	❌ No	5000	Server port
FRONTEND_URL	❌ No	http://localhost:3000	CORS allowed origin

Generate JWT Secret

Run one of these commands to generate a secure JWT secret:

# Linux/macOS/Git Bash node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"                # Using OpenSSL openssl rand -hex 48 # Windows PowerShell [Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(48))

Built for the DevCareer × Raenest Hackathon 2026. Need help? Open an issue onGitHub.