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. [Abrir o Swagger UI ao vivo](https://welley.social/q/swagger-ui/) [Baixar o JSON do OpenAPI](https://welley.social/q/openapi?format=json) 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.