API do Énóis

Filosofia

A API existe para ampliar o acesso à informação e automatizar processos — nunca para fabricar interação social. Publicar conteúdo automaticamente (IA, bots, integrações) é proibido; criar e agendar posts pela funcionalidade oficial, com você no controle, é permitido.

Começando

# 1. Autentique-se (o mesmo token que o app usa)
curl -X POST https://enois.ia.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@exemplo.com","password":"senha-forte-1"}'

# 2. Autentique cada chamada com a sessao
curl https://enois.ia.br/api/me -H "X-Session-Token: <token>"

GET https://enois.ia.br/api/feed/posts/$POST_ID/comments?limit=20
GET ...?cursor=<nextCursor>&limit=20

{"code":"UNAUTHENTICATED","message":"Sessao invalida ou expirada.",
 "timestamp":"2026-10-17T14:20:39Z"}

Autenticação e conta

A sessão do Énóis é o mesmo token que o app usa. Cadastro nasce pendente de confirmação de e-mail; login responde o token que autentica todas as outras rotas pelo header X-Session-Token. Contas com segundo fator respondem um desafio (202) em vez do token.

curl -X POST https://enois.ia.br/api/auth/signup \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-1" \
  -d '{"name":"Ada","email":"ada@exemplo.com","password":"senha-forte-1","acceptedTerms":true}'

201 Created
{"id":"user_…","email":"ada@exemplo.com","emailVerified":false}

curl -X POST https://enois.ia.br/api/auth/email/verify \
  -H "Content-Type: application/json" \
  -d '{"token":"<token-do-email>"}'

curl -X POST https://enois.ia.br/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: login-1" \
  -d '{"email":"ada@exemplo.com","password":"senha-forte-1"}'

200 OK
{"token":"sess_…","refreshToken":"…","user":{"id":"user_…","name":"Ada","username":"ada"}}

200 OK
{"token":"sess_…","refreshToken":"…"}

Feed e publicações

Leitura de publicação e comentários é pública (links compartilhados abrem sem conta). Escrever exige sessão. Posts podem ter mídia (mediaIds) e página em HTML (type PAGE, pageHtml) — a página renderiza em quadro isolado, sem script.

curl "https://enois.ia.br/api/feed?tab=FOR_YOU&limit=20" \
  -H "X-Session-Token: $TOKEN"

200 OK
{"items":[{"id":"post_…","type":"INSIGHT","content":"…","counters":{"reactions":26,"comments":23,"saves":3,"shares":4},"createdAt":"2026-10-15T02:16:48Z"}],"nextCursor":"2026-10-15T02:16:48Z"}

curl https://enois.ia.br/api/feed/posts/post_396a12bc2bc54ad3966829c751acb021

200 OK
{"id":"post_396a12bc…","authorId":"user_…","authorUsername":"aminadojava",
 "type":"INSIGHT","content":"Pessoal. Post pra coletar ideias…","tags":[],"mediaIds":[],
 "createdAt":"2026-10-15T02:16:48Z",
 "counters":{"reactions":26,"comments":23,"saves":3,"shares":4},
 "currentUserReaction":null,"communityId":null,"community":null}

curl "https://enois.ia.br/api/users/aminadojava/posts?limit=10"

curl -X POST https://enois.ia.br/api/feed/posts \
  -H "X-Session-Token: $TOKEN" -H "Idempotency-Key: post-1" \
  -H "Content-Type: application/json" \
  -d '{"type":"INSIGHT","content":"Texto do post","tags":["java"],"mediaIds":[],"mentionedUserIds":[]}'

201 Created
{"id":"post_…","content":"Texto do post","createdAt":"…"}

curl -X POST https://enois.ia.br/api/feed/posts/$POST_ID/comments \
  -H "X-Session-Token: $TOKEN" -H "Idempotency-Key: c-1" \
  -H "Content-Type: application/json" \
  -d '{"content":"Concordo!","parentCommentId":null,"mediaIds":[],"mentionedUserIds":[]}'

201 Created
{"id":"comment_…","postId":"post_…","content":"Concordo!","mediaIds":[],"createdAt":"…"}

