Welcome to the nself-chat (nchat) API documentation. This guide covers everything you need to integrate with the nchat API.

• Getting Started
• Authentication
• Common Patterns
• Error Handling
• Rate Limiting
• API Endpoints Overview
• Code Examples
• Best Practices
• Support

• Local Development: http://localhost:3000
• Production: https://api.nchat.app (or your custom domain)

Visit /api-docs to explore the API interactively using Swagger UI:

• Local: http://localhost:3000/api-docs
• Production: https://your-domain.com/api-docs

The complete OpenAPI 3.0 specification is available at:

• /openapi.yaml - YAML format
• Download: openapi.yaml

You can import this into tools like Postman, Insomnia, or generate client SDKs.

nchat uses JWT (JSON Web Tokens) for authentication. Most endpoints require a valid JWT token in the Authorization header.

Endpoint: POST /api/auth/signin

curl -X POST http://localhost:3000/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Response:

{
  "user": {
    "id": "user-123",
    "email": "[email protected]",
    "username": "johndoe",
    "displayName": "John Doe",
    "role": "member",
    "status": "online"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Endpoint: POST /api/auth/signup

curl -X POST http://localhost:3000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123",
    "username": "johndoe",
    "displayName": "John Doe"
  }'

The first user to sign up automatically becomes the owner with full admin privileges.

Include the access token in the Authorization header for authenticated requests:

curl -X GET http://localhost:3000/api/config?history=true \
  -H "Authorization: Bearer <your-access-token>"

• Access Token: Valid for 24 hours
• Refresh Token: Valid for 30 days

Note: Token refresh functionality is not yet implemented in the API. You'll need to re-authenticate when the access token expires.

Admin-only endpoints return 403 Forbidden for non-admin users.

All POST/PATCH requests expect JSON payloads:

curl -X POST <endpoint> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{ "key": "value" }'

All API responses follow a consistent structure:

Success Response:

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response:

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

Endpoints that return lists support pagination:

Parameters:

• page - Page number (1-indexed)
• limit - Items per page (default: 20, max: 100)
• offset - Number of items to skip (alternative to page)

Example:

curl "http://localhost:3000/api/search?q=hello&limit=20&offset=0"

Response includes pagination metadata:

{
  "items": [...],
  "total": 150,
  "page": 1,
  "limit": 20,
  "hasMore": true
}

Many endpoints support filtering and sorting:

# Quick search
GET /api/search?q=query&limit=20

# Advanced search with filters
POST /api/search
{
  "query": "project update",
  "types": ["messages", "files"],
  "channelIds": ["channel-1"],
  "dateFrom": "2024-01-01",
  "dateTo": "2024-12-31",
  "sortBy": "date",
  "sortOrder": "desc"
}

Common error codes returned in the code field:

{
  "success": false,
  "error": "Validation failed: branding.appName must be 1-50 characters",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "branding.appName",
    "constraint": "length"
  }
}

JavaScript/TypeScript:

try {
  const response = await fetch('/api/endpoint', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify(data),
  })

  const result = await response.json()

  if (!response.ok) {
    throw new Error(result.error || 'Request failed')
  }

  // Handle success
  console.log(result.data)
} catch (error) {
  console.error('API error:', error.message)
}

Every response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

When you exceed the rate limit, the API returns 429 Too Many Requests:

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Best practices:

• Check X-RateLimit-Remaining header
• Implement exponential backoff on 429 responses
• Cache responses when possible
• Use webhooks instead of polling

Retry Logic Example:

async function apiRequestWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options)

    if (response.status !== 429) {
      return response
    }

    // Exponential backoff: 1s, 2s, 4s
    const delay = Math.pow(2, i) * 1000
    await new Promise((resolve) => setTimeout(resolve, delay))
  }

  throw new Error('Max retries exceeded')
}

async function getConfig() {
  const response = await fetch('/api/config')
  const data = await response.json()
  return data.config
}

async function updateConfig(updates: Partial<AppConfig>, token: string) {
  const response = await fetch('/api/config', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify(updates),
  })

  if (!response.ok) {
    const error = await response.json()
    throw new Error(error.error)
  }

  return response.json()
}

