API Overview

Nanostack provides a comprehensive REST API with OpenAPI 3.0 specification. All endpoints are designed with multi-tenancy in mind and include proper authentication and authorization.

Base URL

Production: https://api.nanostack.dev
Development: http://localhost:8080

Authentication

JWT Tokens

Most endpoints require JWT authentication:

curl -H "Authorization: Bearer your-jwt-token" \
  https://api.nanostack.dev/v1/users

API Keys

For server-to-server communication:

curl -H "X-API-Key: your-api-key" \
  https://api.nanostack.dev/v1/users

Core Endpoints

Authentication

• POST /auth/login - User login
• POST /auth/register - User registration
• POST /auth/refresh - Refresh JWT token
• POST /auth/logout - User logout

User Management

• GET /users - List users in tenant
• POST /users - Create new user
• GET /users/{id} - Get user by ID
• PUT /users/{id} - Update user
• DELETE /users/{id} - Delete user

Organization Management

• GET /organizations - List organizations
• POST /organizations - Create organization
• GET /organizations/{id} - Get organization
• PUT /organizations/{id} - Update organization
• DELETE /organizations/{id} - Delete organization

Tenant Management

• GET /tenants - List tenants (admin only)
• POST /tenants - Create tenant (admin only)
• GET /tenants/{id} - Get tenant details
• PUT /tenants/{id} - Update tenant

API Key Management

• GET /api-keys - List API keys
• POST /api-keys - Create API key
• GET /api-keys/{id} - Get API key
• PUT /api-keys/{id} - Update API key
• DELETE /api-keys/{id} - Revoke API key

Request Format

All POST and PUT requests should use JSON:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-jwt-token" \
  -d '{"name":"John Doe","email":"[email protected]"}' \
  https://api.nanostack.dev/v1/users

Response Format

All responses follow a consistent structure:

Success Response

{
  "success": true,
  "data": {
    "id": "user_123",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}

Pagination

List endpoints support pagination:

curl "https://api.nanostack.dev/v1/users?page=2&per_page=50"

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 150,
    "total_pages": 3
  }
}

Filtering and Sorting

Filtering

# Filter by field
curl "https://api.nanostack.dev/v1/[email protected]"

# Multiple filters
curl "https://api.nanostack.dev/v1/users?role=admin&active=true"

Sorting

# Sort by field
curl "https://api.nanostack.dev/v1/users?sort=created_at"

# Descending order
curl "https://api.nanostack.dev/v1/users?sort=-created_at"

# Multiple sort fields
curl "https://api.nanostack.dev/v1/users?sort=name,-created_at"

Rate Limiting

API requests are rate limited:

• Authenticated requests: 1000 requests per hour per user
• Anonymous requests: 100 requests per hour per IP
• API key requests: 5000 requests per hour per key

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Error Codes

Common HTTP status codes:

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Too Many Requests
500	Internal Server Error

Interactive Documentation

Explore the full API using our interactive Swagger UI:

• Production: https://api.nanostack.dev/docs
• Local: http://localhost:8080/docs

SDK and Examples

• Go SDK - Official Go client library
• JavaScript SDK - Official JS/TS client
• Python SDK - Official Python client
• API Examples - Common usage patterns

Need Help?

• View detailed endpoint documentation
• Check authentication examples
• Join our Discord for support