curl "https://enois.ia.br/api/feed/posts/$POST_ID/comments?limit=20"

200 OK
{"items":[{"id":"comment_…","authorUsername":"sergio-de-souza-tomas",
  "content":"Opa eu notei que agora dá pra editar…","mediaIds":[],"createdAt":"2026-10-15T22:03:52Z"}],
 "nextCursor":"2026-10-15T22:03:52Z"}

curl -X POST https://enois.ia.br/api/feed/posts/$POST_ID/reactions \
  -H "X-Session-Token: $TOKEN" -H "Idempotency-Key: r-1" \
  -H "Content-Type: application/json" -d '{"type":"INSIGHTFUL"}'

Busca

Busca unificada por pessoas, publicações, comunidades e vagas.

curl "https://enois.ia.br/api/search?q=java&limit=10"

200 OK
{"items":[{"id":"user_…","type":"users","title":"JavaScript-chan","subtitle":"…","image":"…"}],
 "nextCursor":null}

Perfis e ranking

Perfis públicos com experiência, formação, certificações e emblema. O ranking é calculado pela plataforma (reputação/atividade) e é público.

curl https://enois.ia.br/api/users/aminadojava

200 OK
{"id":"user_…","username":"aminadojava","name":"melissa monfre dos santos",
 "headline":"…","company":"…","skills":[…],"bioHtml":null,"bannerHtml":null,"openToWork":false}

curl https://enois.ia.br/api/profile/ranking

200 OK
[{"id":"user_…","username":"lucas-matheus-florentino","name":"Lucas Matheus Florentino","skills":[…]}]

Comunidades

Listagem, detalhe e feed de comunidade são públicos; entrar, publicar e administrar pedem sessão. A capa pode ser foto (cover) ou HTML/CSS (bannerHtml) — mesma tubulação da capa de perfil.

curl "https://enois.ia.br/api/communities?limit=10"

200 OK
{"items":[{"id":"community_…","name":"Muita IA pouco $","description":"…","members":1,
 "topic":"TECNOLOGIA","cover":null,"bannerHtml":null,"joined":false}],"nextCursor":null}

Vagas

Vagas internas (criadas na plataforma) e externas convivem na mesma listagem. Externas têm id com prefixo ext_, selo de plataforma (sourcePlatform) e URL da origem (sourceUrl) — o redirecionamento é sempre para quem publicou a vaga. Busca booleana: AND, OR, NOT, "frase exata" e parênteses no parâmetro query.

curl "https://enois.ia.br/api/jobs?query=java%20AND%20remoto&limit=20"

200 OK
{"items":[{"id":"ext_Remotive_2091144","title":"Content Reviewer - United States","company":"TELUS Digital",
 "location":"USA","postedAt":"2026-10-17T04:00:49Z","sourcePlatform":"Remotive",
 "sourceUrl":"https://remotive.com/remote-jobs/…"}],"nextCursor":null}

Eventos

Vitrine de eventos profissionais. Eventos passados saem da vitrine e recusam RSVP; presença vira número agregado após 24h.

200 OK
{"items":[{"id":"event_…","title":"…","date":"2029-12-31","time":"23:59","format":"ONLINE","attendees":2}]}

Mentoria

Mentores publicam horários livres; quem quer aprender pede sessão em um slot.

200 OK
{"items":[{"id":"mentor_…","expertise":["Pentest","RedTeam","Certificações"]}]}

Estatísticas

Números públicos e agregados da rede — sem dado pessoal.

curl https://enois.ia.br/api/stats/community

200 OK
{"activeUsers":1031,"totalUsers":1370,"windowDays":30,"computedAt":"2026-10-17T14:20:39Z"}

Rede (conexões e bloqueios)

Conexões bidirecionais com aceite; bloqueio é permanente e esconde os dois lados do feed, comentários, busca e sugestões.

Mensagens

Conversas diretas e de comunidade. Tudo aqui pede sessão — nada de mensagens é público.

Notificações e push

Notificações no app e no celular (Web Push). Cada notificação traz href de destino no formato /api/….

Mídia

