API para bots

A API deixa outros bots usarem a Catita em um servidor: ler e somar XP, dar ou tirar dinheiro, criar chaves de cargos próprios ou gerar capturas FakeSS. O Discord não deixa um bot usar os comandos de outro, então isso é feito por HTTP em https://api.catita.gg/v1.

Criar uma chave

Em /settings > API > Criar chave (é preciso Gerenciar servidor).

• A chave é assim: ctk_1a2b3c4d_…. Ela aparece uma só vez: copie ao criar. A Catita só guarda uma impressão cifrada, então não consegue mostrá-la de novo.
• Cada chave vale só no seu servidor: nenhuma rota recebe o ID do servidor, ele vem da chave.
• Até 5 chaves por servidor, cada uma com nome, permissões, limites e validade.
• Girar gera um segredo novo e o anterior para de valer na hora. Revogar apaga a chave.
• Cada chave criada, girada ou revogada é avisada no canal de registros de moderação.

Guarde como um segredo: numa variável de ambiente, nunca no código nem numa mensagem.

Permissões

As chaves novas só leem. Marque em /settings o que o seu bot precisa:

Permissão	Deixa
keys:read	Ver as chaves de cargos próprios
keys:write	Criar chaves de cargos próprios (até 100 por dia por chave)
levels:read	Ler níveis e o ranking
levels:write	Somar ou tirar XP
economy:read	Ler saldos
economy:write	Dar ou tirar dinheiro da carteira
fakess	Gerar capturas

Autenticação

Envie a chave no cabeçalho Authorization:

curl https://api.catita.gg/v1/me \
  -H "Authorization: Bearer $CATITA_KEY"

const res = await fetch('https://api.catita.gg/v1/me', {
    headers: { Authorization: `Bearer ${process.env.CATITA_KEY}` }
});
console.log(await res.json());

Limites

• 60 pedidos por minuto por chave (capturas: 10). Cada resposta traz X-RateLimit-Remaining; ao passar, 429 com Retry-After.
• Limites diários por chave: por padrão 50.000 de XP e 1.000.000 de dinheiro, somado ou tirado. Mude em /settings > API > a chave > Topes. Eles reiniciam às 00:00 UTC, então uma chave vazada não quebra a economia.
• Muitas chaves erradas do mesmo IP o bloqueiam por 10 minutos.
• Corpos JSON de até 16 KB, com Content-Type: application/json. Campos que não existem são recusados.

Repetir sem duplicar

As escritas aceitam o cabeçalho Idempotency-Key (de 1 a 64 letras, números, - ou _). Se o seu bot repetir o mesmo pedido com a mesma chave em 24 horas, recebe a mesma resposta (com Idempotent-Replayed: true) e nada é aplicado duas vezes.

curl -X POST "https://api.catita.gg/v1/levels/123456789012345678/xp" \
  -H "Authorization: Bearer $CATITA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: premio-evento-42" \
  -d '{"amount": 500}'

Rotas

Todo ID de pessoa tem que ser de um membro do servidor da chave (não bots). ?instance= escolhe a instância de níveis ou de economia; sem ele, a principal.

Método e rota	Permissão	O que faz
GET /v1/me	—	O servidor, a chave, as permissões e quanto resta hoje de cada limite
GET /v1/levels/leaderboard?limit=&offset=	levels:read	Ranking (até 100 por página)
GET /v1/levels/{userId}	levels:read	Nível, XP, rebirths e posição
POST /v1/levels/{userId}/xp	levels:write	{ "amount": 500 } soma; um número negativo tira
GET /v1/economy/{userId}	economy:read	Carteira, banco e patrimônio
POST /v1/economy/{userId}/wallet	economy:write	{ "amount": 1000 } dá; negativo tira (nunca deixa saldo negativo)
GET /v1/customroles/keys	keys:read	As últimas 100 chaves de cargos próprios
POST /v1/customroles/keys	keys:write	{ "days": 30, "count": 5 } cria chaves (1 a 365 dias, 1 a 20 chaves)
POST /v1/fakess	fakess	Captura PNG de uma mensagem

Somar XP funciona como dar pelo /settings: sobe de nível, dá as recompensas e faz o anúncio. Cada mudança de dinheiro fica no livro contábil do servidor como api:<nome da chave>.

Exemplo: premiar alguém com dinheiro

const res = await fetch(`https://api.catita.gg/v1/economy/${userId}/wallet`, {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.CATITA_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': `premio-${interaction.id}`
    },
    body: JSON.stringify({ amount: 1000 })
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(`Agora tem ${data.wallet}`);

Capturas FakeSS

{
  "authorId": "123456789012345678",
  "content": "oi **pessoal**",
  "reply": { "authorId": "234567890123456789", "content": "tudo bem?" },
  "image": "https://cdn.discordapp.com/attachments/…/foto.png",
  "theme": "dark"
}

• O autor tem que ser membro do servidor: nome, avatar e cor vêm do Discord e não podem ser inventados.
• content até 2000 caracteres e 10 menções; theme é dark, darker ou light.
• image só do CDN do Discord (cdn.discordapp.com ou media.discordapp.net).
• Devolve um PNG. Com muitas ao mesmo tempo, 503 com Retry-After.

Erros

Sempre no mesmo formato:

{ "error": { "code": "missing_scope", "message": "This key needs the \"levels:write\" scope." } }

Status	Quando
400	Corpo ou parâmetro inválido
401	Chave faltando, errada, expirada ou revogada
403	A chave não tem essa permissão, ou a Catita não está mais no servidor
404	A pessoa não é membro, ou a instância não existe
409	Não dá para fazer agora (níveis desligados, saldo insuficiente…)
422	Idempotency-Key repetida com outro pedido, ou uma imagem que não deu para ler
429	Limite por minuto ou diário
503	Ocupado: tente de novo após Retry-After

A especificação completa está em openapi.json. Para receber avisos quando algo acontece, veja Eventos.