📋 MyZubster API Reference Guide

📋 MyZubster API Reference Guide

Complete API documentation – all endpoints, authentication, error handling, and usage examples
📌 What is the API Reference?

This is the complete technical documentation for all API endpoints in the MyZubster ecosystem. It covers:

✅ Authentication – JWT-based auth flow

✅ User management – Registration, login, profile

✅ Skills – Create, read, update, delete skills

✅ Orders – Create, track, and manage orders

✅ Payments – Monero payment initiation and status

✅ Escrow – Multi-signature escrow operations

✅ Webhooks – Incoming payment notifications

✅ Admin – Administrative endpoints

✅ Error codes – Complete error reference

🏗️ API Base URLs
Environment Base URL
Local Development http://localhost:4000/api
Staging https://staging.myzubster.com/api
Production https://api.myzubster.com/api
🔐 Authentication
JWT Token Flow

Register – Create a new user account

Login – Obtain a JWT token

Use Token – Include in Authorization: Bearer <token> header

Refresh – Token expires in 7 days, login again to refresh

Headers
http

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

📋 Endpoints Summary
Category Endpoints Count
Auth /auth/* 4
Users /users/* 3
Skills /skills/* 5
Orders /orders/* 5
Payments /payments/* 3
Escrow /escrow/* 4
Admin /admin/* 10
Webhooks /webhook/* 1
🔐 Auth Endpoints
POST /auth/register

Register a new user

Request:
json

{
"email": "[e-mail]",
"password": "secure_password",
"username": "username",
"name": "Full Name"
}

Response (201 Created):
json

{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"email": "[e-mail]",
"username": "username",
"name": "Full Name",
"role": "user",
"isActive": true,
"createdAt": "2026-07-20T10:00:00.000Z"
}
}

Error Responses:
Status Error
400 Email already registered
400 Email and password required
500 Error registering user
POST /auth/login

Login to obtain JWT token

Request:
json

{
"email": "[e-mail]",
"password": "secure_password"
}

Response (200 OK):
json

{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"email": "[e-mail]",
"username": "username",
"name": "Full Name",
"role": "user",
"isActive": true
}
}

Error Responses:
Status Error
401 Invalid credentials
400 Email and password required
500 Error logging in
GET /auth/me

Get current user profile (requires auth)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"user": {
"id": 1,
"email": "[e-mail]",
"username": "username",
"name": "Full Name",
"role": "user",
"isActive": true,
"rating": 0,
"moneroAddress": "4...",
"createdAt": "2026-07-20T10:00:00.000Z",
"updatedAt": "2026-07-20T10:00:00.000Z"
}
}

Error Responses:
Status Error
401 Authentication required
404 User not found
500 Error fetching profile
POST /auth/logout

Logout (client-side token invalidation)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"message": "Logged out successfully"
}

👤 User Endpoints
GET /users

List users (requires auth)

Headers:
http

Authorization: Bearer

Query Parameters:
Parameter Type Description
page integer Page number (default: 1)
limit integer Items per page (default: 20)
search string Search by username or email
role string Filter by role

Response (200 OK):
json

{
"users": [
{
"id": 1,
"email": "[e-mail]",
"username": "username",
"name": "Full Name",
"role": "user",
"rating": 4.5,
"isActive": true
}
],
"pagination": {
"total": 100,
"page": 1,
"limit": 20,
"pages": 5
}
}

GET /users/:id

Get user by ID

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"id": 1,
"email": "[e-mail]",
"username": "username",
"name": "Full Name",
"role": "user",
"rating": 4.5,
"isActive": true,
"location": {
"city": "New York",
"country": "USA"
},
"moneroAddress": "4...",
"createdAt": "2026-07-20T10:00:00.000Z"
}

Error Responses:
Status Error
404 User not found
500 Error fetching user
PUT /users/:id

Update user (requires auth)

Headers:
http

Authorization: Bearer

Request:
json

{
"name": "Updated Name",
"username": "new_username",
"location": {
"city": "Los Angeles",
"country": "USA"
}
}

Response (200 OK):
json

{
"id": 1,
"email": "[e-mail]",
"username": "new_username",
"name": "Updated Name",
"role": "user",
"isActive": true,
"updatedAt": "2026-07-20T12:00:00.000Z"
}

🛠️ Skill Endpoints
POST /skills

Create a new skill (requires auth, seller role)

Headers:
http

Authorization: Bearer

Request:
json

{
"name": "React Native Development",
"description": "Expert React Native developer with 5+ years experience",
"price": 150,
"category": "development",
"currency": "USD"
}

Response (201 Created):
json

{
"id": 1,
"name": "React Native Development",
"description": "Expert React Native developer with 5+ years experience",
"price": 150,
"currency": "USD",
"category": "development",
"sellerId": 1,
"isActive": true,
"createdAt": "2026-07-20T10:00:00.000Z"
}

Error Responses:
Status Error
400 Name, description, price and category required
403 Only sellers can create skills
500 Error creating skill
GET /skills

List all skills (public)

Query Parameters:
Parameter Type Description
category string Filter by category
search string Search in name/description
minPrice number Minimum price filter
maxPrice number Maximum price filter
page integer Page number (default: 1)
limit integer Items per page (default: 20)
sort string Sort by: createdAt, price, rating
order string ASC or DESC (default: DESC)

Response (200 OK):
json

{
"skills": [
{
"id": 1,
"name": "React Native Development",
"description": "Expert React Native developer...",
"price": 150,
"currency": "USD",
"category": "development",
"seller": {
"id": 1,
"username": "username",
"name": "Full Name",
"rating": 4.8
},
"views": 150,
"rating": 4.9,
"createdAt": "2026-07-20T10:00:00.000Z"
}
],
"pagination": {
"total": 50,
"page": 1,
"limit": 20,
"pages": 3
}
}

GET /skills/:id

Get skill by ID (public)

Response (200 OK):
json

{
"id": 1,
"name": "React Native Development",
"description": "Expert React Native developer with 5+ years experience",
"price": 150,
"currency": "USD",
"category": "development",
"seller": {
"id": 1,
"username": "username",
"name": "Full Name",
"rating": 4.8,
"moneroAddress": "4..."
},
"views": 150,
"rating": 4.9,
"isActive": true,
"createdAt": "2026-07-20T10:00:00.000Z",
"updatedAt": "2026-07-20T10:00:00.000Z"
}

PUT /skills/:id

Update skill (requires auth, seller or admin)

Headers:
http

Authorization: Bearer

Request:
json

{
"name": "Updated Skill Name",
"description": "Updated description",
"price": 200,
"category": "updated_category"
}

Response (200 OK):
json

{
"id": 1,
"name": "Updated Skill Name",
"description": "Updated description",
"price": 200,
"currency": "USD",
"category": "updated_category",
"updatedAt": "2026-07-20T12:00:00.000Z"
}

DELETE /skills/:id

Delete skill (requires auth, seller or admin)

Headers:
http

Authorization: Bearer

Response (204 No Content):
No response body

Error Responses:
Status Error
404 Skill not found
403 Not authorized to delete this skill
500 Error deleting skill
📦 Order Endpoints
POST /orders

Create a new order (requires auth, buyer)

Headers:
http

Authorization: Bearer

Request:
json

{
"skillId": 1
}

Response (201 Created):
json

{
"id": 1,
"buyerId": 1,
"sellerId": 2,
"skillId": 1,
"amount": 150,
"currency": "USD",
"moneroAddress": "8A1B2C3D4E5F6G7H8I9J0K",
"moneroAmount": 0.0125,
"status": "pending",
"network": "testnet",
"createdAt": "2026-07-20T10:00:00.000Z"
}

Error Responses:
Status Error
404 Skill not found
400 Cannot buy your own skill
500 Error creating order
GET /orders/my

Get user's orders (requires auth)

Headers:
http

Authorization: Bearer

Query Parameters:
Parameter Type Description
status string Filter by status
page integer Page number (default: 1)
limit integer Items per page (default: 20)

Response (200 OK):
json

{
"orders": [
{
"id": 1,
"buyerId": 1,
"sellerId": 2,
"skillId": 1,
"amount": 150,
"currency": "USD",
"status": "pending",
"moneroAddress": "8A1B2C3D4E5F6G7H8I9J0K",
"createdAt": "2026-07-20T10:00:00.000Z",
"skill": {
"id": 1,
"name": "React Native Development"
},
"seller": {
"id": 2,
"username": "seller",
"name": "Seller Name"
}
}
],
"pagination": {
"total": 10,
"page": 1,
"limit": 20,
"pages": 1
}
}

GET /orders/:id

Get order by ID (requires auth, buyer or seller)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"id": 1,
"buyerId": 1,
"sellerId": 2,
"skillId": 1,
"amount": 150,
"currency": "USD",
"status": "paid",
"moneroAddress": "8A1B2C3D4E5F6G7H8I9J0K",
"moneroTxHash": "tx_123456789",
"paidAt": "2026-07-20T11:00:00.000Z",
"createdAt": "2026-07-20T10:00:00.000Z",
"skill": {
"id": 1,
"name": "React Native Development",
"description": "...",
"price": 150
},
"buyer": {
"id": 1,
"username": "buyer",
"name": "Buyer Name"
},
"seller": {
"id": 2,
"username": "seller",
"name": "Seller Name"
},
"escrow": {
"id": 1,
"status": "funded",
"amount": 150,
"moneroAmount": 0.0125
}
}

PATCH /orders/:id/status

Update order status (requires auth, seller or admin)

Headers:
http

Authorization: Bearer

Request:
json

{
"status": "in_progress"
}

Allowed status transitions:
From To
pending paid (auto via webhook)
paid in_progress
in_progress completed
in_progress cancelled
pending cancelled
paid disputed

Response (200 OK):
json

{
"id": 1,
"status": "in_progress",
"updatedAt": "2026-07-20T12:00:00.000Z"
}

GET /orders/:id/payment-status

Get payment status for order (requires auth)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"id": 1,
"status": "paid",
"confirmations": 10,
"amountReceived": 0.0125,
"txHash": "tx_123456789",
"paidAt": "2026-07-20T11:00:00.000Z"
}

💳 Payment Endpoints
POST /payments/initiate

Initiate a Monero payment (requires auth)

Headers:
http

Authorization: Bearer

Request:
json

{
"orderId": 1,
"amount": 150,
"currency": "USD"
}

Response (201 Created):
json

{
"success": true,
"paymentId": "pay_123456789",
"moneroAddress": "8A1B2C3D4E5F6G7H8I9J0K",
"moneroAmount": 0.0125,
"addressIndex": 1,
"network": "testnet",
"status": "pending"
}

Error Responses:
Status Error
400 Order ID and amount required
500 Error creating payment
GET /payments/status/:paymentId

Get payment status (requires auth)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"paymentId": "pay_123456789",
"status": "confirmed",
"confirmations": 10,
"amountReceived": 0.0125,
"txHash": "tx_123456789",
"createdAt": "2026-07-20T10:00:00.000Z",
"confirmedAt": "2026-07-20T11:00:00.000Z"
}

POST /payments/webhook

Simulate payment webhook (test only)

Request:
json

{
"paymentId": "pay_123456789",
"txHash": "tx_123456789",
"amount": 150
}

Response (200 OK):
json

{
"success": true,
"payment": {
"id": "pay_123456789",
"status": "confirmed",
"amount": 150
}
}

🔒 Escrow Endpoints
GET /escrow/status/:orderId

Get escrow status (requires auth)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"escrowId": 1,
"status": "funded",
"amount": 150,
"moneroAmount": 0.0125,
"moneroAddress": "8A1B2C3D4E5F6G7H8I9J0K",
"createdAt": "2026-07-20T10:00:00.000Z",
"expiresAt": "2026-08-19T10:00:00.000Z",
"releaseSignatures": 1,
"requiredSignatures": 2,
"orderStatus": "paid"
}

POST /escrow/release/:orderId

Release funds to seller (requires auth, buyer)

Headers:
http

Authorization: Bearer

Request:
json

{
"signature": "pgp_signed_signature_here"
}

Response (200 OK):
json

{
"success": true,
"signatures": 2,
"required": 2,
"escrow": {
"id": 1,
"status": "released",
"releasedAt": "2026-07-20T12:00:00.000Z"
},
"order": {
"id": 1,
"status": "completed",
"completedAt": "2026-07-20T12:00:00.000Z"
}
}

POST /escrow/refund/:orderId

Refund buyer (requires auth, seller)

Headers:
http

Authorization: Bearer

Request:
json

{
"signature": "pgp_signed_signature_here"
}

Response (200 OK):
json

{
"success": true,
"escrow": {
"id": 1,
"status": "refunded",
"refundedAt": "2026-07-20T12:00:00.000Z"
},
"order": {
"id": 1,
"status": "refunded",
"cancelledAt": "2026-07-20T12:00:00.000Z"
}
}

POST /escrow/dispute/:orderId

Open a dispute (requires auth, buyer or seller)

Headers:
http

Authorization: Bearer

Request:
json

{
"reason": "Service not delivered as described",
"evidence": [
{
"type": "screenshot",
"url": "https://example.com/evidence1.png",
"description": "Screenshot of conversation"
}
]
}

Response (201 Created):
json

{
"success": true,
"disputeId": 1,
"orderId": 1,
"status": "disputed",
"createdAt": "2026-07-20T12:00:00.000Z"
}

🔑 Admin Endpoints
GET /admin/dashboard/stats

Get dashboard statistics (requires admin)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"stats": {
"totalUsers": 150,
"totalSkills": 75,
"totalOrders": 320,
"openDisputes": 5,
"totalRevenue": 48000
},
"recentOrders": [
{
"id": 1,
"amount": 150,
"status": "completed",
"createdAt": "2026-07-20T10:00:00.000Z",
"buyer": { "id": 1, "username": "buyer" },
"seller": { "id": 2, "username": "seller" }
}
],
"pendingSkills": [
{
"id": 1,
"name": "New Skill",
"createdAt": "2026-07-20T09:00:00.000Z",
"seller": { "id": 2, "username": "seller" }
}
]
}

GET /admin/users

List users (requires admin)

Headers:
http

Authorization: Bearer

Query Parameters:
Parameter Type Description
page integer Page number
limit integer Items per page
search string Search by email/username
role string Filter by role
status string active or inactive

Response (200 OK):
json

{
"users": [
{
"id": 1,
"email": "[e-mail]",
"username": "username",
"name": "Full Name",
"role": "user",
"isActive": true,
"rating": 4.5,
"createdAt": "2026-07-20T10:00:00.000Z"
}
],
"pagination": {
"total": 100,
"page": 1,
"limit": 20,
"pages": 5
}
}

PUT /admin/users/:userId

Update user (requires admin)

Headers:
http

Authorization: Bearer

Request:
json

{
"role": "moderator",
"isActive": true
}

Response (200 OK):
json

{
"id": 1,
"email": "[e-mail]",
"role": "moderator",
"isActive": true,
"updatedAt": "2026-07-20T12:00:00.000Z"
}

DELETE /admin/users/:userId

Delete/deactivate user (requires admin)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"success": true,
"message": "User deactivated successfully"
}

GET /admin/skills

List skills with moderation options (requires admin)

Headers:
http

Authorization: Bearer

Query Parameters:
Parameter Type Description
page integer Page number
limit integer Items per page
search string Search by name/description
category string Filter by category
status string active, pending, flagged

Response (200 OK):
json

{
"skills": [
{
"id": 1,
"name": "Skill Name",
"description": "...",
"price": 150,
"category": "development",
"isActive": true,
"isFlagged": false,
"seller": {
"id": 2,
"username": "seller"
},
"createdAt": "2026-07-20T10:00:00.000Z"
}
],
"pagination": {
"total": 50,
"page": 1,
"limit": 20,
"pages": 3
}
}

PUT /admin/skills/:skillId

Update skill (requires admin)

Headers:
http

Authorization: Bearer

Request:
json

{
"isActive": true,
"isFlagged": false
}

Response (200 OK):
json

{
"id": 1,
"isActive": true,
"isFlagged": false,
"updatedAt": "2026-07-20T12:00:00.000Z"
}

DELETE /admin/skills/:skillId

Delete skill (requires admin)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"success": true,
"message": "Skill deleted successfully"
}

GET /admin/orders

List orders (requires admin)

Headers:
http

Authorization: Bearer

Query Parameters:
Parameter Type Description
page integer Page number
limit integer Items per page
status string Filter by status
from date Start date (ISO)
to date End date (ISO)

Response (200 OK):
json

{
"orders": [
{
"id": 1,
"buyerId": 1,
"sellerId": 2,
"amount": 150,
"currency": "USD",
"status": "completed",
"createdAt": "2026-07-20T10:00:00.000Z",
"buyer": { "id": 1, "username": "buyer" },
"seller": { "id": 2, "username": "seller" },
"skill": { "id": 1, "name": "Skill Name" }
}
],
"pagination": {
"total": 100,
"page": 1,
"limit": 20,
"pages": 5
}
}

GET /admin/analytics

Get platform analytics (requires admin)

Headers:
http

Authorization: Bearer

Query Parameters:
Parameter Type Description
period string day, week, month, year (default: month)
from date Start date (ISO)
to date End date (ISO)

Response (200 OK):
json

{
"period": {
"from": "2026-06-20T00:00:00.000Z",
"to": "2026-07-20T00:00:00.000Z"
},
"dailyOrders": [
{ "date": "2026-07-20", "count": 15, "total": 2250 }
],
"userGrowth": [
{ "date": "2026-07-20", "count": 5 }
],
"topCategories": [
{ "category": "development", "count": 30 }
],
"revenueTrend": [
{ "date": "2026-07-20", "total": 2250 }
],
"summary": {
"totalRevenue": 48000,
"totalOrders": 320,
"totalUsers": 150
}
}

GET /admin/system/health

Get system health status (requires admin)

Headers:
http

Authorization: Bearer

Response (200 OK):
json

{
"status": "healthy",
"timestamp": "2026-07-20T12:00:00.000Z",
"uptime": 3600,
"memory": {
"used": 52428800,
"total": 104857600,
"rss": 73400320
},
"cpu": {
"loadAvg": [0.5, 0.4, 0.3],
"cores": 8
},
"database": {
"connected": true,
"latency": "12ms"
},
"version": {
"node": "v18.17.0",
"npm": "9.6.7"
}
}

🔔 Webhook Endpoints
POST /webhook/order-update

Receive payment confirmation from Gateway

Headers:
http

X-Webhook-Signature: hmac_signature_here

Request:
json

{
"orderId": 1,
"txHash": "tx_123456789",
"status": "confirmed",
"amount": 150,
"timestamp": "2026-07-20T11:00:00.000Z"
}

Response (200 OK):
json

{
"success": true,
"order": {
"id": 1,
"status": "paid",
"updatedAt": "2026-07-20T11:00:00.000Z"
}
}

Error Responses:
Status Error
400 Missing orderId or status
404 Order not found
401 Invalid signature
500 Error processing webhook
📊 Error Codes Reference
HTTP Status Codes
Code Name Description
200 OK Request succeeded
201 Created Resource created successfully
204 No Content Request succeeded, no content to return
400 Bad Request Invalid request parameters
401 Unauthorized Authentication required
403 Forbidden Insufficient permissions
404 Not Found Resource not found
409 Conflict Resource conflict (e.g., duplicate email)
422 Unprocessable Entity Validation failed
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error
Common Error Responses
json

{
"error": "Error message",
"details": "Additional details (optional)",
"code": "ERROR_CODE"
}

Error Codes List
Code Description
AUTH_001 Authentication required
AUTH_002 Invalid credentials
AUTH_003 Token expired
AUTH_004 Invalid token
AUTH_005 Account deactivated
AUTH_006 Insufficient permissions
Code Description
USER_001 User not found
USER_002 Email already registered
USER_003 Invalid email format
USER_004 Username already taken
Code Description
SKILL_001 Skill not found
SKILL_002 Already have this skill
SKILL_003 Skill in use (cannot delete)
Code Description
ORDER_001 Order not found
ORDER_002 Cannot self-order
ORDER_003 Order already completed
ORDER_004 Cannot cancel completed order
Code Description
PAYMENT_001 Payment not found
PAYMENT_002 Payment already confirmed
PAYMENT_003 Payment expired
Code Description
ESCROW_001 Escrow not found
ESCROW_002 Invalid signature
ESCROW_003 Insufficient signatures
ESCROW_004 Escrow expired
Code Description
DISPUTE_001 Dispute not found
DISPUTE_002 Dispute already resolved
DISPUTE_003 Already have open dispute
🔧 Rate Limiting
Endpoint Type Limit Window
Public (auth, health) 100 requests 15 minutes
Authenticated 200 requests 15 minutes
Admin 300 requests 15 minutes
Webhooks 1000 requests 1 hour

Rate Limit Headers:
http

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

🧪 Test Commands
Auth Testing
bash

Register

curl -X POST http://localhost:4000/api/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"[e-mail]","password":"test123","username":"testuser","name":"Test User"}'

Login

curl -X POST http://localhost:4000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"[e-mail]","password":"test123"}'

Get profile

curl -X GET http://localhost:4000/api/auth/me \
-H "Authorization: Bearer $TOKEN"

Skill Testing
bash

Create skill

curl -X POST http://localhost:4000/api/skills \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"React Native Developer","description":"Expert","price":150,"category":"development"}'

List skills

curl http://localhost:4000/api/skills

Get skill

curl http://localhost:4000/api/skills/1

Order Testing
bash

Create order

curl -X POST http://localhost:4000/api/orders \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"skillId":1}'

Get orders

curl -X GET http://localhost:4000/api/orders/my \
-H "Authorization: Bearer $TOKEN"

Get order

curl -X GET http://localhost:4000/api/orders/1 \
-H "Authorization: Bearer $TOKEN"

📚 Resources

Postman Collection: [Available on request]

OpenAPI/Swagger: [coming soon]

API Testing: insomnia.rest

✅ Next Steps

Add OpenAPI/Swagger – Generate interactive documentation

Add rate limiting – Protect all endpoints

Add pagination – For all list endpoints

Add filtering – Advanced query parameters

Add sorting – Sort by multiple fields

Add versioning – API versioning strategy

Built with ❤️ for privacy, freedom, and decentralization.

Happy coding! 🚀