The-One-File

TheOneFile Verse API Documentation

Base URL: http://localhost:10101 (or your deployed instance)

Authentication

API Key Authentication

Authorization: Bearer yourapikey

API keys have granular permissions:

Public Endpoints

Check Room Exists

GET /api/room/{roomId}/exists

Response

{
  "exists": true,
  "hasPassword": false,
  "created": "2024-01-15T10:30:00.000Z",
  "destruct": {
    "mode": "time",
    "value": 86400000
  }
}

Create Room

POST /api/room
Content-Type: application/json

{
  "creatorId": "optional uuid",
  "password": "optional room password",
  "destructMode": "time",
  "destructValue": 86400000,
  "topology": null
}

Parameters | Field | Type | Description | |——-|——|————-| | creatorId | string (UUID) | Optional. Auto generated if not provided | | password | string | Optional. Minimum 4 characters | | destructMode | string | time, empty, or never | | destructValue | number | Milliseconds until destruction (max 30 days) | | topology | object | Optional initial state |

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "/s/550e8400-e29b-41d4-a716-446655440000",
  "hasPassword": false
}

Verify Room Password

POST /api/room/{roomId}/verify
Content-Type: application/json

{
  "password": "room password"
}

Response

{
  "valid": true
}

Delete Room (Creator Only)

DELETE /api/room/{roomId}
Content-Type: application/json

{
  "creatorId": "creator uuid"
}

Response

{
  "deleted": true
}

Get Theme Settings

GET /api/theme

Response

{
  "forcedTheme": "user",
  "chatEnabled": true,
  "cursorSharingEnabled": true,
  "nameChangeEnabled": true
}

Rooms

List All Rooms

GET /api/admin/rooms
GET /api/admin/rooms?q=searchterm

Response

{
  "rooms": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "created": "2024-01-15T10:30:00.000Z",
      "lastActivity": "2024-01-15T12:00:00.000Z",
      "hasPassword": false,
      "connectedUsers": 2,
      "destruct": {
        "mode": "time",
        "value": 86400000
      }
    }
  ],
  "total": 1
}

Delete Room

DELETE /api/admin/rooms/{roomId}

Response

{
  "deleted": true
}

Settings

Get Settings

GET /api/admin/settings

Response

{
  "instancePasswordEnabled": false,
  "instancePasswordSet": false,
  "updateIntervalHours": 24,
  "skipUpdates": false,
  "allowPublicRoomCreation": true,
  "maxRoomsPerInstance": 0,
  "defaultDestructMode": "time",
  "defaultDestructHours": 24,
  "forcedTheme": "user",
  "rateLimitEnabled": true,
  "rateLimitWindow": 60,
  "rateLimitMaxAttempts": 10,
  "chatEnabled": true,
  "cursorSharingEnabled": true,
  "nameChangeEnabled": true,
  "webhookEnabled": false,
  "webhookUrl": null,
  "backupEnabled": false,
  "backupIntervalHours": 24,
  "backupRetentionCount": 7
}

Update Settings

POST /api/admin/settings
Content-Type: application/json

{
  "chatEnabled": false,
  "webhookEnabled": true,
  "webhookUrl": "https://example.com/webhook"
}

Only include fields you want to update.

Activity Logs

Get Activity Logs

GET /api/admin/activity-logs
GET /api/admin/activity-logs?room={roomId}

Response

{
  "logs": [
    {
      "id": 1,
      "timestamp": "2024-01-15T10:30:00.000Z",
      "roomId": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user uuid",
      "userName": "Connor MacLeod",
      "eventType": "join",
      "ipAddress": "192.168.1.1"
    }
  ]
}

Audit Logs

Get Audit Logs

GET /api/admin/audit-logs
GET /api/admin/audit-logs?q=searchterm

Response

{
  "logs": [
    {
      "id": 1,
      "timestamp": "2024-01-15T10:30:00.000Z",
      "action": "room_deleted",
      "actor": "admin",
      "actorIp": "192.168.1.1",
      "targetType": "room",
      "targetId": "550e8400-e29b-41d4-a716-446655440000",
      "details": null
    }
  ]
}

Backups

List Backups

GET /api/admin/backups

Response

{
  "backups": [
    {
      "id": "backup uuid",
      "filename": "backup_2024-01-15T10-30-00.json",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "sizeBytes": 15234,
      "roomCount": 5,
      "autoGenerated": false
    }
  ]
}

