#API Reference

Agent Skill Hub provides a REST API for programmatic access to skills and skillsets.

#Overview

• Base URL: https://agentskillhub.dev/api/v1/
• Authentication: Bearer token (for authenticated endpoints)
• Content-Type: application/json

#Authentication

#Obtaining a Token

Use the CLI to authenticate:

skhub login

This stores a token in ~/.skhub/auth.json.

#Using Tokens

Include the token in the Authorization header:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://agentskillhub.dev/api/v1/cli/me

#Public Endpoints

These endpoints don't require authentication.

#Get Skill

GET /api/v1/skills/:slug

Retrieve skill metadata and manifest.

Parameters:

• slug — Skill identifier (URL-encoded if containing /)

Response:

{
  "slug": "my-org/data-analysis",
  "name": "Data Analysis",
  "description": "Analyze CSV and JSON data",
  "version": "1.2.0",
  "author": "my-org",
  "categories": ["data"],
  "tags": ["csv", "json"],
  "manifest": {
    "name": "Data Analysis",
    "capabilities": [...]
  },
  "content": "# Data Analysis\n\nInstructions..."
}

#Get Skill Version

GET /api/v1/skills/:slug/versions/:version

Retrieve a specific skill version.

Parameters:

• slug — Skill identifier
• version — Version string (e.g., 1.2.0)

#Get Skillset

GET /api/v1/skillsets/:username/:slug

Retrieve a skillset and its items.

Parameters:

• username — Skillset owner's username
• slug — Skillset slug

Response:

{
  "slug": "devops-toolkit",
  "name": "DevOps Toolkit",
  "description": "Essential DevOps skills",
  "owner": "team",
  "skills": [
    {
      "slug": "team/docker-manager",
      "name": "Docker Manager",
      "version": "1.0.0"
    },
    {
      "slug": "team/k8s-helper",
      "name": "Kubernetes Helper",
      "version": "2.1.0"
    }
  ]
}

#Analyze Repository

POST /api/v1/repos/analyze

Analyze a GitHub repository for importable skills.

Request Body:

{
  "repoUrl": "https://github.com/user/repo"
}

Response:

{
  "skills": [
    {
      "path": "data-analysis/SKILL.md",
      "name": "Data Analysis",
      "slug": "data-analysis",
      "valid": true
    }
  ]
}

#Import Repository

POST /api/v1/repos/import

Import selected skills from a GitHub repository.

Request Body:

{
  "repoUrl": "https://github.com/user/repo",
  "skills": ["data-analysis", "api-client"]
}

#Import Stream

POST /api/v1/repos/import-stream

Stream import progress as NDJSON (Newline Delimited JSON).

#Authenticated Endpoints

These endpoints require a valid API token.

#Get Current User

GET /api/v1/cli/me

Retrieve current user and token metadata.

Response:

{
  "user": {
    "id": "user_123",
    "username": "johndoe",
    "email": "[email protected]"
  },
  "token": {
    "id": "token_456",
    "createdAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-07-15T10:30:00Z"
  }
}

#Create CLI Session

POST /api/v1/cli/auth/sessions

Create a new CLI authentication session.

Request Body:

{
  "sessionId": "sess_abc123",
  "deviceName": "MacBook Pro"
}

#Get Session Status

GET /api/v1/cli/auth/sessions/:sessionId

Poll for session approval status.

#Claim Session

POST /api/v1/cli/auth/sessions/:sessionId/claim

Exchange an approved session for an API token.

Response:

{
  "token": "sk_live_abc123",
  "expiresAt": "2024-07-15T10:30:00Z"
}

#Logout

POST /api/v1/cli/logout

Revoke the current API token.

#Record Install

POST /api/v1/installs

Record a skill or skillset installation event.

Request Body:

{
  "type": "skill",
  "slug": "my-org/data-analysis",
  "version": "1.2.0"
}

#MCP Endpoint

The platform exposes a Model Context Protocol endpoint:

https://agentskillhub.dev/mcp

This endpoint follows the MCP specification for agent integration.

#Error Responses

#400 Bad Request

{
  "error": "Invalid request",
  "message": "Missing required field: repoUrl"
}

#401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

#404 Not Found

{
  "error": "Not found",
  "message": "Skill 'my-org/unknown' not found"
}

#429 Too Many Requests

{
  "error": "Rate limited",
  "retryAfter": 60
}

#Rate Limits

• Public endpoints: 100 requests per minute per IP
• Authenticated endpoints: 1000 requests per minute per token

#SDKs and Tools

#Official CLI

The skhub CLI uses this API internally:

npm install -g skhub

See the CLI Reference for details.

#Custom Integration

Use any HTTP client:

// Example: Fetch skill metadata
const response = await fetch("https://agentskillhub.dev/api/v1/skills/my-org/data-analysis");
const skill = await response.json();

#Changelog

#v1 (Current)

• Initial API release
• Skills and skillsets endpoints
• CLI authentication flow
• Repository import endpoints