← ENiGMA½ BBS docs
API docs by Redocly

ENiGMA½ BBS REST API (1)

Download OpenAPI specification:

REST API for ENiGMA½ BBS. Base path: /_enig/api/v1

Authentication

Most write endpoints and some read endpoints require authentication. Two schemes are supported:

  • Bearer JWT — obtain via POST /auth/login. Short-lived (15 min). Refresh with POST /auth/refresh using the enigma_refresh HttpOnly cookie.
  • API Key — static key in Authorization: Bearer <key> header, generated via oputil rest api-key generate. Suitable for scripts and bots.

Public endpoints (system info, public message areas, public file areas) work without authentication. The sysop can tune which endpoints are public via config.hjson.

Auth

Authentication and token management

Log in and obtain tokens

Request Body schema: application/json
required
username
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "tokenType": "Bearer",
  • "expiresIn": 0
}

Rotate refresh token and issue new access token

Reads the enigma_refresh HttpOnly cookie set by /auth/login.

Responses

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "tokenType": "Bearer",
  • "expiresIn": 0
}

Revoke the current refresh token

Responses

System

Board information and live node status

Basic board information

Public by default. Can be restricted via config.

Responses

Response samples

Content type
application/json
{
  • "boardName": "string",
  • "version": "string",
  • "nodeCount": 0,
  • "closedSystem": true
}

Active node list

Authentication required by default. Can be made public via config.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Recent login history

Public by default. Returns up to 50 entries.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Board statistics

Public by default.

Responses

Response samples

Content type
application/json
{
  • "totalUsers": 0
}

Messages

Message conferences, areas, and posts

List message conferences

Authenticated users see all conferences their ACS permits. Unauthenticated callers see only conferences with areas in the public allowlist.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Conference detail with area list

Authorizations:
bearerAuth
path Parameters
confTag
required
string

Responses

Response samples

Content type
application/json
{
  • "confTag": "string",
  • "name": "string",
  • "desc": "string",
  • "areas": [
    ]
}

Message area detail

Authorizations:
bearerAuth
path Parameters
areaTag
required
string

Responses

Response samples

Content type
application/json
{
  • "areaTag": "string",
  • "name": "string",
  • "desc": "string",
  • "confTag": "string"
}

List messages in an area

Authorizations:
bearerAuth
path Parameters
areaTag
required
string
query Parameters
limit
integer <= 100
Default: 25
cursor
string

Opaque cursor from a previous response's meta.nextCursor

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Post a message to an area

Authorizations:
bearerAuth
path Parameters
areaTag
required
string
Request Body schema: application/json
required
subject
required
string <= 72 characters
message
required
string
toUserName
string
Default: "All"
replyToMessageId
integer

Responses

Request samples

Content type
application/json
{
  • "subject": "string",
  • "message": "string",
  • "toUserName": "All",
  • "replyToMessageId": 0
}

Response samples

Content type
application/json
{
  • "messageId": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "areaTag": "string",
  • "replyToMessageId": 0,
  • "toUserName": "string",
  • "fromUserName": "string",
  • "subject": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Full message detail

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "messageId": 0,
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "areaTag": "string",
  • "replyToMessageId": 0,
  • "toUserName": "string",
  • "fromUserName": "string",
  • "subject": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "body": "string",
  • "network": {
    }
}

Delete a message

Users may delete their own messages. Sysops may delete any message.

Authorizations:
bearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{}

Files

File areas, metadata, uploads, and downloads

List file areas

Authenticated users see all areas their ACS permits. Unauthenticated callers see only areas in the public allowlist.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

File area detail

Authorizations:
bearerAuth
path Parameters
areaTag
required
string

Responses

Response samples

Content type
application/json
{
  • "areaTag": "string",
  • "name": "string",
  • "desc": "string",
  • "storageTag": "string"
}

Upload a file to an area

Authorizations:
bearerAuth
path Parameters
areaTag
required
string
Request Body schema: multipart/form-data
required
file
required
string <binary>