async function uploadFile(file: File, token: string) {
  // Step 1: Initialize upload
  const initResponse = await fetch('/api/upload', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      filename: file.name,
      contentType: file.type,
      size: file.size,
    }),
  })

  const { fileId, uploadUrl, method, headers } = await initResponse.json()

  // Step 2: Upload file to presigned URL
  const uploadResponse = await fetch(uploadUrl, {
    method,
    headers,
    body: file,
  })

  if (!uploadResponse.ok) {
    throw new Error('Upload failed')
  }

  return fileId
}

async function searchMessages(query: string, channelId: string) {
  const response = await fetch('/api/search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query,
      types: ['messages'],
      channelIds: [channelId],
      limit: 50,
    }),
  })

  const data = await response.json()
  return data.results
}

import requests

# Sign in
def sign_in(email: str, password: str):
    response = requests.post('http://localhost:3000/api/auth/signin', json={
        'email': email,
        'password': password
    })
    response.raise_for_status()
    return response.json()

# Get config
def get_config(token: str = None):
    headers = {}
    if token:
        headers['Authorization'] = f'Bearer {token}'

    response = requests.get('http://localhost:3000/api/config', headers=headers)
    response.raise_for_status()
    return response.json()['config']

# Update config
def update_config(updates: dict, token: str):
    response = requests.post(
        'http://localhost:3000/api/config',
        json=updates,
        headers={'Authorization': f'Bearer {token}'}
    )
    response.raise_for_status()
    return response.json()

# Sign in
curl -X POST http://localhost:3000/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"pass123"}'

# Get config
curl http://localhost:3000/api/config

# Update config (admin)
curl -X POST http://localhost:3000/api/config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "branding": {
      "appName": "My Team Chat"
    }
  }'

# Search
curl -X POST http://localhost:3000/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "project update",
    "types": ["messages"],
    "limit": 20
  }'

# Send webhook
curl -X POST http://localhost:3000/api/webhook/webhook-id/token \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Deployment successful!",
    "username": "CI/CD Bot"
  }'

• Store tokens securely: Use httpOnly cookies or secure storage
• Refresh tokens: Implement token refresh before expiry
• Don't expose tokens: Never log or expose tokens in URLs
• Use HTTPS: Always use HTTPS in production

• Check status codes: Don't rely solely on response body
• Handle all error types: Network errors, timeouts, API errors
• Retry on transient errors: Implement retry logic for 5xx errors
• Log errors: Log errors for debugging but sanitize sensitive data

• Cache when possible: Use cache headers and client-side caching
• Batch requests: Combine multiple operations when possible
• Use pagination: Don't fetch all records at once
• Compress payloads: Use gzip/brotli compression
• Minimize payload size: Only request fields you need

• Respect limits: Monitor X-RateLimit-* headers
• Implement backoff: Use exponential backoff on 429 responses
• Use webhooks: Instead of polling, use webhooks for real-time updates
• Cache responses: Reduce redundant API calls

• Validate input: Always validate and sanitize user input
• Use webhooks securely: Validate webhook signatures
• Monitor for abuse: Implement monitoring and alerting
• Keep dependencies updated: Regularly update client libraries

• Test in development: Use development environment first
• Handle version changes: Monitor API version and changelog
• Implement health checks: Use /api/health and /api/ready
• Log API calls: Log requests/responses for debugging

• Interactive Docs: http://localhost:3000/api-docs
• OpenAPI Spec: openapi.yaml
• GitHub: https://github.com/nself-chat
• Documentation: docs/

1. Check Documentation: Review this guide and API docs
2. Check Examples: See code examples above
3. Check Issues: Search existing GitHub issues
4. Create Issue: Open a new issue with:
   • API endpoint
   • Request/response
   • Error message
   • Environment details

When reporting API bugs, include:

• Endpoint: Full URL and HTTP method
• Request: Headers and body
• Response: Status code, headers, body
• Expected: What you expected to happen
• Environment: Development/production, version

To request new API features:

1. Check if it already exists
2. Describe the use case
3. Provide example request/response
4. Explain the benefit

• Initial API documentation
• OpenAPI 3.0 specification
• Interactive Swagger UI
• Complete endpoint coverage
• Authentication flow
• Rate limiting
• Error handling

Happy Building! 🚀

For questions or feedback, reach out via GitHub Issues or contribute to the project.