Desenvolvedores
Crie com o Welley
Você pode usar a API do Welley para criar clientes, scripts, ferramentas para comunidades e integrações. A referência Swagger ao vivo descreve as operações e os esquemas que você pode usar.
Planejamos lançar o Welley como código aberto no futuro. Ainda não há data de lançamento nem licença anunciadas.
Comece com uma requisição pública
A API funciona por HTTPS, e a maioria das operações recebe e retorna JSON. As operações públicas de leitura podem funcionar sem conta.
Leia as informações do servidor
Essa requisição retorna metadados públicos sobre o servidor. Ela não altera nenhum dado do servidor.
curl --fail --silent --show-error "https://welley.social/api/v1/instance"Consulte a operação no Swagger
Antes de escrever um cliente, confira os parâmetros, o esquema da requisição, o esquema da resposta e as permissões.
Autentique uma integração
Operações protegidas precisam de um token válido no cabeçalho Authorization. Nossa CLI oficial envia o token com o prefixo Bearer.
Leia suas permissões efetivas no servidor
Defina WELLEY_TOKEN com o seu próprio token válido, do jeito que você costuma lidar com segredos. Este exemplo só lê dados.
curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"- Para uma integração, crie um token de acesso pessoal nas configurações da sua conta.
- Dê a ele um nome e uma data de expiração. A API também aceita expiresInDays=0 para um token sem expiração armazenada.
- Limite quais permissões globais, permissões de grupo e grupos o token pode usar.
- Se você deixar vazia uma lista de itens permitidos, esse campo fica limitado apenas pelo seu acesso atual. Um token não pode dar direitos que você não tem.
- Você verá o segredo do token só uma vez. Salve-o antes de fechar o resultado da criação.
- Para gerenciar tokens, você precisa de uma sessão de login da conta. Um token de acesso pessoal não pode criar, listar, copiar nem revogar tokens.
Confira permissões e escopo
A autenticação diz à API quem está chamando. As permissões do papel decidem quais operações esse chamador pode usar.
- A API retorna 401 quando uma requisição protegida não tem autenticação válida.
- A API retorna 403 quando o chamador não tem uma permissão necessária.
- Os nomes de permissão seguem Resource.Action, por exemplo GroupSettings.Manage.
- Em operações de webhook e permissão com escopo, omita scope para usar o escopo do servidor. Para o escopo de grupo, passe o TypeId de um grupo.
- Leia a descrição de cada operação. Alguns endpoints usam assinaturas HTTP ou outro protocolo em vez de um token de conta.
Escolha uma área da API
A referência cobre recursos sociais, integrações e administração do servidor. Os exemplos aqui são só uma pequena parte da API.
Contas e perfis
Leia perfis, gerencie as identidades da conta e use as operações de exportação ou migração da conta.
| Método | Caminho | Operação | Acesso |
|---|---|---|---|
| GET | /api/v1/users | Leia um perfil local ou remoto pelo nome de usuário. | Público ou token opcional |
| POST | /api/v1/users | Adicione outro perfil à conta atual, até o limite do servidor. | Token obrigatório |
Publicações e feeds
Leia feeds e crie publicações. Outras operações cuidam de respostas, enquetes, reações, rascunhos e publicações salvas.
| Método | Caminho | Operação | Acesso |
|---|---|---|---|
| GET | /api/v1/posts | Leia publicações públicas como visitante ou um feed personalizado quando você estiver autenticado. | Público ou token opcional |
| POST | /api/v1/posts | Crie uma publicação, definindo o conteúdo e quem pode vê-la. | Token obrigatório |
Grupos e eventos
Crie ferramentas para comunidades com grupos, membros, canais, moderação e eventos.
| Método | Caminho | Operação | Acesso |
|---|---|---|---|
| POST | /api/v1/groups | Crie um grupo usando as permissões do usuário autenticado. | Token obrigatório |
| GET | /api/v1/events | Liste os eventos públicos ou os eventos que o usuário autenticado pode ver. | Público ou token opcional |
| POST | /api/v1/events | Crie um evento. Um evento de grupo precisa de GroupEvents.Create. | Token obrigatório |
Conversas e notificações
Leia salas de conversa e suas mensagens. Leia coleções de notificações e atualize se foram lidas.
| Método | Caminho | Operação | Acesso |
|---|---|---|---|
| GET | /api/v1/rooms | Liste as salas do usuário atual. Para continuar a lista, use nextCursor do corpo da resposta. | Token obrigatório |
| GET | /api/v1/user-notifications | Liste as notificações do usuário atual. | Token obrigatório |
Mídia, busca e tradução
Envie mídia, busque o conteúdo que você pode ver e peça traduções de texto.
| Método | Caminho | Operação | Acesso |
|---|---|---|---|
| POST | /api/v1/uploads | Crie uma entrada de upload e depois envie o conteúdo do arquivo com PUT para o URL de upload que ela retorna. | Token obrigatório |
| GET | /api/v1/search | Busque o conteúdo que o chamador pode ver ou resolva URLs compatíveis. | Público ou token opcional |
| POST | /api/v1/translate/text | Traduza o texto para o idioma solicitado. | Token obrigatório |
Webhooks e agentes de IA
Conecte serviços externos com webhooks. Configure agentes de IA pelas APIs de agentes.
| Método | Caminho | Operação | Acesso |
|---|---|---|---|
| GET | /api/v1/webhooks/events | Obtenha a lista de tipos de evento de webhook compatíveis. | Token obrigatório |
| POST | /api/v1/webhooks | Crie um webhook em um escopo de servidor ou de grupo para o qual você tem permissão. O segredo de assinatura HTTP é mostrado só uma vez. | Token obrigatório |
| GET | /api/v1/ai-agents | Liste os agentes de IA que o chamador pode ver. | Token obrigatório |
Administração de servidor e de grupo
Use a API para configurações, denúncias, moderação, controles de federação, cotas e administração de implantação.
| Método | Caminho | Operação | Acesso |
|---|---|---|---|
| GET | /api/v1/rbac/permissions | Leia as permissões efetivas do usuário e do escopo atuais. | Token obrigatório |
| GET | /api/v1/settings | Leia as configurações da plataforma, se a conta tiver as permissões necessárias. | Público ou token opcional |
Trabalhe com respostas e mídia
Siga a paginação e o fluxo de upload próprios de cada operação.
- Em feeds com cursor, siga os links de paginação que o servidor retorna. Não monte cursores a partir de suposições sobre IDs.
- As salas retornam um nextCursor opaco no corpo da resposta. Ao continuar a lista, mantenha os mesmos filtros.
- Para enviar mídia, crie uma entrada de upload e depois envie o conteúdo para o URL que ela retorna.
- Confira as respostas de erro e os limites de cada operação. Até uma operação documentada pode precisar de um papel, de uma configuração do servidor ou de um provedor externo.