Skip to content

Wellesley Platform API (1.0)

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server
https://docs.wellesley.social/_mock/openapi/
Simple setup, all in one. Digital Ocean
https://dust.allroads.social/
Simple setup, db is separate. Digital Ocean
https://meteor.allroads.social/

AI Agents

Assign and list group AI agent assignments

Operations

Accounts

Account management and authentication endpoints. Handles user registration, login flows (email/phone), profile management, and account lifecycle operations. Supports multi-step signup with email/SMS verification, CAPTCHA, and optional admin approval.

Operations

ActivityPub

WebFinger endpoint for ActivityPub user discovery and federation

Addresses

Endpoints for suggesting and validating physical addresses

Operations

Admin

Development and testing endpoints for populating the database with test data

Admin Accounts

Administrative endpoints for account and user management. Provides comprehensive tools for managing user accounts, including creation, deletion, role assignment, password management, state changes, and user impersonation for bot accounts.

Operations

Admin ActivityPub

Administrative endpoints for ActivityPub

Operations

Admin Audit

Administrative endpoints for viewing and managing audit logs. Provides comprehensive logging of all security-relevant actions performed in the system.

Operations

Admin Domain Blocks

Administrative APIs for managing domain blocks. Provides endpoints to block specific domains with different severity levels (SUSPEND, LIMIT, NOOP), update existing blocks, unblock domains, and list currently blocked domains. Domain blocks prevent or limit federation with specified domains.

Operations

Admin Domains Allow List

Administrative endpoints for managing domain allowlists. When domain allowlisting is enabled, only domains in this list can federate with the instance.

Operations

Admin Email Allow List

Administrative endpoints for managing email domain allowlist used for registrations.

Operations

Admin Email Blocks

Administrative APIs for managing email blocks to prevent unwanted signups. Supports blocking specific email addresses and entire domains. Email blocks are automatically normalized and checked during user registration.

Operations

Admin Federation Metrics

Administrative endpoints for monitoring and managing federation with other ActivityPub instances. Provides metrics on connected domains, user counts, post statistics, and federation health monitoring.

Operations

Admin Feeds

Administrative endpoints for managing user feeds and cache

Operations

Admin Groups

Administrative endpoints for Groups management

Operations

Admin Init

Administration endpoints for system initialization and updates

Admin Posts

Administrative endpoints for managing posts. Provides moderation capabilities to delete posts that violate community guidelines or are part of reported content.

Operations

Admin Reports

Administrative endpoints for managing user reports and moderation. Provides tools for reviewing, assigning, resolving, and annotating reports about users, posts, and groups. Supports workflow management with assignment, notes, and resolution tracking.

Operations

Admin Signup Requests

Administrative endpoints for managing user signup requests. Provides tools for reviewing, approving, rejecting, and managing signup requests in moderation queue. Supports workflow for manual account approval when enabled.

Operations

Admin Uploads

Administrative endpoints for managing file uploads and media storage. Provides tools for monitoring user storage usage, searching uploaded files, and managing upload processing jobs. Supports queue management for async upload processing workflows.

Operations

Aliases

Endpoints for managing previous usernames and username aliases

Operations

Application Data

Endpoints for managing application-specific data storage. Provides a flexible key-value storage system for applications to store custom data associated with users, groups, or the platform. Supports tagging, filtering, and ownership-based access control.

Operations

Applications

Endpoints for serving and routing platform applications to users

Operations

Blocks

User blocking functionality for preventing interaction with specific users. Blocking a user prevents them from following you, seeing your posts, or interacting with your content. Block operations are federated to remote servers when blocking remote users.

Operations

Categories

Endpoints for managing forum-specific categories

Operations

Domain Blocks

Public API for listing domains blocked by this instance. Visibility and reason details are controlled by platform settings.

Operations

Domain-blocks

Endpoints for managing user-level domain blocks to filter content from specific servers

Operations

Drafts

Endpoints for creating, reading, updating, and deleting drafts, as well as publishing them to posts

Operations

Email

Email address management for user accounts. Provides secure email change workflow with verification codes, password confirmation, and notification system. All email changes require authentication and are logged for security.

Operations

Emoji

Custom emoji management system for the platform. Supports creating, uploading, importing/exporting, searching, and deleting custom emojis. Emojis are automatically resized and optimized. Admin-only operations require Emojis.Manage permission.

Operations

Events

Endpoints for creating, retrieving, and managing events and attendees

Operations

Events ActivityPub

ActivityPub-compatible endpoint for events

Follow

User follow relationship management. Handles following/unfollowing users, managing follow requests, and querying follower/followee relationships. Supports both local and remote (federated) users with ActivityPub protocol integration.

Operations

Forums

Endpoints for managing discussion forums, including creation, retrieval, and deletion

Operations

Geo

Endpoints for geographic location lookup and timezone services

Operations

Group Applications

Endpoints for managing applications available to groups, including listing, adding, and removing group-specific applications

Operations

Group Channels

API endpoints for managing channels within groups. Channels are specialized accounts that enable organized content distribution within groups. They support hierarchical organization with main and default channels, privacy controls inherited from parent groups, and both scoped (group-specific) and global usernames for discovery. Group administrators manage channels while members can follow them.

Operations

List all group channels

