PufferBlow API Reference - Developer Documentation

PufferBlow API Reference - Developer Documentation#

This reference documents the main REST and federation endpoints in the current beta server. The API uses standard HTTP methods and JSON payloads.

Most feature endpoints require an auth_token (JWT access token) returned by /api/v1/users/signup or /api/v1/users/signin.

Authentication#

PufferBlow uses access + refresh token sessions.

  • Access token: short-lived JWT used for API calls.

  • Refresh token: long-lived token used to rotate session tokens.

  • Tokens are instance-bound via origin_server claims.

Most endpoints still accept auth_token in query params or request body. For clients that send Authorization: Bearer headers, normalize to the same token value before calling routes.

Token Refresh Endpoints#

POST /api/v1/auth/refresh

Rotate refresh token and issue a new access/refresh pair.

Request Body:

{
  "refresh_token": "..."
}

POST /api/v1/auth/revoke

Revoke refresh token (logout session).

Request Body:

{
  "refresh_token": "..."
}

Decentralized Node Auth Endpoints#

These endpoints are used for node-bound delegated sessions:

  • POST /api/v1/auth/decentralized/challenge

  • POST /api/v1/auth/decentralized/verify

  • POST /api/v1/auth/decentralized/introspect

  • POST /api/v1/auth/decentralized/revoke

General auth token placement patterns:

  1. Query Parameter: ?auth_token=your_token_here

  2. Header: Authorization: Bearer your_token_here

  3. Request Body: Include auth_token field in JSON payload

User Routes#

These endpoints handle user authentication, account management, and profile operations.

GET /api/v1/users/signin

Sign in to an existing account.

Query Parameters:

Parameter

Type

Description

username

string

Account username

password

string

Account password

Response (200 OK):

{
  "status_code": 200,
  "message": "Signin successfully",
  "auth_token": "eyJhbGciOi...",
  "refresh_token": "eyJ1aWQiOi...",
  "token_type": "Bearer",
  "auth_token_expire_time": "2026-02-21T10:00:00+00:00",
  "refresh_token_expire_time": "2026-03-22T10:00:00+00:00"
}

POST /api/v1/users/signup

Create a new user account.

Request Body:

{
  "username": "johndoe",
  "password": "mySecurePassword123!"
}

Response (201 Created):

{
  "status_code": 201,
  "message": "Account created successfully",
  "auth_token": "eyJhbGciOi...",
  "refresh_token": "eyJ1aWQiOi...",
  "token_type": "Bearer",
  "auth_token_expire_time": "2026-02-21T10:00:00+00:00",
  "refresh_token_expire_time": "2026-03-22T10:00:00+00:00"
}

POST /api/v1/users/profile

Get current user’s profile information. Also supports fetching other users’ public profiles.

Request Body:

{
  "auth_token": "your_auth_token",
  "user_id": "optional_other_user_id"
}

PUT /api/v1/users/profile

Update user profile information. Supports username, status, password, and about section updates.

Query Parameters:

Parameter

Type

Description

auth_token

string

User’s authentication token

new_username

string

Optional new username

status

string

New status message

new_password

string

New password (requires old_password)

old_password

string

Current password (for password changes)

about

string

New about/bio text

POST /api/v1/users/profile/reset-auth-token

Reset authentication token (requires password verification).

Request Body:

{
  "auth_token": "current_token",
  "password": "current_password"
}

POST /api/v1/users/profile/avatar

Upload user avatar image.

Form Data:

Field

Type

Description

auth_token

string

User’s authentication token

file

file

Image file (PNG, JPEG, GIF)

POST /api/v1/users/profile/banner

Upload user banner image (same format as avatar).

Channel Routes#

These endpoints handle channel management, messaging, and message operations.

GET /api/v1/channels

Get information about the channels endpoint.

POST /api/v1/channels/list/

List all available channels (excludes private channels unless user has access).

Request Body:

{
  "auth_token": "your_auth_token"
}

POST /api/v1/channels/create/

Create a new channel. Only server admins or owners can create channels.

Request Body:

{
  "auth_token": "admin_token",
  "channel_name": "gaming-discussion",
  "is_private": false
}

DELETE /api/v1/channels/{channel_id}/delete