Upload em três passos: (1) pede a assinatura; (2) sobe o arquivo no endereço que a resposta indicar (S3 = PUT direto na signedUrl com os headers dados; ImageKit = multipart); (3) usa o mediaId no post/comentário/perfil. Ninguém precisa de chave de terceiros — a plataforma assina.

curl -X POST https://enois.ia.br/api/media/uploads \
  -H "X-Session-Token: $TOKEN" -H "Idempotency-Key: up-1" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"media/abc/foto.png","mimeType":"image/png","size":10240,"purpose":"POST_IMAGE"}'

201 Created
{"id":"media_…","cdnUrl":"https://…","uploadUrl":"https://…(assinada)","provider":"S3","uploadHeaders":{…}}

Denúncias, moderação e recursos

Qualquer pessoa autenticada pode denunciar conteúdo; cada denúncia avisa o suporte por e-mail. Um sistema automático pré-tri por IA e, só em violação grave e inequívoca, restringe o autor — que pode recorrer. A decisão final é sempre humana: recurso aceito remove a restrição; negado converte em banimento.

curl -X POST https://enois.ia.br/api/reports \
  -H "X-Session-Token: $TOKEN" -H "Idempotency-Key: rep-1" \
  -H "Content-Type: application/json" \
  -d '{"targetType":"POST","targetId":"post_…","reason":"SCAM","description":"Parece golpe de investimento"}'

201 Created
{"id":"report_…","targetType":"POST","reason":"SCAM","status":"PENDING","createdAt":"…"}

200 OK
{"sanctions":[{"id":"sanc_…","type":"RESTRICTION","status":"ACTIVE","reason":"…","createdAt":"…"}],
 "appeals":[{"id":"appl_…","status":"PENDING","message":"…"}]}

curl -X POST https://enois.ia.br/api/me/sanctions/appeals \
  -H "X-Session-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"message":"Foi discussão técnica, não discriminação."}'

Suporte e conta

Canal de suporte responde por e-mail e fica no painel admin; exclusão de conta anonimiza o conteúdo (nada de dado pessoal órfão).

Temas (galeria da comunidade)

Pacotes de TOKENS validados por schema e com gate de contraste (>= 4.5:1) — sem CSS livre. O pacote é JSON; a instalação aplica na hora e a conta guarda o tema como preferência.

[{"id":"tema_…","name":"Bruma Silenciosa","description":"…","packageJson":"{"palette":…}","modeDefault":"light","installs":12,"createdAt":"2026-10-17T18:20:11Z"}]