Request

Retrieves a complete list of all channels within the specified group. Requires group membership to access. Returns both public and private channels visible to the authenticated user. The response includes channel metadata such as privacy settings, default status, and whether each channel is designated as the main channel. Channels are returned in creation order.

RBAC: requires GroupChannels.Read

Path
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
curl -i -X GET \
  https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels

Responses

Complete list of group channels successfully retrieved

Bodyapplication/jsonArray [
groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
avatarobject or null

User's avatar

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

channelboolean

Whether this is a channel or a user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
]
Response
application/json
[
  {
    "groupUserName": "string",
    "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
    "username": "john_smith",
    "domain": "wlsly1.net",
    "displayName": "John Smith",
    "uri": "https://wlsly1.net/users/john_smith",
    "avatar": { … },
    "createdAt": "2022-03-10T16:15:50Z",
    "deleted": true,
    "state": "REGULAR",
    "relationship": { … },
    "channel": true,
    "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
    "groupPrivacy": "PUBLIC",
    "groupMain": true,
    "groupDefault": true,
    "actorType": "Application"
  }
]

Create a new group channel

Request

Creates a new channel within the specified group. Requires group administrator privileges. The channel's privacy is constrained by the parent group's privacy settings (private groups can only have private channels). The first channel created is automatically designated as both main and default. Channels can have both scoped usernames (group-specific) and optional global usernames (platform-wide). Note: Avatar and header images must be set via the update endpoint after channel creation.

RBAC: requires GroupChannels.Manage

Path
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
Query
htmlContentany

Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.

Bodyapplication/jsonrequired
usernamestring\Srequired

Channel identifier scoped to the group. Must be unique within the group. Used to generate the channel's username in format 'groupname:channelname' for private channels.

Example: "news"
displayNamestring\Srequired

Human-readable display name for the channel. Shown in channel listings and UI.

Example: "Group News"
summarystring<= 1024 charactersrequired

Brief description of the channel's purpose and content (max 1024 characters)

Example: "Read group news and announcements here"
privacystringrequired
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
Example: "PUBLIC"
isMainboolean

Whether this channel should be the main channel for the group. Only one main channel allowed per group. The first channel created is automatically made main.

Default false
Example: false
isDefaultboolean

Whether this channel should be a default channel. Default channels are automatically followed by new group members. The first channel created is automatically made default.

Default false
Example: true
globalUsernamestring or null

Global username for public channels. Must be unique across the entire platform. Allows the channel to be accessed via '@globalUsername' in addition to the scoped username. Only available for public channels in public groups.

Example: "platform-news"
curl -i -X POST \
  https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "news",
    "displayName": "Group News",
    "summary": "Read group news and announcements here",
    "privacy": "PUBLIC",
    "isMain": false,
    "isDefault": true,
    "globalUsername": "platform-news"
  }'

Responses

Channel created successfully with all configured properties

Bodyapplication/json
groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
summarystringrequired

User's summary or bio

Example: "Pixels are my paint, code is my canvas, creativity is my brush."
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
statsobjectrequired

User stats

stats.​postsinteger(int32)required

number of posts

stats.​followersinteger(int32)required

number of followers

stats.​followinginteger(int32)required

number of following

stats.​followingHiddenbooleanrequired

privacy setting to hide followings

stats.​totalStorageBytesinteger(int64)required

total storage volume in bytes

stats.​commentsinteger(int32)required

number of comments

fieldsobjectrequired

User fields

fields.​property name*object(UserField)additional property
avatarobject or null

User's avatar

headerobject or null

User's header

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

emojisArray of objects or null(Emoji)
locationobject or null

User's location, geo and name

timezoneobject or null

User's timezone

birthdayobject or null

User's birthday

softwarestringrequired

Software platform type (wellesley, mastodon, threads.net)

Example: "wellesley"
channelboolean

is channel user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
Response
application/json
{
  "groupUserName": "string",
  "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "username": "john_smith",
  "domain": "wlsly1.net",
  "displayName": "John Smith",
  "summary": "Pixels are my paint, code is my canvas, creativity is my brush.",
  "uri": "https://wlsly1.net/users/john_smith",
  "stats": {
    "posts": 0,
    "followers": 0,
    "following": 0,
    "followingHidden": true,
    "totalStorageBytes": 0,
    "comments": 0
  },
  "fields": {
    "property1": { … },
    "property2": { … }
  },
  "avatar": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "header": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "createdAt": "2022-03-10T16:15:50Z",
  "deleted": true,
  "state": "REGULAR",
  "relationship": {
    "following": "PENDING",
    "followed": "PENDING",
    "blocked": true,
    "blockedBy": true,
    "muted": { … },
    "note": "string"
  },
  "emojis": [
    { … }
  ],
  "location": {
    "geo": { … },
    "name": "string",
    "autoUpdate": true,
    "show": true
  },
  "timezone": {
    "ianaTimezone": "string",
    "autoUpdate": true,
    "show": true
  },
  "birthday": {
    "date": "2022-03-10T16:15:50Z",
    "show": "NONE"
  },
  "software": "wellesley",
  "channel": true,
  "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "groupPrivacy": "PUBLIC",
  "groupMain": true,
  "groupDefault": true,
  "actorType": "Application"
}