Create Backup

POST /api/admin/backups

Response

{
  "success": true,
  "backup": {
    "id": "backup uuid",
    "filename": "backup_2024-01-15T10-30-00.json",
    "sizeBytes": 15234,
    "roomCount": 5
  }
}

Download Backup

GET /api/admin/backups/{backupId}/download

Returns the backup file as JSON download.

Restore Backup

POST /api/admin/backups/{backupId}/restore

Response

{
  "success": true,
  "roomsRestored": 3
}

Delete Backup

DELETE /api/admin/backups/{backupId}

Response

{
  "deleted": true
}

Export

Export All Data

GET /api/admin/export

Returns a JSON file containing all rooms and settings.

Response Structure

{
  "version": 1,
  "exportedAt": "2024-01-15T10:30:00.000Z",
  "rooms": [...],
  "settings": {...}
}

API Keys

List API Keys

GET /api/admin/api-keys

Response

{
  "keys": [
    {
      "id": "key uuid",
      "name": "My Integration",
      "permissions": ["read", "write"],
      "createdAt": "2024-01-15T10:30:00.000Z",
      "lastUsed": "2024-01-15T12:00:00.000Z",
      "expiresAt": null,
      "active": true
    }
  ]
}

Create API Key

POST /api/admin/api-keys
Content-Type: application/json

{
  "name": "My Integration",
  "permissions": ["read", "write"],
  "expiresInDays": 30
}

Parameters | Field | Type | Description | |——-|——|————-| | name | string | Required. Display name for the key | | permissions | array | read, write, admin | | expiresInDays | number | Optional. 0 or null for no expiration |

Response

{
  "id": "key uuid",
  "key": "tof_a1b2c3d4e5f6...",
  "name": "My Integration",
  "permissions": ["read", "write"]
}

Important: The key value is only returned once at creation. Store it securely.

Revoke API Key

DELETE /api/admin/api-keys/{keyId}

Response

{
  "revoked": true
}

Source Management

Change Source Mode

POST /api/admin/source-mode
Content-Type: application/json

{
  "mode": "github"
}

Modes: github (auto update from GitHub) or local (manual upload)

Trigger GitHub Update

POST /api/admin/update

Response

{
  "success": true,
  "size": 245678
}

Upload Local HTML

POST /api/admin/upload-html
Content-Type: multipart/form-data

file: [HTML file]

Response

{
  "success": true,
  "size": 245678,
  "edition": "networkening"
}

WebSocket API

ws://localhost:10101/ws/{roomId}

Message Types

Join Room

{
  "type": "join",
  "user": {
    "id": "user uuid",
    "name": "Connor MacLeod",
    "color": "#e63946"
  }
}

Leave Room

{
  "type": "leave",
  "userId": "user uuid"
}

Presence Update

{
  "type": "presence",
  "userId": "user uuid",
  "selectedNodes": ["node-1", "node-2"],
  "editingNode": "node-1",
  "currentTab": "Main"
}

State Sync

{
  "type": "state",
  "state": {
    "nodeData": {...},
    "edgeData": {...},
    "imageData": {...},
    ...
  }
}

Cursor Position

{
  "type": "cursor",
  "userId": "user uuid",
  "x": 1500,
  "y": 1200,
  "isCanvasCoords": true
}

Chat Message

{
  "type": "chat",
  "userId": "user uuid",
  "userName": "Connor MacLeod",
  "userColor": "#e63946",
  "text": "Hello everyone!",
  "timestamp": 1705312200000
}

Server Messages

Initial State

{
  "type": "initial-state",
  "state": {...}
}

User List

{
  "type": "users",
  "users": [...]
}

Name Rejected

{
  "type": "name-rejected",
  "reason": "Name already taken in this room"
}

Rate Limiting

When rate limiting is enabled, endpoints return 429 Too Many Requests if limits are exceeded.

Default limits:

Response:

{
  "error": "Too many attempts. Try again later."
}

Error Responses

All errors follow this format:

{
  "error": "Error message description"
}

Common HTTP status codes:

Webhook Events

When webhooks are enabled, POST requests are sent to your configured URL.

Room Created

{
  "event": "room_created",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "roomId": "550e8400-e29b-41d4-a716-446655440000",
    "hasPassword": false,
    "destructMode": "time",
    "creatorId": "creator uuid"
  }
}
This site is open source. Improve this page.