Skip to main content

API Documentation

Overview​

The KOL Network API provides programmatic access to manage Matrix servers, user subscriptions, and system operations. All APIs use REST architecture and communicate using JSON.

Base URLs​

  • Production: https://api.kolnetwork.com/v1
  • Staging: https://api.staging.kolnetwork.com/v1

Authentication​

All API requests require authentication using JWT tokens. Obtain tokens through the authentication endpoint.

Authorization: Bearer <token>

API Endpoints​

Authentication​

POST /auth/token​

Obtain authentication token.

Request:

{
  "username": "string",
  "password": "string",
  "mfa_code": "string" // optional
}

Response:

{
  "access_token": "string",
  "token_type": "Bearer",
  "expires_in": 3600
}

Subscription Management​

POST /subscriptions​

Create new subscription.

Request:

{
  "tier": "string",
  "user_id": "string",
  "payment_method": "string"
}

GET /subscriptions/{id}​

Get subscription details.

Response:

{
  "id": "string",
  "status": "active",
  "tier": "string",
  "created_at": "timestamp",
  "server_info": {
    "id": "string",
    "status": "running",
    "domain": "string"
  }
}

Matrix Server Management​

POST /servers​

Provision new Matrix server.

Request:

{
  "subscription_id": "string",
  "domain": "string",
  "config": {
    "max_users": 100,
    "storage_quota": 1000
  }
}

GET /servers/{id}​

Get server status and details.

Response:

{
  "id": "string",
  "status": "running",
  "domain": "string",
  "metrics": {
    "users": 45,
    "storage_used": 234,
    "cpu_usage": 12.5
  }
}

User Management​

POST /users​

Create new user.

Request:

{
  "email": "string",
  "role": "string",
  "server_id": "string"
}

GET /users/{id}​

Get user details.

Response:

{
  "id": "string",
  "email": "string",
  "role": "string",
  "status": "active",
  "servers": ["string"]
}

Data Export​

POST /exports​

Initialize data export.

Request:

{
  "server_id": "string",
  "export_type": "full|partial",
  "date_range": {
    "start": "timestamp",
    "end": "timestamp"
  }
}

Response:

{
  "export_id": "string",
  "status": "processing",
  "estimated_completion": "timestamp"
}

Error Handling​

All errors follow standard HTTP status codes and include detailed messages:

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

Common error codes:

  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 429: Too Many Requests
  • 500: Internal Server Error

Rate Limiting​

API requests are limited by:

  • 1000 requests per hour per IP
  • 10000 requests per day per account

Rate limit headers:

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

Webhook Events​

Subscribe to events using webhooks:

{
  "event": "server.created",
  "server_id": "string",
  "timestamp": "string",
  "data": {}
}

Available events:

  • server.created
  • server.updated
  • server.deleted
  • subscription.created
  • subscription.updated
  • subscription.cancelled
  • export.completed
  • user.created
  • user.updated