List default channels

Request

Retrieves all channels designated as default for the specified group. Default channels are automatically followed by new members upon joining. Requires group membership to access. Returns an empty array if no default channels are configured. The response includes full channel information including privacy settings and follow status.

RBAC: requires GroupChannels.Read

Path
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
curl -i -X GET \
  https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/default

Responses

List of default channels successfully retrieved

Bodyapplication/jsonArray [
groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
avatarobject or null

User's avatar

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

channelboolean

Whether this is a channel or a user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
]
Response
application/json
[
  {
    "groupUserName": "string",
    "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
    "username": "john_smith",
    "domain": "wlsly1.net",
    "displayName": "John Smith",
    "uri": "https://wlsly1.net/users/john_smith",
    "avatar": { … },
    "createdAt": "2022-03-10T16:15:50Z",
    "deleted": true,
    "state": "REGULAR",
    "relationship": { … },
    "channel": true,
    "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
    "groupPrivacy": "PUBLIC",
    "groupMain": true,
    "groupDefault": true,
    "actorType": "Application"
  }
]

Get group channel by scoped username

Request

Retrieves a channel using its group-scoped username (slug). Useful for accessing channels without global usernames. Private channels and channels inside private groups require membership and otherwise return 404.

Path
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
Query
fullboolean or null

If true return also summary, stats, header and fields. Default false.

usernamestring\Srequired

Channel slug unique within the group (e.g. "news").

htmlContentany

Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.

curl -i -X GET \
  'https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/lookup?full=true&username=string'

Responses

Channel information successfully retrieved

Bodyapplication/json
One of:

One of account's users. Can be multiple per account

groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
avatarobject or null

User's avatar

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

channelboolean

Whether this is a channel or a user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
Response
application/json
{
  "groupUserName": "string",
  "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "username": "john_smith",
  "domain": "wlsly1.net",
  "displayName": "John Smith",
  "uri": "https://wlsly1.net/users/john_smith",
  "avatar": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "createdAt": "2022-03-10T16:15:50Z",
  "deleted": true,
  "state": "REGULAR",
  "relationship": {
    "following": "PENDING",
    "followed": "PENDING",
    "blocked": true,
    "blockedBy": true,
    "muted": { … },
    "note": "string"
  },
  "channel": true,
  "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "groupPrivacy": "PUBLIC",
  "groupMain": true,
  "groupDefault": true,
  "actorType": "Application"
}

Retrieve main channel

Request

Retrieves the designated main channel for the specified group. Access control is based on both group and channel privacy settings. Public groups with public main channels are accessible to everyone. Private groups or private channels require group membership. Returns 404 if no main channel is designated or if access is denied due to privacy settings.

Path
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
Query
htmlContentany

Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.

curl -i -X GET \
  https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/main

Responses

Main channel information successfully retrieved

Bodyapplication/json
groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
summarystringrequired

User's summary or bio

Example: "Pixels are my paint, code is my canvas, creativity is my brush."
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
statsobjectrequired

User stats

stats.​postsinteger(int32)required

number of posts

stats.​followersinteger(int32)required

number of followers

stats.​followinginteger(int32)required

number of following

stats.​followingHiddenbooleanrequired

privacy setting to hide followings

stats.​totalStorageBytesinteger(int64)required

total storage volume in bytes

stats.​commentsinteger(int32)required

number of comments

fieldsobjectrequired

User fields

fields.​property name*object(UserField)additional property
avatarobject or null

User's avatar

headerobject or null

User's header

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

emojisArray of objects or null(Emoji)
locationobject or null

User's location, geo and name

timezoneobject or null

User's timezone

birthdayobject or null

User's birthday

softwarestringrequired

Software platform type (wellesley, mastodon, threads.net)

Example: "wellesley"
channelboolean

is channel user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
Response
application/json
{
  "groupUserName": "string",
  "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "username": "john_smith",
  "domain": "wlsly1.net",
  "displayName": "John Smith",
  "summary": "Pixels are my paint, code is my canvas, creativity is my brush.",
  "uri": "https://wlsly1.net/users/john_smith",
  "stats": {
    "posts": 0,
    "followers": 0,
    "following": 0,
    "followingHidden": true,
    "totalStorageBytes": 0,
    "comments": 0
  },
  "fields": {
    "property1": { … },
    "property2": { … }
  },
  "avatar": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "header": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "createdAt": "2022-03-10T16:15:50Z",
  "deleted": true,
  "state": "REGULAR",
  "relationship": {
    "following": "PENDING",
    "followed": "PENDING",
    "blocked": true,
    "blockedBy": true,
    "muted": { … },
    "note": "string"
  },
  "emojis": [
    { … }
  ],
  "location": {
    "geo": { … },
    "name": "string",
    "autoUpdate": true,
    "show": true
  },
  "timezone": {
    "ianaTimezone": "string",
    "autoUpdate": true,
    "show": true
  },
  "birthday": {
    "date": "2022-03-10T16:15:50Z",
    "show": "NONE"
  },
  "software": "wellesley",
  "channel": true,
  "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "groupPrivacy": "PUBLIC",
  "groupMain": true,
  "groupDefault": true,
  "actorType": "Application"
}

Check if channel username is already in use

