Developers
Build with Welley
You can use the Welley API to build clients, scripts, community tools and integrations. The live Swagger reference describes the operations and schemas you can use.
We plan to release Welley as open source in the future. No release date or license is announced yet.
Start with a public request
The API runs over HTTPS, and most operations take and return JSON. Public read operations can work without an account.
Read server information
This request returns public metadata about the server. It doesn't change any server data.
curl --fail --silent --show-error "https://welley.social/api/v1/instance"Look up the operation in Swagger
Before you write a client, check its parameters, request schema, response schema and permissions.
Authenticate an integration
Protected operations need a valid token in the Authorization header. Our official CLI sends the token with the Bearer prefix.
Read your effective server permissions
Set WELLEY_TOKEN to your own valid token, the way you usually handle secrets. This example only reads data.
curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"- For an integration, create a personal access token in your account settings.
- Give it a name and an expiration. The API also accepts expiresInDays=0 for a token with no stored expiration.
- Limit which global permissions, group permissions and groups the token can use.
- If you leave an allow-list empty, that field is limited only by your current access. A token can't give rights that you don't have.
- You'll see the token secret only once. Save it before you close the creation result.
- To manage tokens, you need an account login session. A personal access token can't create, list, copy or revoke tokens.
Check permissions and scope
Authentication tells the API who's calling. Role permissions decide which operations that caller can use.
- The API returns 401 when a protected request has no valid authentication.
- The API returns 403 when the caller doesn't have a required permission.
- Permission names follow Resource.Action, for example GroupSettings.Manage.
- For scoped webhook and permission operations, leave out scope to use server scope. For group scope, pass a group TypeId.
- Read the description of each operation. Some endpoints use HTTP signatures or another protocol instead of an account token.
Choose an API area
The reference covers social features, integrations and server administration. The examples here are just a small part of the API.
Accounts and profiles
Read profiles, manage account identities and use the account export or move operations.
| Method | Path | Operation | Access |
|---|---|---|---|
| GET | /api/v1/users | Read a local or remote profile by username. | Public or optional token |
| POST | /api/v1/users | Add another profile to the current account, up to the server's limit. | Token required |
Posts and feeds
Read feeds and create posts. Other operations handle replies, polls, reactions, drafts and saved posts.
| Method | Path | Operation | Access |
|---|---|---|---|
| GET | /api/v1/posts | Read public posts as a guest, or a personalized feed when you're authenticated. | Public or optional token |
| POST | /api/v1/posts | Create a post with its content and who can see it. | Token required |
Groups and events
Build community tools with groups, membership, channels, moderation and events.
| Method | Path | Operation | Access |
|---|---|---|---|
| POST | /api/v1/groups | Create a group, using the permissions of the authenticated user. | Token required |
| GET | /api/v1/events | List public events or the events the authenticated user can see. | Public or optional token |
| POST | /api/v1/events | Create an event. A group event needs GroupEvents.Create. | Token required |
Conversations and notifications
Read conversation rooms and their messages. Read notification collections and update whether they're read.
| Method | Path | Operation | Access |
|---|---|---|---|
| GET | /api/v1/rooms | List the current user's rooms. To continue the list, use nextCursor from the response body. | Token required |
| GET | /api/v1/user-notifications | List the current user's notifications. | Token required |
Media, search and translation
Upload media, search the content you can see and ask for text translations.
| Method | Path | Operation | Access |
|---|---|---|---|
| POST | /api/v1/uploads | Create an upload entry, then PUT the file content to the upload URL it returns. | Token required |
| GET | /api/v1/search | Search the content the caller can see, or resolve supported URLs. | Public or optional token |
| POST | /api/v1/translate/text | Translate text into the requested language. | Token required |
Webhooks and AI agents
Connect outside services with webhooks. Set up AI agents through the agent APIs.
| Method | Path | Operation | Access |
|---|---|---|---|
| GET | /api/v1/webhooks/events | Get the list of supported webhook event types. | Token required |
| POST | /api/v1/webhooks | Create a webhook in a server or group scope you have permission for. The HTTP signing secret is shown only once. | Token required |
| GET | /api/v1/ai-agents | List the AI agents the caller can see. | Token required |
Server and group administration
Use the API for settings, reports, moderation, federation controls, quotas and deployment administration.
| Method | Path | Operation | Access |
|---|---|---|---|
| GET | /api/v1/rbac/permissions | Read the effective permissions for the current user and scope. | Token required |
| GET | /api/v1/settings | Read platform settings, if the account has the required permissions. | Public or optional token |
Handle responses and media
Follow each operation's own pagination and upload flow.
- For cursor feeds, follow the pagination links the server returns. Don't build cursors from guesses about IDs.
- Rooms return an opaque nextCursor in the response body. When you continue the list, keep the same filters.
- To upload media, create an upload entry, then send the content to the URL it returns.
- Check each operation's error responses and limits. Even a documented operation can need a role, a server configuration or an external provider.