Delete a channel. Only admins/owners can delete channels.

PUT /api/v1/channels/{channel_id}/add_user

Add user to private channel. Admin/owner only.

URL Parameters:

Parameter

Type

Description

channel_id

string

Target channel

Query Parameters:

Parameter

Type

Description

auth_token

string

Admin authentication token

to_add_user_id

string

User to add to channel

Response (200 OK):

{
  "status_code": 200,
  "message": "User ID: 'user_123' added to Channel ID: 'channel_456'"
}

DELETE /api/v1/channels/{channel_id}/remove_user

Remove user from private channel. Admin/owner only.

URL Parameters:

Parameter

Type

Description

channel_id

string

Target channel

Query Parameters:

Response (200 OK):

{
  "status_code": 200,
  "message": "User ID: 'user_123' removed from Channel ID: 'channel_456'"
}

GET /api/v1/channels/{channel_id}/load_messages

Load paginated messages from a channel.

URL Parameters:

Parameter

Type

Description

channel_id

string

Channel to load messages from

Query Parameters:

Response (200 OK):

{
  "status_code": 200,
  "messages": [
    {
      "message_id": "msg_123",
      "sender_user_id": "user_456",
      "channel_id": "channel_789",
      "message": "Hello everyone!",
      "hashed_message": "a1b2c3d4...",
      "username": "johndoe",
      "sent_at": "2025-10-18T07:00:00Z",
      "attachments": ["/api/v1/cdn/file/upload_image.jpg"]
    }
  ]
}

POST /api/v1/channels/{channel_id}/send_message

Send a message to a channel. Supports text and file attachments.

URL Parameters:

Parameter

Type

Description

channel_id

string

Channel to send message to

Form Data:

Field

Type

Description

auth_token

string

User authentication token

message

string

Message text (optional with attachments)

attachments

file(s)

File attachments (optional)

Response (201 Created):

{
  "status_code": 201,
  "message": "message sent successfully",
  "message_id": "msg_456",
  "attachments": ["/api/v1/cdn/file/upload_file.jpg"]
}

PUT /api/v1/channels/{channel_id}/mark_message_as_read

Mark a message as read for the current user.

URL Parameters:

Parameter

Type

Description

channel_id

string

Channel containing the message

Query Parameters:

Parameter

Type

Description

auth_token

string

User authentication token

message_id

string

Message to mark as read

Response (201 Created):

{
  "status_code": 201,
  "message": "The message_id was successfully marked as read"
}

DELETE /api/v1/channels/{channel_id}/delete_message

Delete a message from channel. User can delete own messages, admins can delete any.

URL Parameters:

Parameter

Type

Description

channel_id

string

Channel containing the message

Query Parameters:

Parameter

Type

Description

auth_token

string

User authentication token

message_id

string

Message to delete

Response (204 No Content):

{
  "status_code": 204,
  "message": "The message has been deleted successfully"
}

Voice Channel Routes#

Voice endpoints are attached to channel IDs and use WebRTC/aiortc:

  • POST /api/v1/channels/{channel_id}/join-audio

  • POST /api/v1/channels/{channel_id}/leave-audio

  • GET /api/v1/channels/{channel_id}/audio-status

Federation and Direct Message Routes#

These endpoints provide ActivityPub interop and local/remote direct messaging:

  • GET /.well-known/webfinger

  • GET /ap/users/{user_id}

  • GET /ap/users/{user_id}/outbox

  • POST /ap/users/{user_id}/inbox

  • POST /ap/inbox

  • POST /api/v1/federation/follow

  • POST /api/v1/dms/send

  • GET /api/v1/dms/messages

File Management (Storage/CDN) Routes#

These endpoints handle file uploads, downloads, and CDN management. Most require server owner privileges.

POST /api/v1/storage/upload

Upload file to storage. Server owner only.

POST /api/v1/storage/files

List files in storage directory. Server owner only.

POST /api/v1/storage/file-info

Get detailed file information. Server owner only.

POST /api/v1/storage/delete-file

Delete file from storage. Server owner only.

GET /api/v1/cdn/file/{file_path}

Serve CDN-compatible file path.

GET /api/v1/storage/file/{file_path}