Request

Used for inline validation during channel creation. Scoped to the group. Returns a result object indicating whether the username is taken within the specified group.

RBAC: requires GroupChannels.Manage

Path
channelUsernamestringrequired

The channel username (slug) to check for availability

groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
curl -i -X GET \
  'https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/namecheck/{channelUsername}'

Responses

Username availability check result

Bodyapplication/json
existsbooleanrequired

Whether the group name already exists in the database

Example: true
Response
application/json
{
  "exists": true
}

List public channels

Request

Retrieves all public channels from a public group. This endpoint is accessible to everyone, including non-members and unauthenticated users, but only works for public groups. Private groups will return an error regardless of their channels' privacy settings. Useful for discovery and browsing group content before joining. Channels with global usernames are included with their platform-wide identifiers.

Path
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
curl -i -X GET \
  https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/public

Responses

OK

Bodyapplication/jsonArray [
groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
avatarobject or null

User's avatar

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

channelboolean

Whether this is a channel or a user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
]
Response
application/json
[
  {
    "groupUserName": "string",
    "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
    "username": "john_smith",
    "domain": "wlsly1.net",
    "displayName": "John Smith",
    "uri": "https://wlsly1.net/users/john_smith",
    "avatar": { … },
    "createdAt": "2022-03-10T16:15:50Z",
    "deleted": true,
    "state": "REGULAR",
    "relationship": { … },
    "channel": true,
    "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
    "groupPrivacy": "PUBLIC",
    "groupMain": true,
    "groupDefault": true,
    "actorType": "Application"
  }
]

Update an existing group channel

Request

Modifies properties of an existing channel. Requires group administrator privileges. Only included fields are updated; null fields preserve existing values. Privacy changes are constrained by the parent group's privacy (cannot make a channel public in a private group). Changes to default status affect auto-follow behavior for new members.

RBAC: requires GroupChannels.Manage

Path
channelIdstring(TypeId)required

UUID with type prefix

Example: us_01hxcvk1hjexere4pvtrj0ymqq
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
Query
htmlContentany

Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.

Bodyapplication/jsonrequired
displayNamestring or null

New display name for the channel. Updates how the channel appears in UI.

Example: "Group Announcements"
summarystring or null<= 1024 characters

New channel description (max 1024 characters)

Example: "Important announcements and updates"
privacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
Example: "PRIVATE"
isDefaultboolean or null

Whether this channel should be a default channel (auto-followed by new members)

Example: true
avatarIdstring or null

Upload ID for the channel avatar image. Must be a previously uploaded image. Set to null to remove the avatar.

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
headerIdstring or null

Upload ID for the channel header/banner image. Must be a previously uploaded image. Set to null to remove the header.

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
fieldsobject or null

Channel profile fields (key-value pairs for additional information)

locationobject or null

Channel location information

timezoneobject or null

Channel timezone preferences

curl -i -X PUT \
  https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/us_01hxcvk1hjexere4pvtrj0ymqq \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "Group Announcements",
    "summary": "Important announcements and updates",
    "privacy": "PRIVATE",
    "isDefault": true,
    "avatarId": "us_01hxcvk1hjexere4pvtrj0ymqq",
    "headerId": "us_01hxcvk1hjexere4pvtrj0ymqq",
    "fields": {
      "property1": {
        "value": "string",
        "verifiedAt": "2022-03-10T16:15:50Z"
      },
      "property2": {
        "value": "string",
        "verifiedAt": "2022-03-10T16:15:50Z"
      }
    },
    "location": {
      "geo": {
        "latitude": 0.1,
        "longitude": 0.1,
        "altitude": 0.1,
        "accuracy": 0.1,
        "verticalAccuracy": 0.1,
        "speed": 0.1,
        "bearing": 0.1,
        "timestamp": 0
      },
      "name": "string",
      "autoUpdate": true,
      "show": true
    },
    "timezone": {
      "ianaTimezone": "string",
      "autoUpdate": true,
      "show": true
    }
  }'

Responses

Channel properties updated successfully

Bodyapplication/json
groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
summarystringrequired

User's summary or bio

Example: "Pixels are my paint, code is my canvas, creativity is my brush."
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
statsobjectrequired

User stats

stats.​postsinteger(int32)required

number of posts

stats.​followersinteger(int32)required

number of followers

stats.​followinginteger(int32)required

number of following

stats.​followingHiddenbooleanrequired

privacy setting to hide followings

stats.​totalStorageBytesinteger(int64)required

total storage volume in bytes

stats.​commentsinteger(int32)required

number of comments

fieldsobjectrequired

User fields

fields.​property name*object(UserField)additional property
avatarobject or null

User's avatar

headerobject or null

User's header

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

emojisArray of objects or null(Emoji)
locationobject or null

User's location, geo and name

timezoneobject or null

User's timezone

birthdayobject or null

User's birthday

softwarestringrequired

Software platform type (wellesley, mastodon, threads.net)

Example: "wellesley"
channelboolean

