Skip to main content
The Skillhouse API is a REST API that serves the web client and any third-party integrations you build on top of the platform. All requests and responses use JSON.
Skillhouse is self-hosted. Replace https://your-backend-domain.com with the URL of your running backend instance. If you are running locally, this is typically http://localhost:3000.

​
Base URL

https://your-backend-domain.com/api

​
Route groups

The API is organized into five route groups based on the actor or resource being accessed.
PrefixPurpose
/api/auth/*Registration, login, OTP verification, and password reset
/api/client/*Job postings, contracts, payments, and reviews for clients
/api/freelancer/*Applications, active contracts, and wallet for freelancers
/api/admin/*User management, categories, escrow releases, and revenue
/api/media/*File uploads (images, videos)

Auth endpoints

Register, log in, verify OTP, refresh tokens, and reset passwords.

Jobs endpoints

Post jobs, browse listings, and manage proposals.

Contracts endpoints

Create and manage contracts through their full lifecycle.

Payments endpoints

Handle escrow deposits, releases, and refunds via Stripe.

Freelancer endpoints

Manage freelancer profiles, applications, and wallet.

Admin endpoints

Oversee users, categories, escrow, and platform revenue.

​
Authentication

Protected endpoints require a valid JWT access token. You can send the token in one of two ways:
  • Authorization header — Authorization: Bearer <accessToken>
  • HttpOnly cookie — the refreshToken cookie is set automatically on login and used to issue new access tokens
Most browser-based clients will rely on cookies. API integrations should use the Authorization header. See Authentication for the full flow.

​
Request format

Set Content-Type: application/json on all requests that include a body. 
curl -X POST https://your-backend-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "yourpassword"}'

​
HTTP methods

The API uses standard HTTP methods:
MethodUsage
GETRetrieve a resource or list
POSTCreate a resource or trigger an action
PUTReplace a resource
PATCHPartially update a resource
DELETERemove a resource

​
Response format

All responses return JSON. Successful responses include relevant data at the top level: 
{
  "message": "Login successful",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": "client",
  "user": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Alex Johnson",
    "email": "[email protected]",
    "status": "active",
    "profilePic": ""
  }
}

​
Error responses

Errors follow a consistent shape across all endpoints: 
{
  "message": "Invalid credentials",
  "status": 400
}
Common HTTP status codes:
CodeMeaning
400Bad request — missing or invalid parameters
401Unauthorized — missing, expired, or invalid token
403Forbidden — valid token but insufficient role
404Not found — resource does not exist
409Conflict — resource already exists (e.g., duplicate email)
500Internal server error

​
CORS

The API allows cross-origin requests from the URL configured in the CLIENT_URL environment variable on the server. If you are calling the API from a browser on a different origin, ensure the backend CLIENT_URL is set to your frontend’s domain. Allowed headers: Content-Type, Authorization Allowed methods: GET, POST, PUT, PATCH, DELETE Credentials (cookies) are supported — the API sets credentials: true in its CORS configuration.
See Environment variables for the full list of variables required to run the backend, including CLIENT_URL.

Build docs developers (and LLMs) love

Get started for freeTalk to us