The AI Agents API manages bot creation and configuration. Each bot is a user profile of type Service with a configuration profile that includes tools, triggers, and scope. Global bots operate in the global scope; group bots operate within a group scope.
Wellesley Platform API (1.0)
Wellesley is a decentralized social platform built on top of ActivityPub. It operates as a federation of independent servers that exchange data using standard ActivityPub messages alongside custom extensions. The platform strives for Mastodon compatibility while introducing additional capabilities such as Groups, Forums, rich media, AI agents, and fine-grained access control.
This API provides full access to the platform's functionality including user and account management, posting and feeds, group creation and moderation, notifications, real-time streaming, search, federated content delivery, AI agent configuration, and platform administration. Most endpoints accept and return JSON. Pagination follows cursor-based patterns using Link headers.
Authentication: Endpoints that require authentication expect an Authorization header with a valid access token. Unauthenticated requests to protected endpoints will receive a 401 response.
RBAC (Role-Based Access Control): Some endpoints are protected by RBAC permissions. When an endpoint description mentions "RBAC: requires ...", the caller must hold the listed permission(s) in addition to being authenticated. Requests that lack the required permissions will receive a 403 response. RBAC permissions are scoped to resources (e.g., Group, Post, User) and actions (e.g., Read, Write, Moderate), and are assigned through roles.
Download OpenAPI description
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
Endpoints for viewing AI providers and configuring per-scope API keys. Providers are catalog entries synced from models.dev. Use scope='global' for platform-wide configuration (requires AIProviders permissions) or a group TypeId for group-specific configuration (requires GroupAIProviders permissions).
Operations
- Mock serverhttps://docs.wellesley.social/_mock/openapi/api/v1/ai-providers
- Simple setup, all in one. Digital Oceanhttps://dust.allroads.social/api/v1/ai-providers
- Simple setup, db is separate. Digital Oceanhttps://meteor.allroads.social/api/v1/ai-providers
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://docs.wellesley.social/_mock/openapi/api/v1/ai-providers?scope=string' \
-H 'Authorization: YOUR_API_KEY_HERE'List of providers with scoped state
Provider unique identifier (catalog)
Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
Masked preview of the stored API key (provider prefix + first few unique chars)
Example: "sk-abcd..."
Lightweight API key format hint for this provider type
When the provider was last updated
Example: "2022-03-10T16:15:50Z"
Response
application/json
[ { "providerId": "us_01hxcvk1hjexere4pvtrj0ymqq", "providerType": "OPENAI", "name": "string", "configured": true, "hasApiKey": true, "apiKeyPreview": "sk-abcd...", "apiKeyFormatHint": { … }, "logoUrl": "https://models.dev/logos/openai.svg", "createdAt": "2022-03-10T16:15:50Z", "updatedAt": "2022-03-10T16:15:50Z" } ]
- Mock serverhttps://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/{providerId}
- Simple setup, all in one. Digital Oceanhttps://dust.allroads.social/api/v1/ai-providers/{providerId}
- Simple setup, db is separate. Digital Oceanhttps://meteor.allroads.social/api/v1/ai-providers/{providerId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/us_01hxcvk1hjexere4pvtrj0ymqq?scope=string' \
-H 'Authorization: YOUR_API_KEY_HERE'Response
application/json
{ "providerId": "us_01hxcvk1hjexere4pvtrj0ymqq", "providerType": "OPENAI", "name": "string", "configured": true, "hasApiKey": true, "apiKeyPreview": "sk-abcd...", "apiKeyFormatHint": { "prefixes": [ … ], "exampleMasked": "sk-...abcd", "rule": "string", "docsUrl": "string", "regexHint": "string" }, "logoUrl": "https://models.dev/logos/openai.svg", "createdAt": "2022-03-10T16:15:50Z", "updatedAt": "2022-03-10T16:15:50Z" }
- Mock serverhttps://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/{providerId}/agents
- Simple setup, all in one. Digital Oceanhttps://dust.allroads.social/api/v1/ai-providers/{providerId}/agents
- Simple setup, db is separate. Digital Oceanhttps://meteor.allroads.social/api/v1/ai-providers/{providerId}/agents
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/us_01hxcvk1hjexere4pvtrj0ymqq/agents?scope=string' \
-H 'Authorization: YOUR_API_KEY_HERE'List of AI agents using this scoped provider configuration
Bot user profile
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"
Entity type: USER, BOT, APPLICATION, GROUP_CHANNEL
Enum"USER""BOT""APPLICATION""GROUP_CHANNEL"
Group ID if this is a group channel, group user or category.
Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
- 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"
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"
User's summary or bio
Example: "Pixels are my paint, code is my canvas, creativity is my brush."
Software platform type (wellesley, mastodon, threads.net)
Example: "wellesley"
Sync state for remote users:
- SHALLOW_SYNCED - Profile fetched, only first page of outbox loaded
- SYNC_IN_PROGRESS - Deep sync is currently running
- DEEP_SYNCED - Full outbox has been fetched
- DEEP_SYNC_FAILED - Deep sync attempted but failed (retryable)
Enum"SHALLOW_SYNCED""SYNC_IN_PROGRESS""DEEP_SYNCED""DEEP_SYNC_FAILED"
When the last deep sync completed (null if never deep-synced)
Example: "2022-03-10T16:15:50Z"
Follow approval mode: AUTO_APPROVE, MANUALLY_APPROVES, or UNKNOWN
Enum"AUTO_APPROVE""MANUALLY_APPROVES""UNKNOWN"
Bot configuration profile
Group scope resource ids (channels/categories/forums). Empty means whole group.
Example: ["us_01hz1f0kw36f82k9s4nzpc4s92n","ct_01hz1f0kw36f82k9s4nzpc4s92n"]
List of tools enabled for this bot
Items Enum"VECTOR_SEARCH""REGULAR_SEARCH""ENTITY_SEARCH""WEB_SEARCH""POSTS_SINCE_LAST_INVOCATION""POSTS_IN_TIME_RANGE""LIST_GROUP_STRUCTURE""REPLY""LIKE""REPORT"
Example: ["VECTOR_SEARCH","REPLY"]
profile.​triggersArray of AIAgentTriggerPostCreated (object) or AIAgentTriggerReplyCreated (object) or AIAgentTriggerPostEdited (object) or AIAgentTriggerMentioned (object) or AIAgentTriggerQuestionDetected (object) or AIAgentTriggerKeywordMatch (object) or AIAgentTriggerIntentMatch (object) or AIAgentTriggerReportedContent (object) or AIAgentTriggerThreshold (object) or AIAgentTriggerUnanswered (object) or AIAgentTriggerCron (object) or AIAgentTriggerNewGroupMember (object)(AIAgentTrigger)
Configured triggers for this bot
Model identifier (ai_models.model_id); must be enabled in this scope
Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
List of uploads (documents) attached to the bot
Example: ["up_01hz1f0kw36f82k9s4nzpc4s92n"]
Daily budget in USD cents (null = unlimited)
Example: 1000
Monthly budget in USD cents (null = unlimited)
Example: 10000
Maximum invocations per hour (null = unlimited)
Example: 100
Maximum invocations per day (null = unlimited)
Example: 1000
Role/instruction directives for the agent
Example: ["Skeptical engineer"]
Personality traits used when building agent instructions
Example: ["Friendly","Fact-checking"]
Writing/response style directives
Example: ["Clear paragraphs","Simple language"]
Behavior directives
Example: ["Explain first","Ask clarifying questions"]
Additional free-form prompt/instructions
Example: "Prioritize concise actionable guidance."
Group id for group-scoped bots
Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
Combined stats across all profile versions for the current agent state
Stats for this exact profile version
When this profile version became current (null for non-current versions)
Example: "2022-03-10T16:15:50Z"
Response
application/json
[ { "user": { … }, "profile": { … }, "model": { … }, "provider": { … }, "latestVersion": 0, "isLatest": true } ]
- Mock serverhttps://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/{providerId}/configure
- Simple setup, all in one. Digital Oceanhttps://dust.allroads.social/api/v1/ai-providers/{providerId}/configure
- Simple setup, db is separate. Digital Oceanhttps://meteor.allroads.social/api/v1/ai-providers/{providerId}/configure
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
'https://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/us_01hxcvk1hjexere4pvtrj0ymqq/configure?scope=string' \
-H 'Authorization: YOUR_API_KEY_HERE'Request
Sets or updates the API key and auth configuration for a provider in the given scope. Creates a scoped provider record if one doesn't exist.
RBAC:
- requires ANY of AIProviders.Manage, GroupAIProviders.Manage
Security
header
- Mock serverhttps://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/{providerId}/configure
- Simple setup, all in one. Digital Oceanhttps://dust.allroads.social/api/v1/ai-providers/{providerId}/configure
- Simple setup, db is separate. Digital Oceanhttps://meteor.allroads.social/api/v1/ai-providers/{providerId}/configure
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/us_01hxcvk1hjexere4pvtrj0ymqq/configure?scope=string' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"authType": "API_KEY",
"authSecret": "string",
"clearAuthSecret": true
}'Response
application/json
{ "providerId": "us_01hxcvk1hjexere4pvtrj0ymqq", "providerType": "OPENAI", "name": "string", "configured": true, "hasApiKey": true, "apiKeyPreview": "sk-abcd...", "apiKeyFormatHint": { "prefixes": [ … ], "exampleMasked": "sk-...abcd", "rule": "string", "docsUrl": "string", "regexHint": "string" }, "logoUrl": "https://models.dev/logos/openai.svg", "createdAt": "2022-03-10T16:15:50Z", "updatedAt": "2022-03-10T16:15:50Z" }
- Mock serverhttps://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/{providerId}/models
- Simple setup, all in one. Digital Oceanhttps://dust.allroads.social/api/v1/ai-providers/{providerId}/models
- Simple setup, db is separate. Digital Oceanhttps://meteor.allroads.social/api/v1/ai-providers/{providerId}/models
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://docs.wellesley.social/_mock/openapi/api/v1/ai-providers/us_01hxcvk1hjexere4pvtrj0ymqq/models?enabled=true&includeDeprecated=true&scope=string' \
-H 'Authorization: YOUR_API_KEY_HERE'List of models with scoped state
Whether the model is enabled in the requested scope (null if no scoped record)
Successor model ID if deprecated
Example: "us_01hxcvk1hjexere4pvtrj0ymqq"
Model capabilities
Supported input/output modalities
Items Enum"TEXT""IMAGE""AUDIO""VIDEO""PDF"
Built-in tools supported natively by the provider for this model
Items Enum"WEB_SEARCH""CODE_EXECUTION""FILE_SEARCH""COMPUTER_USE""IMAGE_GENERATION""TEXT_EDITOR""BASH""URL_CONTEXT""MCP"
Token limits
Pricing information
Response
application/json
[ { "modelId": "us_01hxcvk1hjexere4pvtrj0ymqq", "providerId": "us_01hxcvk1hjexere4pvtrj0ymqq", "externalId": "string", "name": "string", "enabled": true, "deprecated": true, "successorModelId": "us_01hxcvk1hjexere4pvtrj0ymqq", "capabilities": { … }, "modalities": [ … ], "builtInTools": [ … ], "limits": { … }, "pricing": { … }, "family": "string", "releaseDate": "string", "knowledgeCutoff": "string", "openWeights": true, "createdAt": "2022-03-10T16:15:50Z", "updatedAt": "2022-03-10T16:15:50Z" } ]
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. Requires Users.Manage permission unless otherwise noted on individual endpoints.
Operations
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. Write operations require Federation.Manage permission; read operations require Federation.Read or Federation.Manage permission.
Operations
Administrative endpoints for managing domain allowlists. When domain allowlisting is enabled, only domains in this list can federate with the instance. Write operations require Federation.Manage permission; read operations require Federation.Read or Federation.Manage permission.
Operations
Administrative endpoints for managing the email domain allowlist used during user registration. When enabled, only email addresses from allowed domains can sign up. Write operations require AdminSettings.Manage permission; read operations require AdminSettings.Read or AdminSettings.Manage permission.
Operations
Administrative endpoints for managing FASP (Fediverse Auxiliary Service Provider) provider registrations and default capability assignments. Allows accepting, declining, and blocking providers, as well as configuring which provider is the default for each capability. Read operations require Federation.Read or Federation.Manage permission; write operations require Federation.Manage permission.
Operations
Administrative endpoints for monitoring and managing federation with other ActivityPub instances. Provides metrics on connected domains, user counts, post statistics, and federation health monitoring including sliding window performance metrics for inbox processing. Requires Federation.Read or Federation.Manage permission.
Operations
Administrative endpoints for configuring a remote link preview service provider. This service fetches rich link previews (title, description, image) for URLs shared in posts. The provider must support the 'link_preview' FASP capability. Requires AdminSettings.Manage permission.
Operations
Administrative endpoints for managing user signup requests. Provides tools for reviewing, approving, rejecting, and managing signup requests in the moderation queue. Supports workflow for manual account approval when enabled. Read operations require Signups.Read or Signups.Manage permission; write operations require Signups.Manage permission.
Operations
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. Requires Uploads.Read permission.
Operations
Endpoints for managing forum categories within groups. Categories organize forum discussions into topics, allowing structured content browsing. Each forum must have at least one category. Most management operations require the GroupForum.Manage RBAC permission (group admin/moderator). Read operations are accessible according to group visibility settings.
Operations
Administrative endpoints for managing vector embeddings used in AI-powered features such as semantic search and content recommendations. Provides tools for enabling/disabling embeddings, configuring the embedding model, estimating costs, and managing batch recalculation jobs. Requires AdminSettings.Manage permission.
Operations
Administration endpoints for managing FASP (Fediverse Auxiliary Service Provider) registrations and capabilities. Handles the FASP registration workflow: providers register via POST, admins confirm registration, and capabilities are activated or deactivated. Also provides debug and backfill request tools. The registration endpoint is publicly accessible; all other endpoints require the Federation.Manage RBAC permission.
Operations
FASP (Fediverse Auxiliary Service Provider) data sharing endpoints implementing the FASP data sharing protocol v0. Allows FASP providers to subscribe to content lifecycle events and trends, request backfills of historical data, and manage their subscriptions. All requests are authenticated using FASP Ed25519 HTTP signature verification, not user authentication. Not intended to be called directly by client applications.
Debug endpoints for FASP (Fediverse Auxiliary Service Provider) integration testing. Allows FASP providers to submit debug callback responses and administrators to view and manage callback logs. The POST endpoint uses FASP Ed25519 HTTP signature authentication; the GET and DELETE endpoints are currently unauthenticated and intended for admin use only.
Endpoints for managing discussion forums within groups. Each group can have one forum that organizes discussions into categories and tags. Forums are auto-created on first access if the group does not already have one. Management operations (update, delete) require the GroupForum.Manage RBAC permission (group admin/moderator). Read operations follow group visibility settings.
Operations
Endpoints for managing applications available to groups. Applications are installable modules that extend group functionality. Group admins can add or remove applications from their groups. The global apps list shows all available applications at the GROUP entry point, while per-group lists show only applications installed for that specific group. Management operations require the GroupApps.Manage RBAC permission.
Operations
API endpoints for managing channels within groups. Channels are specialized accounts that enable organized content distribution within groups. They support hierarchical organization with primary and auto-subscribe channels, privacy controls inherited from parent groups, and both scoped (group-specific) and global usernames for discovery. Group admins manage channels while members follow.
Operations
API endpoints for managing group invitations. Group owners and admins can invite users to join their groups. Invitees can accept or reject invitations. Creating invitations requires the GroupMembers.Invite RBAC permission. Accepting, rejecting, and viewing personal invitations require standard authentication.
Operations
API endpoints for group join workflows. Users can request to join a group, and group admins can approve or reject join requests. Join behavior depends on the group's join mode: OPEN (instant), APPROVAL (requires admin approval), or INVITE_ONLY (requires invitation). Groups may also have entry questions that must be answered before joining. Admin operations (listing, approving, rejecting requests) require the GroupMembers.Manage RBAC permission. All endpoints require authentication.
Operations
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
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
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
Login method management for authenticated accounts. Allows adding or removing email/password and phone number as authentication methods. Adding a login method requires email or SMS verification. Removing a method is blocked if it is the last remaining login identifier. All changes are audited. All endpoints require authentication.
Operations
User muting functionality for hiding content from specific users without blocking them. Muting a user hides their posts from your timelines and notifications, but does not prevent them from following you or interacting with your content. Mutes can be temporary (with an expiration duration) or permanent. All endpoints require authentication.
Operations
User notification management for retrieving, counting, and updating notification status. Notifications are generated by user interactions such as follows, mentions, reposts, and likes. Supports filtering by notification type and status (read/unread). All endpoints require authentication.
Operations
Password management endpoints for changing and recovering account passwords. Supports two flows: authenticated password change (requires current password and email confirmation) and unauthenticated password recovery (sends reset code to account email). All password changes invalidate other active sessions for security.
Operations
Phone number change management for authenticated users. Implements a secure 4-step phone change flow: (1) request change and receive SMS code on current phone, (2) verify current phone ownership, (3) submit new phone number and receive SMS code, (4) verify new phone number. All endpoints require authentication.
Operations
Endpoints for managing Pins (top-level posts) and Highlights (pinned replies). Top-level pins are shown first in the profile scope and are limited by admin setting Maximum number of pinned posts. Replies can be pinned as highlights under their root post. Pin and unpin actions are federated via ActivityPub.
Operations
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
Endpoints for creating, reading, updating, and deleting posts, as well as managing comments, likes, bookmarks, reposts, subscriptions, and votes. Most endpoints require authentication; read-only feed and post endpoints are accessible to guests via @PermitAll. Post mutations are federated via ActivityPub.
Operations
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, aname, an optionaldescription, and ascope. - The
scopedefines the domain or area in which the role is valid. - The
scopecan be Global (hardcoded), currently the only one is "global" - The
scopealso 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
createdAtandupdatedAttimestamps 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 allowedRBACAccesstypes. RBACAccessenumerates 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) androleId(specific role ID). - Includes timestamps to record when the assignment was created or updated.
Operations
API to retrieve followers and following collections for remote (federated) users. Fetches collection data from remote ActivityPub servers, resolves actor URIs to user profiles, and returns them in the local user format. Supports pagination via offset/limit parameters. All endpoints are publicly accessible (@PermitAll) and operate on remote users only -- local users are rejected.
Operations
Authentication session management endpoints. Allows users to view active sessions across devices, revoke individual sessions or all other sessions, and permanently delete session records. Sessions are tracked in both the database and Redis for real-time state synchronization. All endpoints require authentication. The current session cannot be revoked or deleted.
Operations
Endpoints for uploading, retrieving, and managing media files. The upload flow is two-step: first create an upload via POST to get an upload URL, then PUT the actual file content to that URL. Most endpoints require authentication. Class-level @RBACAuthorize requires authentication by default; public endpoints use @PermitAll.
Operations
User profile management endpoints. Handles user creation, retrieval by ID or username, profile updates, deletion, and social graph queries (followers/following). Supports both authenticated and guest access with varying levels of detail. Guest users receive basic profile data; authenticated users can access relationship statuses and full profiles.
Operations