is channel user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
Response
application/json
{
  "groupUserName": "string",
  "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "username": "john_smith",
  "domain": "wlsly1.net",
  "displayName": "John Smith",
  "summary": "Pixels are my paint, code is my canvas, creativity is my brush.",
  "uri": "https://wlsly1.net/users/john_smith",
  "stats": {
    "posts": 0,
    "followers": 0,
    "following": 0,
    "followingHidden": true,
    "totalStorageBytes": 0,
    "comments": 0
  },
  "fields": {
    "property1": { … },
    "property2": { … }
  },
  "avatar": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "header": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "createdAt": "2022-03-10T16:15:50Z",
  "deleted": true,
  "state": "REGULAR",
  "relationship": {
    "following": "PENDING",
    "followed": "PENDING",
    "blocked": true,
    "blockedBy": true,
    "muted": { … },
    "note": "string"
  },
  "emojis": [
    { … }
  ],
  "location": {
    "geo": { … },
    "name": "string",
    "autoUpdate": true,
    "show": true
  },
  "timezone": {
    "ianaTimezone": "string",
    "autoUpdate": true,
    "show": true
  },
  "birthday": {
    "date": "2022-03-10T16:15:50Z",
    "show": "NONE"
  },
  "software": "wellesley",
  "channel": true,
  "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "groupPrivacy": "PUBLIC",
  "groupMain": true,
  "groupDefault": true,
  "actorType": "Application"
}

Get group channel by id

Request

Retrieves a channel within the current group by its identifier. Access to private channels (or channels in private groups) is restricted to group members; outsiders receive a 404.

Path
channelIdstring(TypeId)required

UUID with type prefix

Example: us_01hxcvk1hjexere4pvtrj0ymqq
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
Query
fullboolean or null

If true return also summary, stats, header and fields. Default false.

htmlContentany

Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.

curl -i -X GET \
  'https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/us_01hxcvk1hjexere4pvtrj0ymqq?full=true'

Responses

Channel information successfully retrieved

Bodyapplication/json
One of:

One of account's users. Can be multiple per account

groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
avatarobject or null

User's avatar

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

channelboolean

Whether this is a channel or a user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
Response
application/json
{
  "groupUserName": "string",
  "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "username": "john_smith",
  "domain": "wlsly1.net",
  "displayName": "John Smith",
  "uri": "https://wlsly1.net/users/john_smith",
  "avatar": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "createdAt": "2022-03-10T16:15:50Z",
  "deleted": true,
  "state": "REGULAR",
  "relationship": {
    "following": "PENDING",
    "followed": "PENDING",
    "blocked": true,
    "blockedBy": true,
    "muted": { … },
    "note": "string"
  },
  "channel": true,
  "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "groupPrivacy": "PUBLIC",
  "groupMain": true,
  "groupDefault": true,
  "actorType": "Application"
}

Delete a group channel

Request

Removes the specified channel from the group. Requires group administrator privileges. The channel is marked as deleted immediately and background workers handle cleanup of posts, media, and follower relationships.

RBAC: requires GroupChannels.Manage

Path
channelIdstring(TypeId)required

UUID with type prefix

Example: us_01hxcvk1hjexere4pvtrj0ymqq
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
curl -i -X DELETE \
  https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/us_01hxcvk1hjexere4pvtrj0ymqq

Responses

OK

Bodyapplication/json
any
Response
application/json
null

Update channel default status

Request

Toggles whether a channel is designated as a default channel. Requires group administrator privileges. Default channels are automatically followed by new group members upon joining. Multiple channels can be marked as default. This setting helps onboard new members by ensuring they receive content from essential channels immediately.

RBAC: requires GroupChannels.Manage

Path
channelIdstring(TypeId)required

UUID with type prefix

Example: us_01hxcvk1hjexere4pvtrj0ymqq
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
Query
isDefaultboolean

Whether to mark the channel as default (true) or remove default status (false)

Default true
htmlContentany

Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.

curl -i -X PUT \
  'https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/us_01hxcvk1hjexere4pvtrj0ymqq/default?isDefault=true'

Responses

Default channel status successfully updated

Bodyapplication/json
groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
summarystringrequired

User's summary or bio

Example: "Pixels are my paint, code is my canvas, creativity is my brush."
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
statsobjectrequired

User stats

stats.​postsinteger(int32)required

number of posts

stats.​followersinteger(int32)required

number of followers

stats.​followinginteger(int32)required

number of following

stats.​followingHiddenbooleanrequired

privacy setting to hide followings

stats.​totalStorageBytesinteger(int64)required

total storage volume in bytes

stats.​commentsinteger(int32)required

number of comments

fieldsobjectrequired

User fields

fields.​property name*object(UserField)additional property
avatarobject or null

User's avatar

headerobject or null

User's header

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

emojisArray of objects or null(Emoji)
locationobject or null

User's location, geo and name

timezoneobject or null

User's timezone

birthdayobject or null

User's birthday

softwarestringrequired

Software platform type (wellesley, mastodon, threads.net)

Example: "wellesley"
channelboolean

