🚀 go-pugleaf

RetroBBS NetNews Server

Inspired by RockSolid Light RIP Retro Guy

🏠 Home 📰 News 🗂️ Usenet Search 🔑 Login

go-pugleaf BBS Help System

Your guide to navigating the NNTP newsgroup interface

RESTful API Endpoints
Authentication Required: Most API endpoints require the X-API header with a valid token. Only /api/v1/stats is publicly accessible.

Authentication Method

API endpoints require authentication via the X-API custom header:

X-API: your-api-token-here
Public Endpoints (No Auth Required)

The following endpoints are publicly accessible without authentication, but only while the API is enabled (otherwise they answer 503):

GET /api/v1/stats System statistics and performance metrics
GET /api/v1/groups/:group/articles/:articleNum/preview Article preview/excerpt without full content. The same preview is served by the web route GET /groups/:group/articles/:articleNum/preview, which the thread tree view uses and which does not depend on the API setting.
Token Management: API tokens are managed through the admin interface. Contact your system administrator for access.

Authentication Required: These endpoints require the X-API header.
GET /api/v1/groups List all available newsgroups with metadata
GET /api/v1/groups/:group/overview Get article overview for a specific newsgroup
GET /api/v1/groups/:group/threads Get threaded conversation structure for a group
GET /api/v1/groups/:group/articles/:articleNum Get specific article by article number
GET /api/v1/groups/:group/message/:messageId Get specific article by message ID
Response Format: All API endpoints return JSON data with appropriate HTTP status codes.
Rate Limiting: API calls may be rate-limited during high traffic periods.
API Usage Examples
Note: Replace your-api-token with your actual API token. Only /api/v1/stats is public.
Public Endpoints (No Auth Required)
curl https://api.pugleaf.net/api/v1/stats
Returns system statistics - no authentication needed
Article Preview (No Auth Required)
curl https://api.pugleaf.net/api/v1/groups/alt.comp.freeware/articles/123/preview
Returns article preview/excerpt without authentication (requires the API to be enabled)
Get All Newsgroups (Auth Required)
curl -H "X-API: your-api-token" \
    https://api.pugleaf.net/api/v1/groups
Returns JSON array of all available newsgroups
Get Group Articles (Auth Required)
curl -H "X-API: your-api-token" \
    https://api.pugleaf.net/api/v1/groups/alt.comp.freeware/overview
Returns article overview for the specified group
Get Specific Article (Auth Required)
curl -H "X-API: your-api-token" \
    https://api.pugleaf.net/api/v1/groups/alt.comp.freeware/articles/123
Returns full article content including headers and body
Get Article by Message ID (Auth Required)
curl -H "X-API: your-api-token" \
    https://api.pugleaf.net/api/v1/groups/alt.comp.freeware/message/<msg-id@domain.com>
Returns article by message ID instead of article number
Get Thread Structure (Auth Required)
curl -H "X-API: your-api-token" \
    https://api.pugleaf.net/api/v1/groups/alt.comp.freeware/threads
Returns threaded conversation structure for the group
Authentication Errors: Missing or invalid X-API header will return HTTP 401 Unauthorized.
Quick Actions
Start Browsing Groups Search for Content View System Status