The file to upload (max 512 MiB)

desc
string

Short description (overrides FILE_ID.DIZ if present)

Responses

Response samples

Content type
application/json
{
  • "fileId": 0,
  • "areaTag": "string",
  • "fileName": "string",
  • "desc": "string",
  • "descLong": "string",
  • "byteSize": 0,
  • "uploadTimestamp": "2019-08-24T14:15:22Z",
  • "uploadByUsername:{ type": null,
  • "dlCount": 0,
  • "sha256": "string",
  • "archiveType": "string",
  • "hashTags": [
    ],
  • "estReleaseYear": 0
}

List files in an area

Authorizations:
bearerAuth
path Parameters
areaTag
required
string
query Parameters
limit
integer <= 100
Default: 25
cursor
string

Opaque cursor from a previous response's meta.nextCursor

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

File metadata

Authorizations:
bearerAuth
path Parameters
fileId
required
integer

Responses

Response samples

Content type
application/json
{
  • "fileId": 0,
  • "areaTag": "string",
  • "fileName": "string",
  • "desc": "string",
  • "descLong": "string",
  • "byteSize": 0,
  • "uploadTimestamp": "2019-08-24T14:15:22Z",
  • "uploadByUsername:{ type": null,
  • "dlCount": 0,
  • "sha256": "string",
  • "archiveType": "string",
  • "hashTags": [
    ],
  • "estReleaseYear": 0
}

Download a file

Authorizations:
bearerAuth
path Parameters
fileId
required
integer

Responses

Response samples

Content type
application/problem+json
{}

Users

User profiles

Own profile (full detail)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "userId": 0,
  • "username": "string",
  • "groups": [
    ],
  • "realName": "string",
  • "location": "string",
  • "affiliations": "string",
  • "emailAddress": "string",
  • "webAddress": "string",
  • "autoSignature": "string",
  • "accountCreated": "2019-08-24T14:15:22Z",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "loginCount": 0,
  • "postCount": 0,
  • "uploadCount": 0,
  • "uploadBytes": 0,
  • "downloadCount": 0,
  • "downloadBytes": 0,
  • "achievementPoints:{ type": null,
  • "minutesOnline": 0
}

Update own profile

Authorizations:
bearerAuth
Request Body schema: application/json
required
realName
string or null <= 64 characters
location
string or null <= 64 characters
affiliations
string or null <= 64 characters
webAddress
string or null <= 256 characters
autoSignature
string or null <= 512 characters

Responses

Request samples

Content type
application/json
{
  • "realName": "string",
  • "location": "string",
  • "affiliations": "string",
  • "webAddress": "string",
  • "autoSignature": "string"
}

Response samples

Content type
application/json
{
  • "userId": 0,
  • "username": "string",
  • "groups": [
    ],
  • "realName": "string",
  • "location": "string",
  • "affiliations": "string",
  • "emailAddress": "string",
  • "webAddress": "string",
  • "autoSignature": "string",
  • "accountCreated": "2019-08-24T14:15:22Z",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "loginCount": 0,
  • "postCount": 0,
  • "uploadCount": 0,
  • "uploadBytes": 0,
  • "downloadCount": 0,
  • "downloadBytes": 0,
  • "achievementPoints:{ type": null,
  • "minutesOnline": 0
}

Public user profile

Profile fields are opt-in — only shown when the user has set them. Authenticated sysops receive additional fields marked "Sysop only".

Authorizations:
bearerAuth
path Parameters
username
required
string

Responses

Response samples

Content type
application/json
{
  • "userId": 0,
  • "username": "string",
  • "accountCreated": "2019-08-24T14:15:22Z",
  • "postCount": 0,
  • "achievementPoints:{ type": null,
  • "realName": "string",
  • "location": "string",
  • "affiliations": "string",
  • "webAddress": "string",
  • "groups": [
    ],
  • "emailAddress": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "loginCount": 0,
  • "uploadCount": 0,
  • "downloadCount": 0,
  • "minutesOnline": 0
}