Skip to main content

​
Overview

Permission Mongo provides a high-performance REST API for managing multi-tenant data with built-in permission controls, document versioning, and audit logging. The API is built on fasthttp for maximum throughput and minimal latency.

​
Base URL

All API requests are made to: 
http://localhost:8080
You can configure the host and port in your config.yaml: 
server:
  host: "0.0.0.0"
  port: 8080

​
API Versioning

The current API version is embedded in the response metadata. Version information is available via: 
curl http://localhost:8080/health

{
  "data": {
    "status": "ok",
    "goroutines": 42
  },
  "meta": {
    "request_id": "a1b2c3d4e5f6",
    "version": "v1"
  }
}

​
Response Format

All API responses follow a consistent structure:

​
Success Response

​
data
any
The response payload (object, array, or primitive)
​
pagination
object
Pagination metadata (only for list endpoints)
​
meta
object
Response metadata

​
Example Success Response

curl -X GET "http://localhost:8080/users/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "email": "[email protected]",
    "role": "admin"
  },
  "meta": {
    "request_id": "a1b2c3d4e5f6",
    "version": "v1"
  }
}

​
Error Response

​
error
object
Error information
​
meta
object
Response metadata (same as success response)

​
Example Error Response

curl -X GET "http://localhost:8080/users/invalid_id" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "error": {
    "code": "NOT_FOUND",
    "message": "document not found"
  },
  "meta": {
    "request_id": "b7c8d9e0f1a2",
    "version": "v1"
  }
}

​
Request Headers

All API requests should include:
​
Content-Type
string
default:"application/json"
required
Must be application/json for POST, PUT, and PATCH requests
​
Authorization
string
required
Bearer token for authentication (see Authentication)
​
X-Request-ID
string
Optional client-provided request ID for tracing. If not provided, the server generates one.

​
Response Headers

The API returns these headers:
​
X-Request-ID
string
Unique request identifier for tracing and debugging
​
Content-Type
string
Always application/json; charset=utf-8
​
Access-Control-Allow-Origin
string
CORS header (if configured)

​
Health Check Endpoints

​
Health Check

Check if the server is running: 
curl http://localhost:8080/health

{
  "data": {
    "status": "ok",
    "goroutines": 42
  },
  "meta": {
    "request_id": "c9d0e1f2a3b4"
  }
}

​
Readiness Check

Check if the server is ready to accept requests (includes dependency checks): 
curl http://localhost:8080/ready

{
  "data": {
    "status": "ready",
    "checks": {
      "mongodb": "ok",
      "redis": "ok"
    },
    "goroutines": 42
  },
  "meta": {
    "request_id": "d0e1f2a3b4c5"
  }
}

​
HTTP Methods

The API follows RESTful conventions:
  • GET - Retrieve resources
  • POST - Create new resources
  • PUT - Update existing resources (full replacement)
  • PATCH - Partially update resources
  • DELETE - Delete resources
  • OPTIONS - CORS preflight requests

​
Content Types

The API only accepts and returns JSON:
  • Request: application/json
  • Response: application/json; charset=utf-8

​
Idempotency

  • GET, PUT, and DELETE operations are idempotent
  • POST operations are not idempotent (each call creates a new resource)
  • Use X-Request-ID header for request deduplication if needed

​
Performance

The API is built for high performance:
  • Concurrency: Supports up to 262,144 concurrent connections
  • Keep-Alive: TCP keep-alive enabled by default
  • Timeouts: Configurable read/write timeouts
  • Memory: Optimized for speed over memory usage
Configure timeouts in config.yaml: 
server:
  read_timeout: 30s
  write_timeout: 30s

Build docs developers (and LLMs) love

Get started for freeTalk to us