API Reference — Skill Scanner

API Reference

The Skill Scanner API Server provides a REST interface for uploading and scanning agent skill packages. It enables integration with web applications, CI/CD pipelines, and service-to-service workflows.

Starting the Server

# Default: localhost:8000
skill-scanner-api

# Custom port
skill-scanner-api --port 8080

# Development mode with auto-reload
skill-scanner-api --reload

# Custom host and port
skill-scanner-api --host 127.0.0.1 --port 9000

Or programmatically:

from skill_scanner.api.api_server import run_server

run_server(host="127.0.0.1", port=8000, reload=False)

Endpoints

POST /scan

Scan a skill by local directory path.

curl -X POST http://localhost:8000/scan \
  -H "Content-Type: application/json" \
  -d '{
    "skill_directory": "/path/to/skill",
    "use_behavioral": true,
    "use_llm": false,
    "policy": "balanced"
  }'

Request body:

POST /scan-upload

Upload a skill as a ZIP file and scan it.

curl -X POST http://localhost:8000/scan-upload \
  -F "file=@my-skill.zip" \
  -F "use_behavioral=true"

Upload guardrails:

POST /scan-batch

Start an asynchronous batch scan. Returns a scan_id for polling.

curl -X POST http://localhost:8000/scan-batch \
  -H "Content-Type: application/json" \
  -d '{
    "skills_directory": "/path/to/skills",
    "recursive": true,
    "use_behavioral": true
  }'

Response:

{
  "scan_id": "abc123",
  "status": "pending"
}

GET /scan-batch/{scan_id}

Poll batch scan status and retrieve results when complete.

curl http://localhost:8000/scan-batch/abc123

Status values: pending, running, completed, failed

GET /health

Health check with analyzer availability.

curl http://localhost:8000/health

GET /analyzers

List all available analyzers and their activation requirements.

curl http://localhost:8000/analyzers

Interactive Documentation

When the server is running:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Configuration

The API server uses the same environment variables as the CLI:

export SKILL_SCANNER_LLM_API_KEY=your_key
export SKILL_SCANNER_LLM_MODEL=anthropic/claude-sonnet-4-20250514
export AI_DEFENSE_API_KEY=your_key

Server bind settings are controlled by CLI flags (--host, --port).

CORS Configuration

For web application integration, add CORS middleware:

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from skill_scanner.api.router import router

app = FastAPI()
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_methods=["*"],
    allow_headers=["*"],
)
app.include_router(router)

Performance

• /scan-batch runs as a background task, polled by scan_id
• Batch status stored in an in-memory bounded cache (max 1000 entries, 1 hour TTL)
• /scan and /scan-upload execute via threadpool workers to avoid blocking the event loop
• Throughput depends on analyzer mix, model/provider latency, and uploaded archive size

When to Use CLI vs API

See API Rationale for more detail.