AIToolkit

> Documentação da API

Referência completa dos endpoints REST e comandos CLI do AI Toolkit.

Autenticação

A API suporta dois métodos de autenticação: JWT Bearer Token (para sessões web) e API Token (para CLI e integrações).

JWT Bearer Token (sessão web)
Authorization: Bearer <supabase-jwt>
API Token (CLI / integrações)
X-API-Token: aitk_xxxxxxxxxxxxxxxx

Base URL

api
https://ai-toolkit-henna.vercel.app/api/v1

Auth

Endpoints de autenticação e gerenciamento de tokens.

POST/api/v1/auth/cli-tokenJWT

Gerar token de API para autenticação do CLI.

Parâmetros
namestringobrigatórioNome descritivo do token.
Resposta
{ "token": "aitk_xxx...", "id": "uuid" }
GET/api/v1/auth/verifyAPI Token

Verificar se um token de API é válido.

Resposta
{ "valid": true, "user_id": "uuid" }

Artefatos

Endpoints para criar, buscar e gerenciar artefatos.

GET/api/v1/artifacts

Listar artefatos públicos com paginação.

Parâmetros
pagenumberNúmero da página (padrão: 1).
limitnumberItens por página (padrão: 20, máximo: 100).
typestringFiltrar por tipo (skill, mcp, template, config, hook).
Resposta
{ "data": [Artifact], "total": number, "page": number }
GET/api/v1/artifacts/search

Busca full-text de artefatos por query.

Parâmetros
qstringobrigatórioTermo de busca.
typestringFiltrar por tipo (skill, mcp, template, config, hook).
toolstringFiltrar por ferramenta alvo.
Resposta
{ "data": [Artifact], "total": number }
POST/api/v1/artifactsJWT

Criar um novo artefato no registry.

Parâmetros
namestringobrigatórioNome do artefato.
typestringobrigatórioTipo do artefato (skill, mcp, template, config, hook).
descriptionstringobrigatórioDescrição do artefato ou equipe.
visibilitystringVisibilidade (public, private, team). Padrão: public.
keywordsstring[]Palavras-chave para busca.
tool_targetsstring[]Ferramentas compatíveis.
Resposta
{ "data": Artifact }
GET/api/v1/artifacts/:scope/:name

Obter detalhes de um artefato específico.

Resposta
{ "data": Artifact }

Versões

Endpoints para publicar, baixar e consultar versões.

POST/api/v1/artifacts/:scope/:name/versionsJWT

Publicar nova versão com tarball (multipart/form-data).

Parâmetros
versionstringobrigatórioVersão semver (ex: 1.0.0).
tarballFileobrigatórioArquivo tarball (.tgz) com o conteúdo da versão.
changelogstringRegistro de mudanças desta versão.
Resposta
{ "data": ArtifactVersion }
GET/api/v1/artifacts/:scope/:name/versions/:version/download

Baixar tarball de uma versão específica.

Resposta
application/gzip (tarball)
GET/api/v1/artifacts/:scope/:name/stats

Obter estatísticas de downloads do artefato.

Resposta
{ "total_downloads": number, "weekly": [...] }

Equipes

Endpoints para criar e gerenciar equipes.

GET/api/v1/teamsJWT

Listar equipes do usuário autenticado.

Resposta
{ "data": [Team] }
POST/api/v1/teamsJWT

Criar uma nova equipe.

Parâmetros
slugstringobrigatórioIdentificador único da equipe.
namestringobrigatórioNome de exibição da equipe.
descriptionstringDescrição do artefato ou equipe.
Resposta
{ "data": Team }
GET/api/v1/teams/:slugJWT

Obter detalhes de uma equipe.

Resposta
{ "data": Team }
POST/api/v1/teams/:slug/membersJWT

Adicionar membro a uma equipe.

Parâmetros
usernamestringobrigatórioNome de usuário do membro.
rolestringFunção do membro (admin, member). Padrão: member.
Resposta
{ "data": TeamMember }

CLI (aitk)

O CLI permite gerenciar artefatos diretamente do terminal. Instale com npx ou globalmente.

$ aitk login

Autenticar via browser OAuth.

$ aitk search "query"

Buscar artefatos no registry.

$ aitk install scope/name

Instalar artefato no projeto.

$ aitk publish

Publicar artefato para o registry.

$ aitk init

Inicializar projeto ou aplicar template.

$ aitk list

Listar artefatos instalados.

$ aitk update

Atualizar artefatos instalados.

$ aitk team create slug

Gerenciar equipes.

Uso rápido
terminal
$ npx aitk-cli login

Shell Autocompletion

Bash
eval "$(aitk completions bash)"
Zsh
eval "$(aitk completions zsh)"
Fish
aitk completions fish | source

CI/CD — GitHub Action

Automatize a publicação de artefatos com o GitHub Action reutilizável.

Configuração
  1. 1.Gere um API Token no Dashboard
  2. 2.Adicione como secret AITK_API_TOKEN no repositório
  3. 3.Crie o aitk-artifact.json na raiz do artefato
  4. 4.Adicione o workflow ao repositório
Uso no workflow
.github/workflows/aitk-publish.yml
# .github/workflows/aitk-publish.yml
name: Publish to ai-toolkit
on:
release:
types: [published]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: tarcisiojr/ai-toolkit/.github/actions/aitk-publish@main
with:
api-token: ${{ secrets.AITK_API_TOKEN }}
directory: '.'
Inputs
api-tokenstringobrigatórioToken de API (obrigatório). Gere em Dashboard → API Tokens.
directorystringDiretório contendo o aitk-artifact.json.
accessstringVisibilidade do artefato (public, private, team).
teamstringSlug da equipe (necessário para access=team).
registry-urlstringURL do registry (padrão: https://ai-toolkit-henna.vercel.app).
Outputs
artifact-slugstringSlug completo do artefato publicado (scope/name@version).