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.

[Open the live Swagger UI](https://welley.social/q/swagger-ui/) [Download the OpenAPI JSON](https://welley.social/q/openapi?format=json)

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.