{"name":"Meu Tema","description":"Cores da minha comunidade","modeDefault":"light",
 "packageJson":"{"palette":{"background":"#f5e6c8",…}}"}

{"id":"tema_…","status":"PUBLISHED"}

Faísca (carteira e cotação)

A moeda interna é FRACIONADA: o ledger inteiro conta milésimos — 1 faísca = 1.000 mf (como os centavos do real). A cotação de REFERÊNCIA em BRL é publicada pela plataforma e financia a remuneração de criadores; não é câmbio — comprar faísca com dinheiro não existe. Transferências são estilo Pix: por username, instantâneas e irreversíveis, com Idempotency-Key obrigatória.

{"brlCents":1,"escala":1000,"atualizadaEm":"2026-10-18T10:00:00Z",
 "historico":[{"brlCents":1,"em":"2026-10-18T10:00:00Z"}]}

{"brlCents":2,"note":"reajuste de referência"}

{"brlCents":2,"em":"2026-10-18T10:05:00Z"}

{"balance":105000,"escala":1000,"cotacaoBrlCents":1,"chave":"ada-silva",
 "entries":[{"amount":5000,"kind":"REWARD","message":"Presença diária","createdAt":"2026-10-18T10:00:00Z"},
 {"amount":100000,"kind":"AIRDROP","message":"Distribuição inicial","createdAt":"2026-10-18T09:59:59Z"}]}

{"toUsername":"joao-silva","amount":1500,"message":"pelo mockup lindo"}

{"status":"SENT","amount":1500,"toUsername":"joao-silva"}

Jogos (agregador)

O Énóis NÃO hospeda jogos: o criador envia o LINK de onde o jogo já está publicado (itch.io, site próprio), a moderação revisa, e o jogo roda EMBUTIDO num quadro isolado no app. A página do criador é pública em /games/{username}.

[{"id":"game_…","userId":"user_…","username":"ada-silva","slug":"kawaii-survivors","title":"Kawaii Survivors",
 "description":"Survivor fofo com pixel art.","url":"https://ada.itch.io/kawaii","tags":"arcade,pixel","status":"PUBLISHED",
 "submittedAt":"2026-10-18T10:00:00Z"}]

{"slug":"kawaii-survivors","title":"Kawaii Survivors","url":"https://ada.itch.io/kawaii",
 "description":"…","tags":"arcade,pixel"}

{"id":"game_…","slug":"kawaii-survivors","status":"SUBMITTED"}

{"texto":"Peguei nível 10 na fazendinha!","mediaIds":["media_…"]}

{"postId":"post_…","status":"SHARED"}

{"note":"carrega e roda"}

{"id":"game_…","status":"PUBLISHED"}

{"note":"o jogo não carrega"}

{"id":"game_…","status":"REJECTED"}

Marketplace (temas por faíscas, com escrow)

O criador lista um tema próprio por um preço em faíscas; a compra fica em ESCROW — as faíscas ficam retidas até o comprador confirmar (7 dias; liberação automática depois), e o criador recebe o preço menos 10% de taxa. Reembolso devolve 100%. Valores em milésimos de faísca.

[{"id":"mkt_…","sellerId":"user_…","itemKind":"THEME","itemId":"tema_…","title":"Tema à Venda",
 "price":40000,"status":"ACTIVE","createdAt":"2026-10-18T10:00:00Z"}]

{"itemId":"tema_…","title":"Tema à Venda","price":40000}

{"id":"mkt_…","status":"ACTIVE"}

{"purchaseId":"mcmp_…","state":"HELD","price":40000}

{"purchaseId":"mcmp_…","state":"RELEASED"}

{"purchaseId":"mcmp_…","state":"REFUNDED"}

Serviços freelance (com escrow)

Duas faces: OFERTAR (o profissional publica o que faz, modelo Fiverr — teto de 5 abertas por conta) e PEDIR (a demanda publica o que precisa, com orçamento em faixa e entregáveis OBRIGATÓRIOS — a lição dos microprojetos). O contrato nasce HELD: entrega → aceite libera 90%; reembolso devolve 100%.

{"ofertas":[{"id":"sl_…","category":"design","title":"Logo simples","price":30000,"deliveryDays":5,
 "deliverables":"SVG + PNG","status":"ACTIVE"}],
 "pedidos":[{"id":"sr_…","category":"código","title":"Página institucional","budgetMin":40000,"budgetMax":80000,
 "deliverables":"HTML + CSS publicados","status":"OPEN"}]}

{"category":"design","title":"Logo simples para o seu time","description":"Duas rodadas de ajuste…",
 "deliverables":"SVG + PNG em três tamanhos","price":30000,"deliveryDays":5}

{"id":"sl_…","status":"ACTIVE"}

{"contractId":"sc_…","state":"HELD"}

{"category":"código","title":"Página institucional","description":"…","deliverables":"HTML + CSS publicados",
 "budgetMin":40000,"budgetMax":80000}

{"id":"sr_…","status":"OPEN"}

{"message":"Entrego em uma semana, com revisão.","price":50000}

{"id":"sp_…","status":"SENT"}

{"proposalId":"sp_…"}

{"contractId":"sc_…","state":"HELD"}

{"note":"SVG e PNG entregues no link X"}

{"contractId":"sc_…","state":"HELD"}

{"contractId":"sc_…","state":"RELEASED"}

{"contractId":"sc_…","state":"REFUNDED"}

Blogs

Um blog por pessoa, em /blog/{username}. Os posts do blog ficam fora do feed principal; quem assina o blog recebe os posts novos por e-mail (se optou por isso).

curl https://enois.ia.br/api/blogs/ada

200 OK
{"slug":"ada","username":"ada","title":"Blog da Ada","posts":[…]}

Grupos

Espaços privados com feed, tópicos e moderação próprios, independentes das comunidades. Entrada aberta entra na hora; entrada por pedido gera um pendente que os administradores aprovam ou recusam.

Serviços

Ofertas de serviço entre pessoas da rede, com orçamento, contrato e entrega. O fluxo vai de pedido aberto a proposta, escolha, entrega e aceite (ou reembolso integral).

Jogos diários

Três jogos que trocam a todo dia (Blocos, Palavras e Labirinto), com ranking geral e prêmios em faíscas.

Mostrar uma publicação do Énóis em outro site

Um post público serve qualquer widget: leitura sem credencial, contadores e comentários inclusos. Roteiro de três chamadas, sem autenticação.

1. 11. Busque o post (autor, contadores, mídia):

   curl https://enois.ia.br/api/feed/posts/post_396a12bc2bc54ad3966829c751acb021

2. 22. Busque a primeira página de comentários:

   curl "https://enois.ia.br/api/feed/posts/post_396a12bc2bc54ad3966829c751acb021/comments?limit=20"

3. 33. Pagina enquanto houver nextCursor (mande o valor de volta em ?cursor=):

   curl "https://enois.ia.br/api/feed/posts/post_396a12bc2bc54ad3966829c751acb021/comments?cursor=<nextCursor>&limit=20"

4. 4Imagens de perfil e mídia vêm com caminho relativo — prefixe com https://enois.ia.br para renderizar.

Mural de vagas com link para a origem

A listagem junta vagas internas e agregadores públicos (Remotive, Jobicy, RemoteOK, Himalayas). Vagas externas têm id com prefixo ext_ e sempre uma sourceUrl — o clique vai para quem publicou a vaga.

1. 11. Liste com busca booleana no título:

   curl "https://enois.ia.br/api/jobs?query=java%20AND%20(remoto%20OR%20h%C3%ADbrido)&limit=20"

2. 22. Separe as externas pelo prefixo do id e use a origem:

   # externa: id "ext_Remotive_2091144" -> sourcePlatform "Remotive" + sourceUrl para redirecionar
   # interna: id "job_…"      -> aplicação pela própria API (requer sessão)

3. 33. Pagine com nextCursor; filtros estruturais (type/level/location/skills) limitam a vagas internas.

Feed de uma comunidade

Conteúdo de uma comunidade específica, sem credencial — útil para site do evento ou da turma.

1. 11. Encontre a comunidade:

   curl "https://enois.ia.br/api/communities?limit=20"

2. 22. Puxe o feed dela:

   curl "https://enois.ia.br/api/communities/$COMMUNITY_ID/feed?limit=20"

3. 33. Detalhe de cada post e comentários: mesmos endpoints do caso do widget.

Publicar com imagem (com sessão)

Upload em três passos e depois a publicação. Funciona igual para comentário (mediaIds) e avatar.

1. 11. Autentique-se e guarde o token:

   curl -X POST https://enois.ia.br/api/auth/login -H "Content-Type: application/json" \
     -d '{"email":"ada@exemplo.com","password":"senha-forte-1"}'

2. 22. Peça a assinatura do upload:

   curl -X POST https://enois.ia.br/api/media/uploads -H "X-Session-Token: $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"fileName":"media/abc/foto.png","mimeType":"image/png","size":10240,"purpose":"POST_IMAGE"}'

3. 33. Suba o arquivo no uploadUrl que veio na resposta (PUT direto na S3 assinada, ou multipart no ImageKit).

4. 44. Publique com o mediaId:

   curl -X POST https://enois.ia.br/api/feed/posts -H "X-Session-Token: $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"type":"INSIGHT","content":"Olha isso","mediaIds":["media_…"]}'

Faísca: transferência estilo Pix e a cotação

A moeda interna é fracionada (1 faísca = 1.000 mf) e transferida por username, com Idempotency-Key. A cotação de referência em BRL é pública; o total em circulação não é.

1. 11. A cotação de referência (pública, sem token):

   curl https://enois.ia.br/api/coin/cotacao

2. 22. Abra a carteira (a primeira abertura executa o genesis idempotente):

   curl https://enois.ia.br/api/carteira -H "X-Session-Token: $TOKEN"

3. 33. Envie 1,5 faísca (1.500 mf) para outra pessoa:

   curl -X POST https://enois.ia.br/api/carteira/transferencias -H "X-Session-Token: $TOKEN"   -H "Idempotency-Key: pagamento-01" -H "Content-Type: application/json"   -d '{"toUsername":"joao-silva","amount":1500,"message":"pelo mockup lindo"}'

4. 4Repetir a chamada com a MESMA chave não duplica (replay do Pix). Transferência é irreversível — reversão só por moderação, com lançamento espelho no ledger.

Escrow de ponta a ponta: comprar um tema

Compra em faíscas com escrow: as faíscas ficam retidas até o comprador confirmar (7 dias) — o criador recebe 90% e a plataforma fica com 10%.

1. 11. Veja o que está à venda:

   curl https://enois.ia.br/api/marketplace

2. 22. Compre (as faíscas saem da carteira e ficam retidas):

   curl -X POST https://enois.ia.br/api/marketplace/mkt_…/buy -H "X-Session-Token: $TOKEN"

3. 33. Confirme depois de instalar o tema (libera 90% ao criador):

   curl -X POST https://enois.ia.br/api/marketplace/purchases/mcmp_…/confirm -H "X-Session-Token: $TOKEN"

4. 4Arrependeu dentro de 7 dias? /refund devolve 100%. Sem decisão, a liberação para o criador é automática.

Jogos: compartilhar conquista no feed

O jogo roda num iframe de OUTRA origem, sem sessão nenhuma. Para oferecer "compartilhar conquista", ele fala com a página pai por postMessage; a página valida a origem, mostra a prévia e publica com o CLIQUE do jogador — o jogo nunca publica sozinho.

1. 11. Dentro do jogo (iframe), pede o compartilhamento:

   window.parent.postMessage({
     type: "enois:share",
     texto: "Peguei nível 10 na fazendinha!",
     imagem: "data:image/png;base64,…"   // opcional
   }, "*");

2. 22. A página do Énóis valida a origem, mostra a prévia ao jogador e, no clique, sobe a imagem pela mídia e publica:

   curl -X POST https://enois.ia.br/api/games/game_…/compartilhar -H "X-Session-Token: $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"texto":"Peguei nível 10 na fazendinha!","mediaIds":["media_…"]}'

3. 3O post nasce no feed com as tags game + o slug do jogo. Teto de 12/dia (429 SHARE_LIMIT). Protocolo completo em docs/GAMES.md.

Painel de saúde da rede

Números públicos, agregados, sem dado pessoal — prontos para dashboard ou relatório.

1. 11. Atividade da rede:

   curl https://enois.ia.br/api/stats/community

2. 22. Ranking de perfis:

   curl https://enois.ia.br/api/profile/ranking

3. 33. Pulso por tema:

   curl "https://enois.ia.br/api/search?q=ia&limit=50"

Integração de moderação (admins)

Para ferramentas do próprio time: a fila de denúncias e de recursos é acessível por sessão de administrador (REDE_ADMIN_EMAILS). O banimento só acontece por recurso negado — decisão sempre humana.

1. 11. Veja a fila de denúncias (já com a pré-triagem da IA no campo ai_triage):

   curl "https://enois.ia.br/api/admin/reports?limit=30" -H "X-Session-Token: $ADMIN_TOKEN"

2. 22. Decida uma denúncia:

   curl -X POST https://enois.ia.br/api/admin/reports/$REPORT_ID/approve -H "X-Session-Token: $ADMIN_TOKEN" \
     -H "Content-Type: application/json" -d '{"note":"confirmado"}'

3. 33. Julgue recursos (aprovar libera; negar ban):

   curl -X POST https://enois.ia.br/api/admin/appeals/$APPEAL_ID/approve -H "X-Session-Token: $ADMIN_TOKEN"

Estado e contato