is channel user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
Response
application/json
{
  "groupUserName": "string",
  "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "username": "john_smith",
  "domain": "wlsly1.net",
  "displayName": "John Smith",
  "summary": "Pixels are my paint, code is my canvas, creativity is my brush.",
  "uri": "https://wlsly1.net/users/john_smith",
  "stats": {
    "posts": 0,
    "followers": 0,
    "following": 0,
    "followingHidden": true,
    "totalStorageBytes": 0,
    "comments": 0
  },
  "fields": {
    "property1": { … },
    "property2": { … }
  },
  "avatar": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "header": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "createdAt": "2022-03-10T16:15:50Z",
  "deleted": true,
  "state": "REGULAR",
  "relationship": {
    "following": "PENDING",
    "followed": "PENDING",
    "blocked": true,
    "blockedBy": true,
    "muted": { … },
    "note": "string"
  },
  "emojis": [
    { … }
  ],
  "location": {
    "geo": { … },
    "name": "string",
    "autoUpdate": true,
    "show": true
  },
  "timezone": {
    "ianaTimezone": "string",
    "autoUpdate": true,
    "show": true
  },
  "birthday": {
    "date": "2022-03-10T16:15:50Z",
    "show": "NONE"
  },
  "software": "wellesley",
  "channel": true,
  "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "groupPrivacy": "PUBLIC",
  "groupMain": true,
  "groupDefault": true,
  "actorType": "Application"
}

Designate channel as main

Request

Sets the specified channel as the main channel for the group. Requires group administrator privileges. Only one channel can be designated as main per group. The main channel serves as the primary communication channel and is prominently displayed in group interfaces. Any existing main channel designation is automatically removed.

RBAC: requires GroupChannels.Manage

Path
channelIdstring(TypeId)required

UUID with type prefix

Example: us_01hxcvk1hjexere4pvtrj0ymqq
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
Query
htmlContentany

Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.

curl -i -X PUT \
  https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/us_01hxcvk1hjexere4pvtrj0ymqq/main

Responses

Channel successfully designated as main, previous main channel designation removed

Bodyapplication/json
groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
summarystringrequired

User's summary or bio

Example: "Pixels are my paint, code is my canvas, creativity is my brush."
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
statsobjectrequired

User stats

stats.​postsinteger(int32)required

number of posts

stats.​followersinteger(int32)required

number of followers

stats.​followinginteger(int32)required

number of following

stats.​followingHiddenbooleanrequired

privacy setting to hide followings

stats.​totalStorageBytesinteger(int64)required

total storage volume in bytes

stats.​commentsinteger(int32)required

number of comments

fieldsobjectrequired

User fields

fields.​property name*object(UserField)additional property
avatarobject or null

User's avatar

headerobject or null

User's header

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

emojisArray of objects or null(Emoji)
locationobject or null

User's location, geo and name

timezoneobject or null

User's timezone

birthdayobject or null

User's birthday

softwarestringrequired

Software platform type (wellesley, mastodon, threads.net)

Example: "wellesley"
channelboolean

is channel user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
Response
application/json
{
  "groupUserName": "string",
  "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "username": "john_smith",
  "domain": "wlsly1.net",
  "displayName": "John Smith",
  "summary": "Pixels are my paint, code is my canvas, creativity is my brush.",
  "uri": "https://wlsly1.net/users/john_smith",
  "stats": {
    "posts": 0,
    "followers": 0,
    "following": 0,
    "followingHidden": true,
    "totalStorageBytes": 0,
    "comments": 0
  },
  "fields": {
    "property1": { … },
    "property2": { … }
  },
  "avatar": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "header": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "createdAt": "2022-03-10T16:15:50Z",
  "deleted": true,
  "state": "REGULAR",
  "relationship": {
    "following": "PENDING",
    "followed": "PENDING",
    "blocked": true,
    "blockedBy": true,
    "muted": { … },
    "note": "string"
  },
  "emojis": [
    { … }
  ],
  "location": {
    "geo": { … },
    "name": "string",
    "autoUpdate": true,
    "show": true
  },
  "timezone": {
    "ianaTimezone": "string",
    "autoUpdate": true,
    "show": true
  },
  "birthday": {
    "date": "2022-03-10T16:15:50Z",
    "show": "NONE"
  },
  "software": "wellesley",
  "channel": true,
  "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "groupPrivacy": "PUBLIC",
  "groupMain": true,
  "groupDefault": true,
  "actorType": "Application"
}

Assign or update global username

Request

Assigns, updates, or removes a global username for a public channel. Requires group administrator privileges. Global usernames provide platform-wide discovery and must be unique across the entire system. Only public channels in public groups can have global usernames. Setting the username to null removes any existing global username assignment.

RBAC: requires GroupChannels.Manage

Path
channelIdstring(TypeId)required

UUID with type prefix

Example: us_01hxcvk1hjexere4pvtrj0ymqq
groupIdstring(TypeId)required

The unique identifier of the group

Example: gr_01hz1f0kw36f82k9s4nzpc4s33n
Query
htmlContentany

Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.

Bodyapplication/jsonrequired
globalUsernamestring or nullrequired

Global username to assign to the channel. Must be unique platform-wide. Set to null to remove the global username. Only available for public channels in public groups.

Example: "platform-updates"
curl -i -X PUT \
  https://docs.wellesley.social/_mock/openapi/api/v1/groups/gr_01hz1f0kw36f82k9s4nzpc4s33n/channels/us_01hxcvk1hjexere4pvtrj0ymqq/username \
  -H 'Content-Type: application/json' \
  -d '{
    "globalUsername": "platform-updates"
  }'

Responses

OK