Serve storage file path.

POST /api/v1/storage/cleanup-orphaned

Clean up orphaned stored files. Server owner only.

Server Administration Routes#

These endpoints are only available to server owners and administrators for managing server configuration, security, and settings.

POST /api/v1/blocked-ips/list

List blocked IP addresses.

POST /api/v1/blocked-ips/block

Block an IP address.

POST /api/v1/blocked-ips/unblock

Unblock an IP address.

GET /api/v1/system/server-info

Get server configuration information.

GET /api/v1/system/server-stats

Get server statistics and metrics.

POST /api/v1/system/server-usage

Get real-time server resource usage.

PUT /api/v1/system/server-info

Update server configuration. Server owner only.

POST /api/v1/system/upload-avatar

Upload server avatar. Server owner only.

POST /api/v1/system/upload-banner

Upload server banner. Server owner only.

Analytics & Activity Routes#

These endpoints provide charts, metrics, and activity monitoring for server administrators.

POST /api/v1/system/charts/user-registrations

Get user registration chart data.

POST /api/v1/system/charts/message-activity

Get message activity chart data.

POST /api/v1/system/charts/online-users

Get online users chart data.

POST /api/v1/system/charts/channel-creation

Get channel creation chart data.

POST /api/v1/system/charts/user-status

Get user status distribution chart data.

POST /api/v1/system/recent-activity

Get recent server activity events. Admin only.

POST /api/v1/system/activity-metrics

Get current activity metrics. Admin only.

POST /api/v1/system/server-overview

Get comprehensive server overview. Admin only.

Background Tasks Routes#

These endpoints manage background tasks and automated server operations.

POST /api/v1/background-tasks/status

Get status of all background tasks.

POST /api/v1/background-tasks/run

Execute a background task on-demand.

General Routes#

Miscellaneous endpoints for general server information.

GET /api/v1/info

Get basic server information.

GET /api/v1/system/latest-release

Get information about the latest PufferBlow release.

WebSocket Routes#

PufferBlow uses WebSockets for real-time messaging.

WebSocket Endpoints:

  • ws://your-server:7575/ws (global stream for all accessible channels)

  • ws://your-server:7575/ws/channels/{channel_id} (channel-scoped stream)

Connection Parameters:

Parameter

Type

Description

channel_id

string

Channel to connect to (channel endpoint only)

auth_token

string

User authentication token (as query parameter)

Incoming Messages (Server -> Client):

{
  "message_id": "msg_123",
  "sender_user_id": "user_456",
  "channel_id": "channel_789",
  "message": "Hello everyone!",
  "username": "johndoe",
  "sent_at": "2025-10-18T07:00:00Z",
  "attachments": ["/api/v1/cdn/file/image.jpg"]
}

Outgoing Messages (Client -> Server):

{
  "type": "read_confirmation",
  "message_id": "msg_123"
}

Error Responses#

All API endpoints may return error responses in the following format:

400 Bad Request: .. sourcecode:: json

{“detail”: “Error description”}

401 Unauthorized: .. sourcecode:: json

{“detail”: “Authentication required”}

403 Forbidden: .. sourcecode:: json

{“detail”: “Access forbidden”}

404 Not Found: .. sourcecode:: json

{“detail”: “Resource not found”}

409 Conflict: .. sourcecode:: json

{“detail”: “Resource conflict”}

500 Internal Server Error: .. sourcecode:: json

{“detail”: “Internal server error”}

Rate Limiting#

The API uses a sliding-window rate limiter with endpoint buckets:

  • auth endpoints (stricter)

  • uploads endpoints

  • messages endpoints

  • default endpoints

Rate limit headers are included in responses:

Final thresholds are derived from server settings (server_settings table) and can trigger cooldowns and eventual automatic IP blocking.

Development Tips#

API Base URL: http://your-server:7575/api/v1

Debug Mode: Add ?debug=1 to see additional error information

API Documentation: Visit http://your-server:7575/docs for interactive OpenAPI documentation

Testing: Use tools like curl, Postman, or HTTPie for testing endpoints

# Example API call
curl -X POST http://localhost:7575/api/v1/users/signin \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test"}'
Table of content