HTTP API

Use a HTTP API para ler e alterar recursos. Descubra a URL base através de /.well-known/fluxer. Clientes de terceiros usam endpoints.api_public e o aplicativo web oficial usa endpoints.api_client.

Use /v1, a única versão da API. Download de objeto armazenado não é versionado e usa seu caminho raiz documentado.

Leia os limites de recursos em descoberta de instância. Contagens de anexos, contagens de expressões e tamanhos de campos de perfil podem variar entre implantações.

Notação de campo explica os campos opcionais, anuláveis e nulificáveis.

Formato de requisição

Envie corpos JSON com Content-Type: application/json. As respostas são JSON em UTF-8, exceto quando uma operação especifica o contrário. Operações de mensagem e execução de webhook também aceitam corpos multipart, e operações de token OAuth2 aceitam corpos de formulário.

Uma instância sobrecarregada retorna 503 SERVICE_UNAVAILABLE com Retry-After: 1. Aguarde antes de tentar novamente.

Caminhos desconhecidos e métodos não suportados retornam 404 NOT_FOUND sem cabeçalho Allow. Barras finais são significativas.

Toda rota GET suporta HEAD, retornando o mesmo status e cabeçalhos sem corpo. Rotas sem GET não suportam HEAD. O requisito de mesma origem do host também se aplica a HEAD.

Formatos de corpo de requisição

Cada operação documenta seu formato e campos de corpo aceitos.

Use application/json para JSON e application/x-www-form-urlencoded para corpos de formulário OAuth2. Operações de token OAuth2 também aceitam multipart/form-data.

Criar mensagem, Modificar mensagem e Executar webhook aceitam estes campos multipart:

Campo	Tipo	Descrição
payload_json?1	string	Objeto JSON com o payload completo da requisição de mensagem da operação
files[n]?2	file	Arquivo de anexo direto no índice de base zero n

¹ Um payload_json ausente é lido como um objeto vazio. Um valor que não é string ou que não é analisável como JSON é rejeitado com INVALID_JSON_IN_PAYLOAD_JSON

² n é uma sequência de dígitos decimais, no máximo 10000 e abaixo do limite max_attachments_per_message da implantação, que tem padrão 10

Os nomes legados file e file seguido de um índice também são aceitos como campos de arquivo, e um file simples ocupa o próximo índice legado livre.

Falhas no nome de campo são rejeitadas com seus próprios códigos:

• Um índice fora dos limites retorna FILE_INDEX_EXCEEDS_MAXIMUM.
• Qualquer outro nome começando com files[ retorna INVALID_FILE_FIELD_NAME.
• Dois campos de arquivo resolvendo para o mesmo índice retornam DUPLICATE_FILE_INDEX.
• Mais de um arquivo fornecido para um índice retorna MULTIPLE_FILES_FOR_INDEX_NOT_ALLOWED.
• Quando o limite resolvido é 0, qualquer campo de arquivo retorna ATTACHMENTS_NOT_ALLOWED_FOR_MESSAGE.

Inclua o boundary multipart em Content-Type e cada nome de campo em Content-Disposition. Corpos multipart malformados retornam FAILED_TO_PARSE_MULTIPART_FORM_DATA. Campos desconhecidos e valores não-arquivo para índices files[n] válidos são ignorados.

Um corpo multipart de mensagem PODE também ter content, nonce, tts, flags, favorite_meme_id e sticker_ids como campos de formulário simples. Cada um sobrescreve o membro de mesmo nome no payload_json analisado, e sticker_ids coleta cada valor recebido.

O array attachments dentro de payload_json mapeia metadados de anexo para arquivos, associando cada id de anexo a n em files[n]. Uma entrada de metadados com filename mas sem arquivo correspondente é rejeitada com NO_FILE_FOR_ATTACHMENT_METADATA, e duas entradas de metadados reivindicando o mesmo índice de arquivo são rejeitadas com DUPLICATE_ATTACHMENT_IDS_NOT_ALLOWED. Um arquivo fornecido sem entrada de metadados correspondente ainda é anexado, usando seu índice como ID do anexo e seu nome de upload como nome do arquivo. Uma entrada de metadados sem filename e sem arquivo correspondente é lida como referência a um anexo pré-carregado.

Mensagens define os metadados de anexo e o formulário de anexo pré-carregado, e Uploads de anexo define o fluxo separado de upload via relay.

Índices multipart são IDs de anexo

O índice files[n] de cada arquivo direto também é o id em sua entrada de metadados de anexo. O Decoding Chat lê n do nome do campo, então a ordem dos parts não define a identidade. Os índices não precisam começar em zero e não precisam ser consecutivos.

Normalização de entrada

Valores vazios são normalizados antes da validação

Uma string vazia se torna null em qualquer profundidade, e um objeto aninhado vazio se torna null abaixo da raiz do payload.

Essa normalização se aplica a corpos JSON e de formulário, strings de consulta, parâmetros de caminho, cabeçalhos de requisição e cookies.

Um objeto aninhado contendo apenas valores null também se torna null. O objeto raiz nunca se torna null, mesmo quando está vazio ou tem apenas valores null. Um corpo vazio é tratado como {} e validado para campos obrigatórios. JSON malformado retorna 400 INVALID_FORM_BODY com erro de validação no caminho body com código INVALID_FORMAT.

Operações de mensagem preservam valores vazios

Criar mensagem, Modificar mensagem e Executar webhook não aplicam essa normalização.

Essas operações documentam seus próprios erros de validação JSON.

Autenticação

Autenticação define os esquemas Authorization aceitos e vincula ao registro de escopo OAuth2. Cada operação indica quais credenciais aceita. O objeto de verificação sudo define a prova exigida para operações sensíveis de conta.

Um token de acesso bearer OAuth2 é aceito apenas onde uma rota opta por isso, e a página do recurso indica isso. Em qualquer outro lugar, uma credencial bearer é recusada com 403 ACCESS_DENIED. Uma conta com flag de atividade suspeita é recusada com 403 ACCOUNT_SUSPICIOUS_ACTIVITY.

Cabeçalhos de requisição padrão

Estes cabeçalhos são aceitos em todos os recursos. Um cabeçalho específico de operação está documentado na tabela de cabeçalhos de requisição daquela operação.

Campo	Tipo	Descrição
Authorization?	string	A credencial única para uma requisição autenticada, em um dos esquemas aceitos
Content-Type?1	string	Tipo de mídia do corpo da requisição e, para corpos multipart, o boundary
Accept-Language?2	string	Seleciona o locale usado para a message de erro
X-Audit-Log-Reason?3	string	Motivo em texto livre registrado na entrada do log de auditoria resultante
X-Fluxer-Client-Properties?4	string	JSON codificado em Base64 com o os do cliente nativo, lido ao criar uma sessão de autenticação
X-Fluxer-Sudo-Mode-JWT?5	string	Uma prova de modo sudo emitida anteriormente ao usuário autenticado
X-Captcha-Token?6	string	A solução CAPTCHA emitida pelo provedor selecionado
X-Captcha-Type?6	string	hcaptcha ou turnstile, selecionando o provedor que emitiu o token
X-Request-ID?7	string	Um identificador de correlação escolhido pelo cliente, ecoado sem alteração na resposta
User-Agent?	string	A descrição do cliente originador, registrada em uma nova sessão de autenticação e em uma entrada de auditoria Admin
Origin?8	string	A origem do navegador usada para negociação de origem cruzada e verificação de mesma origem em mutações

¹ Use o tipo de mídia especificado em formatos de corpo de requisição

² O locale configurado da conta autenticada tem precedência, então este cabeçalho seleciona o locale apenas para uma requisição não autenticada ou uma conta sem locale configurado

³ O valor é lido literalmente sem decodificação percentual, depois removidos caracteres de avanço de formulário e de substituição da direita para a esquerda e trimado. Um valor em branco ou muito longo é tratado como ausente

⁴ Lido apenas para um User-Agent nativo do Decoding Chat, com no máximo 4096 caracteres, e somente o membro os é usado

⁵ Um token válido substitui os campos de prova sudo no corpo da operação e é ecoado no cabeçalho de resposta sem extensão de tempo de vida

⁶ Lido apenas enquanto a instância tem um provedor configurado e a operação está bloqueada. O handshake é definido em Tratamento de CAPTCHA

⁷ Um valor fornecido é ecoado de volta sem alteração e sem validação

⁸ O uso exato é definido em requisições de origem cruzada

Um cliente NÃO DEVE enviar um X-Request-ID que não esteja disposto a ver em logs, pois o Decoding Chat ecoa e registra o valor sem validá-lo.

Um X-Audit-Log-Reason normalizado para mais de 512 caracteres é descartado, e a requisição ainda tem sucesso. Toda requisição é normalizada desta forma, mas apenas uma operação que suporta motivo de auditoria registra o resultado.

Cabeçalhos de resposta padrão

Campo	Tipo	Descrição
X-Fluxer-Version?1	string	A versão de build da instância que atendeu a requisição
X-Request-ID?2	string	O identificador atribuído à requisição
X-Fluxer-Sudo-Mode-JWT?3	string	O token de modo sudo para o chamador, presente apenas em uma operação que completa uma prova sudo
Content-Type?	string	O tipo de mídia da representação, ausente de uma resposta sem corpo
Cache-Control?4	string	O valor literal no-cache, exceto quando a operação define sua própria diretiva
Access-Control-Allow-Origin?5	string	O Origin da requisição quando é uma origem de aplicação configurada, e o literal * em rotas com curinga próprio
Access-Control-Expose-Headers?5	string	O valor literal X-Fluxer-Version, ETag
Vary?5	string	O valor literal Origin, enviado sempre que a origem permitida foi ecoada
Retry-After?6	string	Segundos inteiros de espera, enviado em negação de rate limit, slowmode, bloqueio de recurso e 503 de teto de requisições em andamento
X-RateLimit-Limit?7	string	Presente em negação de rota e em requisição bem-sucedida de bot ou webhook
X-RateLimit-Remaining?7	string	Presente em negação de rota e em requisição bem-sucedida de bot ou webhook
X-RateLimit-Reset?7	string	Timestamp Unix em segundos
X-RateLimit-Reset-After?7	string	Segundos até o bucket reiniciar
X-RateLimit-Bucket?7	string	Um hash estável de 16 caracteres do nome do bucket
X-RateLimit-Scope?7	string	Presente em negação de rate limit, com valor user, shared ou global
X-RateLimit-Global?7	string	Presente em negação de rate limit global, com valor literal true

¹ O valor é o literal dev quando o build não tem carimbo de versão

² Um UUID gerado, exceto quando a requisição forneceu o seu próprio, caso em que esse valor é ecoado de volta sem alteração e sem validação

³ Um token recém-emitido onde o chamador provou o modo sudo novamente, e caso contrário a prova recebida ecoada de volta sem extensão de tempo de vida

⁴ Ausente de uma resposta sem corpo

⁵ Access-Control-Expose-Headers é enviado em toda resposta que a política CORS da instância trata. Access-Control-Allow-Origin e Vary são enviados apenas para uma origem permitida

⁶ O literal 1 no 503 de teto de requisições em andamento, e caso contrário o contrato de cabeçalho de rate limit

⁷ O contrato completo é definido em Rate limits

Uma operação que define seu próprio Cache-Control mantém esse valor. Uma resposta cujo Content-Type nomeia uma stylesheet, script, fonte, imagem, vídeo ou representação de áudio recebe public, max-age=31536000.

Rate limits

Toda rota consome seu próprio bucket de rate limit. Uma rota que não está isenta do bucket global também conta contra um bucket global. Uma negação retorna 429 RATE_LIMITED. Rate limits define as regras de escopo de bucket, a permissão global, o corpo do 429, o registro de escopos e o contrato completo de cabeçalhos X-RateLimit-*.

Estas respostas 429 não têm cabeçalhos X-RateLimit-*

Uma resposta 429 RESOURCE_LOCKED tem Retry-After: 1, e uma resposta 429 IP_AUTHORIZATION_RESEND_COOLDOWN tem o tempo restante de cooldown em segundos inteiros. Um cliente que lê os cabeçalhos de bucket faz ramificação em code.

Uma negação global tem Retry-After, X-RateLimit-Scope e X-RateLimit-Global sozinhos.

Requisições de origem cruzada

A política de resposta CORS é uma lista de permissão de exatamente duas origens: o endpoint do aplicativo web configurado da implantação e seu endpoint de marketing. Uma requisição cujo Origin coincide com uma delas recebe Access-Control-Allow-Origin definido para aquela origem e Vary: Origin. Qualquer outra requisição, incluindo uma sem Origin, não recebe Access-Control-Allow-Origin dessa política. Requisições de origem cruzada com credenciais não estão habilitadas, portanto Access-Control-Allow-Credentials nunca é enviado.

Os caminhos abaixo são legíveis de qualquer origem. /v1/webhooks/{webhook_id}/{token} e /v1/webhooks/{webhook_id}/{token}/messages/{message_id} têm uma segunda política de origem cruzada que permite qualquer origem. Quatro dos métodos registrados neles recusam o cliente web oficial, e essa recusa é definida em Recusa de origem.

Obter descoberta de instância em /.well-known/fluxer, Obter documento OpenAPI em /v1/openapi.json e Obter geolocalização do cliente em /v1/ip definem Access-Control-Allow-Origin: * na própria operação. Uma requisição sem Origin ou fora da lista de permissão recebe *. Para uma origem permitida, a política substitui * por aquela origem exata e envia Vary: Origin.

Access-Control-Expose-Headers tem o valor X-Fluxer-Version, ETag. Todos os outros cabeçalhos de resposta do Decoding Chat — os cabeçalhos de rate limit e X-Request-ID incluídos — ficam ocultos para scripts de origem cruzada. Access-Control-Allow-Headers é Content-Type, Authorization, X-Requested-With, Accept-Language, X-Request-ID, If-None-Match, portanto um cliente de origem cruzada pode revalidar um ETag que recebeu.

Mutações no mesmo host exigem origem correspondente

Uma implantação em produção rejeita uma requisição não-GET cujo Host é web.fluxer.app ou web.canary.fluxer.app a menos que seu Origin seja exatamente https:// seguido desse mesmo host, retornando 403 INVALID_API_ORIGIN. Uma requisição enviada para o host da API não é afetada.

Objeto de resposta de erro

Uma resposta de erro JSON identifica o código de erro estável e uma mensagem legível por humanos. Uma operação pode adicionar outros membros de nível superior com detalhes estruturados. Erros documenta os registros de código, o mapeamento de fallback de status HTTP e o comportamento de localização.

Estrutura

Campo	Tipo	Descrição
code1	string	Código de erro de API estável e legível por máquina
message2	string	Descrição legível por humanos desta falha
errors?3	array[objeto de erro de validação]	Campos da requisição que falharam na validação

¹ Todo código é um nome simbólico em maiúsculas correspondendo a [A-Z][A-Z0-9_]*

² A redação varia por locale e tem como padrão o próprio código quando a falha não fornece mensagem

³ Presente em uma resposta INVALID_FORM_BODY e em qualquer outra falha com detalhe de campo

Exemplo

{
  "code": "MISSING_PERMISSIONS",
  "message": "Missing permissions"
}

O corpo não tem identificador de requisição. Um cliente correlaciona uma falha através do cabeçalho de resposta X-Request-ID.

Detalhe estruturado fica no nível superior

IP_AUTHORIZATION_REQUIRED tem ip_authorization_required, ticket, email e resend_available_in. SUDO_MODE_REQUIRED tem has_mfa e methods.

MISSING_OAUTH_SCOPE tem required_scope e RATE_LIMITED tem retry_after e global, onde global é true apenas em negação de bucket global. Cada operação que produz um desses membros o documenta. Um cliente DEVE tratar qualquer membro que não reconheça como ausente. Duas operações retornando o mesmo code podem ter membros extras diferentes, portanto um cliente DEVE ler os membros que sua própria operação documenta.

Objeto de erro de validação

Cada entrada identifica um campo de entrada que falhou. Uma resposta 400 cujo código de nível superior é INVALID_FORM_BODY tem o array em errors. Erros indica quais falhas o produzem.

Estrutura

Campo	Tipo	Descrição
path1	string	A localização do campo da requisição que falhou na validação
code?2	string	Código de validação estável e legível por máquina
message3	string	A descrição legível por humanos desta falha de validação

¹ Um campo aninhado é um caminho com pontos como embeds.0.title, e uma falha sem posição de campo usa o caminho literal root

² Presente sempre que a falha tem um código enumerado do registro de código de erro de validação

³ A mensagem localizada registrada para o code, com fallback para o próprio código, e uma string inglesa fixa em uma falha sem código

Exemplo

{
  "code": "INVALID_FORM_BODY",
  "message": "Invalid form body",
  "errors": [
    {"path": "name", "code": "BASE_TYPE_REQUIRED", "message": "This field is required"}
  ]
}

O Decoding Chat produz no máximo uma entrada para cada par distinto de path e code, portanto um campo que falha em vários critérios com o mesmo code aparece apenas uma vez.

Páginas de recursos

Página	Conteúdo
Erros	O envelope de erro, mapeamento de fallback de status e os registros de código de API e validação
Operações de autenticação	Registro, login, MFA, WebAuthn, SSO, verificação de e-mail, recuperação, sessões, autorização de IP, handoff de desktop
Gateway	Descoberta do endpoint principal do Gateway por bots e orçamento de início de sessão
Instância	Descoberta de instância, geolocalização de cliente, registro de chaves de limite, documento OpenAPI servido
OAuth2	Autorização, consentimento, troca de token, introspecção, revogação, autorizações concedidas
Aplicações	Gerenciamento de aplicação, conta de bot, segredo de cliente e token de bot, mais busca pública
Conexões	Início de conexão de conta externa, verificação, visibilidade e exclusão
Usuários	O objeto de usuário e as enumerações compartilhadas de usuário
Usuário atual	Recuperação da conta atual, mutação de perfil, ciclo de vida, aceitação de políticas, estado de IP autorizado
Configurações de usuário	Configurações de conta, notificação e privacidade, pastas de servidores, compartilhamento de atividade de voz
Configurações de usuário Protobuf	Cada mensagem de preferência de cliente estruturada e enumeração
Alterações de e-mail e senha	Os fluxos de substituição de credenciais com ticket
Autenticação multifator	TOTP, códigos de backup, credenciais WebAuthn, verificação sudo
Verificação de telefone	Verificação de telefone de saída e entrada
Relacionamentos	Solicitações de amizade, amizades, bloqueios, apelidos de relacionamento
Notas de usuário	Notas privadas vinculadas a IDs de usuário
Canais privados	Descoberta, criação, pré-carregamento e estado de fixação de DMs e DMs em grupo
Coleções de conteúdo do usuário	Menções recentes, mensagens salvas, exclusão assíncrona de mensagens
Inventário de presentes	Códigos de presente premium criados pela conta atual
Coletas de dados	Criação, status e download de coleta de dados
Estados de leitura	Confirmações de marca d’água de mensagem e contagem de menções
Memes	A coleção de imagens, vídeos e áudios salvos e resolução em lote de URLs de GIF
Temas	Criação de temas CSS personalizados compartilháveis
Canais	Objetos de canal, destinatários privados, substituições de permissão, slowmode, regiões RTC
Chamadas	Elegibilidade de chamada, seleção de região, toque e encerramento
Streams	Chaves de stream Go Live, regiões de stream, ciclo de vida de imagem de prévia
Sons de entrada	A coleção de sons de entrada, suas seleções por escopo e reprodução
Mensagens	Mensagens, anexos, embeds, histórico, confirmações, fixações, reações, digitação
Servidores	Objetos de servidor e operações de ciclo de vida
Canais de servidor	Listagem, criação, hierarquia, herança de permissão, posicionamento em lote
Membros de servidor	Objetos de membro, perfis, moderação de voz, propriedade, remoção, atribuição de cargos
Busca de membros de servidor	Filtros de busca indexada, ordenação, paginação, metadados de entrada suplementares
Moderação de servidor	Banimentos, banimentos temporários, substituição de banimento e os bloqueios de um banimento
Emojis de servidor	Objetos de emoji de servidor, uploads, alterações de metadados, exclusão
Stickers de servidor	Objetos de sticker de servidor, uploads, alterações de metadados, exclusão
Expressões	Leituras de metadados de emoji e sticker em ambos
Logs de auditoria de servidor	Entradas de auditoria, alvos tipados, contextos, alterações, filtros, o contrato de motivo de auditoria
Cargos e permissões	Flags de permissão, ordem de cálculo, objetos de cargo e ciclo de vida
Convites	Consulta, criação, aceitação, exclusão e geração de código de convite
Webhooks	Gerenciamento de webhook, execução de mensagem, callbacks GitHub, Slack e Instatus
Busca	Busca global autenticada de mensagens
Unfurl	Resolução autenticada de metadados de URL externa
Relatórios	Relatórios de segurança autenticados e notificações da Lei de Serviços Digitais com e-mail verificado