Bodyapplication/json
groupUserNamestring or null

Name of the channel inside a group

idstringrequired

internal id of this user

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
usernamestringrequired

unique user name

Example: "john_smith"
domainstringrequired

user's domain, remote only, empty for local

Example: "wlsly1.net"
displayNamestringrequired

full name of the user

Example: "John Smith"
summarystringrequired

User's summary or bio

Example: "Pixels are my paint, code is my canvas, creativity is my brush."
uristring(uri)required

URI of this user

Example: "https://wlsly1.net/users/john_smith"
statsobjectrequired

User stats

stats.​postsinteger(int32)required

number of posts

stats.​followersinteger(int32)required

number of followers

stats.​followinginteger(int32)required

number of following

stats.​followingHiddenbooleanrequired

privacy setting to hide followings

stats.​totalStorageBytesinteger(int64)required

total storage volume in bytes

stats.​commentsinteger(int32)required

number of comments

fieldsobjectrequired

User fields

fields.​property name*object(UserField)additional property
avatarobject or null

User's avatar

headerobject or null

User's header

createdAtstring(date-time)(Instant)required
Example: "2022-03-10T16:15:50Z"
deletedboolean or null
statestringrequired

Registration mode:

  • REGULAR - just regular state
  • SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
  • LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
  • SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
Enum"REGULAR""SENSITIVE""LIMITED""SUSPENDED"
relationshipobject or null

Relationship with this user

emojisArray of objects or null(Emoji)
locationobject or null

User's location, geo and name

timezoneobject or null

User's timezone

birthdayobject or null

User's birthday

softwarestringrequired

Software platform type (wellesley, mastodon, threads.net)

Example: "wellesley"
channelboolean

is channel user

groupIdstring or null

UUID with type prefix

Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
groupPrivacystring or null
  • PUBLIC - Channel is visible to everyone and can be followed by anyone.
  • PRIVATE - Channel is visible only to group members and can only be followed by group members.
Enum"PUBLIC""PRIVATE"
groupMainboolean or null
groupDefaultboolean or null
actorTypestring or null

Types that an Actor can be assigned. Coincide with ActivityPub Actor types:

  • APPLICATION: Apps will have this type
  • GROUP: Interest Groups and Generic Groups wil have this type
  • ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
  • PERSON: Individual people will have this type
  • SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
Enum"Application""Group""Organization""Person""Service"
Response
application/json
{
  "groupUserName": "string",
  "id": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "username": "john_smith",
  "domain": "wlsly1.net",
  "displayName": "John Smith",
  "summary": "Pixels are my paint, code is my canvas, creativity is my brush.",
  "uri": "https://wlsly1.net/users/john_smith",
  "stats": {
    "posts": 0,
    "followers": 0,
    "following": 0,
    "followingHidden": true,
    "totalStorageBytes": 0,
    "comments": 0
  },
  "fields": {
    "property1": { … },
    "property2": { … }
  },
  "avatar": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "header": {
    "uploadId": "up_kjhwieuy2387928371",
    "userId": "us_97234khddqdkuhqwij",
    "uploadType": "video",
    "meta": { … },
    "size": 0,
    "files": [ … ],
    "tags": [ … ],
    "error": "string",
    "cached": true,
    "logs": "string",
    "remote": true,
    "createdAt": "2022-03-10T16:15:50Z",
    "updatedAt": "2022-03-10T16:15:50Z"
  },
  "createdAt": "2022-03-10T16:15:50Z",
  "deleted": true,
  "state": "REGULAR",
  "relationship": {
    "following": "PENDING",
    "followed": "PENDING",
    "blocked": true,
    "blockedBy": true,
    "muted": { … },
    "note": "string"
  },
  "emojis": [
    { … }
  ],
  "location": {
    "geo": { … },
    "name": "string",
    "autoUpdate": true,
    "show": true
  },
  "timezone": {
    "ianaTimezone": "string",
    "autoUpdate": true,
    "show": true
  },
  "birthday": {
    "date": "2022-03-10T16:15:50Z",
    "show": "NONE"
  },
  "software": "wellesley",
  "channel": true,
  "groupId": "us_01hxcvk1hjexere4pvtrj0ymqq",
  "groupPrivacy": "PUBLIC",
  "groupMain": true,
  "groupDefault": true,
  "actorType": "Application"
}

Group Member Settings

Endpoints for managing member-specific settings within groups. These settings are personal to each group member and affect their individual experience within the group. Members can only access and modify their own settings within groups they belong to.

Operations

Group Members

API endpoints for managing group membership. Provides functionality to add, update, and remove members from groups, as well as retrieve membership information. Supports both local and federated groups through ActivityPub protocol. Access control is enforced based on group privacy settings and user permissions.

Operations

Group Questions

API endpoints for managing group entry questions. Groups can require prospective members to answer questions before joining. Questions support multiple types (text, single choice, multiple choice) and are used to screen members when the group's join mode is set to QUESTIONS. Answers are validated and generate a token that can be used during the join process.

Operations

Group Reports

Group-scoped moderation reports. Allows group admins to review and resolve reports targeting their channels, forums, and events without global moderator access.

Operations

Group Rules

