AI Toolkit - Registry de Artefatos para IA

> API Documentation

Complete reference for the AI Toolkit REST endpoints and CLI commands.

Authentication

The API supports two authentication methods: JWT Bearer Token (for web sessions) and API Token (for CLI and integrations).

JWT Bearer Token (web session)

Authorization: Bearer <supabase-jwt>

API Token (CLI / integrations)

X-API-Token: aitk_xxxxxxxxxxxxxxxx

Base URL

api

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

Auth

Authentication and token management endpoints.

POST/api/v1/auth/cli-tokenJWT

Generate an API token for CLI authentication.

Parameters

namestringrequiredDescriptive token name.

Response

{ "token": "aitk_xxx...", "id": "uuid" }

GET/api/v1/auth/verifyAPI Token

Verify if an API token is valid.

Response

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

Artifacts

Endpoints to create, search and manage artifacts.

GET/api/v1/artifacts

List public artifacts with pagination.

Parameters

pagenumberPage number (default: 1).

limitnumberItems per page (default: 20, max: 100).

typestringFilter by type (skill, mcp, template, config, hook).

Response

{ "data": [Artifact], "total": number, "page": number }

GET/api/v1/artifacts/search

Full-text search for artifacts by query.

Parameters

qstringrequiredSearch term.

typestringFilter by type (skill, mcp, template, config, hook).

toolstringFilter by target tool.

Response

{ "data": [Artifact], "total": number }

POST/api/v1/artifactsJWT

Create a new artifact in the registry.

Parameters

namestringrequiredArtifact name.

typestringrequiredArtifact type (skill, mcp, template, config, hook).

descriptionstringrequiredArtifact or team description.

visibilitystringVisibility (public, private, team). Default: public.

keywordsstring[]Keywords for search.

tool_targetsstring[]Compatible tools.

Response

{ "data": Artifact }

GET/api/v1/artifacts/:scope/:name

Get details of a specific artifact.

Response

{ "data": Artifact }

Versions

Endpoints to publish, download and query versions.

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

Publish new version with tarball (multipart/form-data).

Parameters

versionstringrequiredSemver version (e.g., 1.0.0).

tarballFilerequiredTarball file (.tgz) with version content.

changelogstringChangelog for this version.

Response

{ "data": ArtifactVersion }

GET/api/v1/artifacts/:scope/:name/versions/:version/download

Download tarball of a specific version.

Response

application/gzip (tarball)

GET/api/v1/artifacts/:scope/:name/stats

Get artifact download statistics.

Response

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

Teams

Endpoints to create and manage teams.

GET/api/v1/teamsJWT

List teams of the authenticated user.

Response

{ "data": [Team] }

POST/api/v1/teamsJWT

Create a new team.

Parameters

slugstringrequiredUnique team identifier.

namestringrequiredTeam display name.

descriptionstringArtifact or team description.

Response

{ "data": Team }

GET/api/v1/teams/:slugJWT

Get details of a team.

Response

{ "data": Team }

POST/api/v1/teams/:slug/membersJWT

Add a member to a team.

Parameters

usernamestringrequiredMember username.

rolestringMember role (admin, member). Default: member.

Response

{ "data": TeamMember }

CLI (aitk)

The CLI lets you manage artifacts directly from the terminal. Install with npx or globally.

$ aitk login

Authenticate via browser OAuth.

$ aitk search "query"

Search artifacts in the registry.

$ aitk install scope/name

Install artifact into project.

$ aitk publish

Publish artifact to the registry.

$ aitk init

Initialize project or apply template.

$ aitk list

List installed artifacts.

$ aitk update

Update installed artifacts.

$ aitk team create slug

Manage teams.

Quick start

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

Automate artifact publishing with the reusable GitHub Action.

Setup

1.Generate an API Token in the Dashboard
2.Add it as AITK_API_TOKEN secret in your repository
3.Create aitk-artifact.json in your artifact root
4.Add the workflow to your repository

Workflow usage

.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-tokenstringrequiredAPI token (required). Generate at Dashboard → API Tokens.

directorystringDirectory containing aitk-artifact.json.

accessstringArtifact visibility (public, private, team).

teamstringTeam slug (required for access=team).

registry-urlstringRegistry URL (default: https://ai-toolkit-henna.vercel.app).

Outputs

artifact-slugstringFull slug of published artifact (scope/name@version).