API endpoints for managing community rules within groups. Rules define the expected conduct and content policies that members must follow. Each rule consists of text (the rule itself), a hint (explanation or context), and an ordering value for display sequence. Rules are scoped to specific groups and can be managed by users with appropriate permissions.

Operations

Group Settings

Endpoints for managing group-specific settings and configuration options. These endpoints allow authorized group members to view, update, and delete settings that control group behavior, features, and customization options.

Operations

Groups

API endpoints for managing groups within the Wellesley platform. Groups are community spaces that can be public or private, support forums, and have their own membership and permission systems. Groups can be federated via ActivityPub for cross-instance communication.

Operations

Import

Endpoints for importing data from other platforms including followers, blocks, and mutes

Operations

Instance

Server instance information and configuration. Provides metadata about the server, compatible domains, supported languages, timezones, and countries. All endpoints are publicly accessible without authentication.

Operations

Invites

Endpoints for sending and managing user invitations

Operations

Jobs

Endpoints for monitoring and managing background job queues, including statistics, job listings, and queue monitoring

Operations

Lists

Endpoints for managing user lists for organizing and grouping followed accounts

Operations

Logins

Endpoints for managing user login methods including email, password, and phone authentication

Operations

Metrics

Endpoints for retrieving metrics and analytics data from the events stream

Operations

Mutes

Endpoints for managing user mutes to hide content from specific users

Operations

Notes

Endpoints for managing personal notes about other users

Operations

Notifications

Endpoints for managing user notifications including retrieving, counting, and marking notifications as read or unread

Operations

Passkeys

Passkey (WebAuthn) registration and authentication

Operations

Password

Endpoints for password management including changing, resetting, and recovering passwords

Operations

Pins

Endpoints for pinning posts to profiles and retrieving pinned posts

Operations

Platform Data

Endpoints for managing platform-wide and group-specific data storage. Unlike application data, this provides direct data management not tied to specific applications. Supports flexible ownership models including platform-level, group-level, and user-level data with appropriate access controls.

Operations

Platform Settings

Endpoints for managing platform-wide settings and configuration options. These endpoints control server-level settings that affect the entire platform, including features, limits, security policies, and default behaviors for all users and groups.

Operations

Polls

Endpoints for interacting with polls, including voting and retrieving results

Operations

Posts

Endpoints for creating, reading, updating, and deleting posts, as well as managing comments, likes, bookmarks, and reposts

Operations

RBAC

Endpoints for retrieving Role-Based Access Control (RBAC) configurations and managing roles, resources, permissions and role-to-user assignments. Scoped Role Definition (RBACRole):

  • Represents roles within the RBAC system.
  • Each role has a unique roleId, a name, an optional description, and a scope.
  • The scope defines the domain or area in which the role is valid.
  • The scope can be Global (hardcoded), currently the only one is "System"
  • The scope also can be dynamic, currently we use Group Ids, like "gr_05hxcvk1hjexere4pvtrj0hggt"
  • Roles come with assigned permissions (RBACPermissions) that define what actions the role can perform on system resources.
  • Metadata such as createdAt and updatedAt timestamps track the role's lifecycle events.

Permissions** (RBACPermissions):

  • Encapsulates resource-specific access controls.
  • Each permission object specifies the resource (e.g., "user", "document") and an associated list of allowed RBACAccess types.
  • RBACAccess enumerates the supported actions: Read, Add, Modify, Delete.

Role Assignments to Actors (RBACActorRole):

  • Maps actors (e.g., users, services) to specific roles.
  • Tracks the association through actorId (representing the unique entity being assigned) and roleId (specific role ID).
  • Includes timestamps to record when the assignment was created or updated.
Operations

Remote collections

API to retrieve followers and following collections for remote users.

Operations

Reports

Endpoints for reporting content and managing content reports

Operations

Rules

Endpoints for managing platform rules that govern user conduct and content policies

Operations

Sessions

Endpoints for managing user authentication sessions and device logins

Operations

Tags

Endpoints for managing hashtags, including following, featuring, and retrieving tag information

Operations

Tags v2

Scoped tags search, policy lists and reports

Operations

Translation

Endpoints for translating text between languages

Operations

Uploads

Endpoints for uploading, retrieving, and managing media files

Operations

User Devices

APIs for managing user devices for push notifications

Operations

User Settings

Endpoints for managing user-specific settings and preferences. These endpoints allow authenticated users to view, update, and delete their personal settings that control their account behavior, interface preferences, privacy options, and feature customizations.

Operations

Users

Endpoints for managing user profiles, including creation, retrieval, updates, and moderation

Operations

employee

Employee. DO NOT USE, SUBJECT TO CHANGE/REMOVE

employer

Employer. DO NOT USE, SUBJECT TO CHANGE/REMOVE

job-applications

Jobs. DO NOT USE, SUBJECT TO CHANGE/REMOVE

job-postings

Jobs. DO NOT USE, SUBJECT TO CHANGE/REMOVE

phone

Phone management

Operations

Fasp Resource

Operations

Debug Resource

Operations

Test Authenticated Controller

Operations

Test Class Auth Controller

Operations

Test Class Authenticated Controller

Operations

Test Class Permit All Controller

Operations

Test Permit All Controller

Operations

Test Authorization Controller

Operations

Quarkus Test Resource For Transaction

Operations