API Reference Overview

API Overview

FastSkill provides two main API interfaces:

Rust Library API - Direct programmatic access for Rust applications
HTTP REST API - HTTP-based API for web applications and cross-language integration

The Rust library provides the core functionality, while the HTTP API exposes it via REST endpoints. Both APIs provide access to the same core functionality.

API Types

1. Rust Library API

The primary interface for Rust applications, providing async/await support with tokio and comprehensive error handling.

use fastskill::{FastSkillService, ServiceConfig};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create service with configuration
    let config = ServiceConfig {
        skill_storage_path: PathBuf::from("./skills"),
        ..Default::default()
    };

    // Initialize service
    let mut service = FastSkillService::new(config).await?;
    service.initialize().await?;

    // Use the API
    let skills = service.skill_manager().list_skills(None).await?;
    println!("Found {} skills", skills.len());

    service.shutdown().await?;
    Ok(())
}

For complete Rust API documentation, see Rust API Reference.

2. HTTP REST API

HTTP-based API for web applications, microservices, and cross-language integration. Start the server with:

fastskill serve --host 0.0.0.0 --port 8080

Skills Management Endpoints

# List all skills
curl -X GET http://localhost:8080/api/skills

# Get a specific skill
curl -X GET http://localhost:8080/api/skills/:id

# Create a skill
curl -X POST http://localhost:8080/api/skills \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-skill",
    "name": "My Skill",
    "description": "Example skill",
    "version": "1.0.0"
  }'

# Update a skill
curl -X PUT http://localhost:8080/api/skills/:id \
  -H "Content-Type: application/json" \
  -d '{...}'

# Delete a skill
curl -X DELETE http://localhost:8080/api/skills/:id

Search Endpoints

# Search for skills
curl -X POST http://localhost:8080/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "text processing",
    "limit": 10
  }'

Reindex Endpoints

# Reindex all skills
curl -X POST http://localhost:8080/api/reindex

# Reindex a specific skill
curl -X POST http://localhost:8080/api/reindex/:id

Status Endpoints

# Get service status
curl -X GET http://localhost:8080/api/status

# Root endpoint
curl -X GET http://localhost:8080/

Authentication Endpoints

# Generate JWT token
curl -X POST http://localhost:8080/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user",
    "password": "pass"
  }'

# Verify token
curl -X GET http://localhost:8080/auth/verify \
  -H "Authorization: Bearer <token>"

Claude Code API Endpoints

FastSkill implements the Claude Code v1 API specification:

# Create skill (Claude API format)
curl -X POST http://localhost:8080/v1/skills \
  -H "Content-Type: application/json" \
  -d '{...}'

# List skills
curl -X GET http://localhost:8080/v1/skills

# Get skill
curl -X GET http://localhost:8080/v1/skills/:skill_id

# Delete skill
curl -X DELETE http://localhost:8080/v1/skills/:skill_id

# Create skill version
curl -X POST http://localhost:8080/v1/skills/:skill_id/versions \
  -H "Content-Type: application/json" \
  -d '{...}'

# List skill versions
curl -X GET http://localhost:8080/v1/skills/:skill_id/versions

# Get skill version
curl -X GET http://localhost:8080/v1/skills/:skill_id/versions/:version

# Delete skill version
curl -X DELETE http://localhost:8080/v1/skills/:skill_id/versions/:version

Registry Endpoints (when —enable-registry is used)

# List all sources
curl -X GET http://localhost:8080/api/registry/sources

# List all skills from all sources
curl -X GET http://localhost:8080/api/registry/skills

# List skills from a specific source
curl -X GET http://localhost:8080/api/registry/sources/:name/skills

# Get marketplace.json for a source
curl -X GET http://localhost:8080/api/registry/sources/:name/marketplace

# Refresh all sources
curl -X POST http://localhost:8080/api/registry/refresh

Manifest Endpoints (when —enable-registry is used)

# List skills in manifest
curl -X GET http://localhost:8080/api/manifest/skills

# Add skill to manifest
curl -X POST http://localhost:8080/api/manifest/skills \
  -H "Content-Type: application/json" \
  -d '{...}'

# Update skill in manifest
curl -X PUT http://localhost:8080/api/manifest/skills/:id \
  -H "Content-Type: application/json" \
  -d '{...}'

# Remove skill from manifest
curl -X DELETE http://localhost:8080/api/manifest/skills/:id

# Generate MDC file
curl -X POST http://localhost:8080/api/manifest/generate-mdc

API Architecture

Request Flow

Response Format

All HTTP APIs return consistent JSON response formats:

{
  "success": true,
  "data": {
    // Response data
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid skill definition",
    "details": {
      "field": "version",
      "expected": "semantic version string",
      "received": "invalid"
    }
  }
}

Common Patterns

Error Handling

use fastskill::ServiceError;

match service.skill_manager().list_skills(None).await {
    Ok(skills) => {
        println!("Found {} skills", skills.len());
    }
    Err(ServiceError::Validation(msg)) => {
        eprintln!("Validation error: {}", msg);
    }
    Err(ServiceError::Storage(msg)) => {
        eprintln!("Storage error: {}", msg);
    }
    Err(e) => {
        eprintln!("Error: {}", e);
    }
}

Filtering Skills

use fastskill::SkillFilters;

let filters = SkillFilters {
    enabled: Some(true),
    tags: Some(vec!["text".to_string(), "nlp".to_string()]),
    ..Default::default()
};

let skills = service.skill_manager()
    .list_skills(Some(filters))
    .await?;

Starting the HTTP Server

Basic Server

# Start server on default port (8080)
fastskill serve

# Custom host and port
fastskill serve --host 0.0.0.0 --port 9000

With Registry UI

# Enable registry web UI at /registry
fastskill serve --enable-registry

Then open http://localhost:8080/registry in your browser.

Integration Examples

Rust Application

use fastskill::{FastSkillService, ServiceConfig};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ServiceConfig {
        skill_storage_path: PathBuf::from("./skills"),
        ..Default::default()
    };

    let mut service = FastSkillService::new(config).await?;
    service.initialize().await?;

    // Discover skills
    let skills = service.metadata_service()
        .discover_skills("text processing")
        .await?;

    println!("Found {} relevant skills", skills.len());

    service.shutdown().await?;
    Ok(())
}

HTTP Client (cURL)

# Search for skills
curl -X POST http://localhost:8080/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "data visualization", "limit": 5}'

# List all skills
curl -X GET http://localhost:8080/api/skills

HTTP Client (Rust reqwest)

use reqwest;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();

    // Search for skills
    let response = client
        .post("http://localhost:8080/api/search")
        .json(&json!({
            "query": "text processing",
            "limit": 10
        }))
        .send()
        .await?;

    let result: serde_json::Value = response.json().await?;
    println!("Search results: {}", result);

    Ok(())
}

Testing APIs

Unit Testing with Rust Library

use fastskill::{FastSkillService, ServiceConfig};
use std::path::PathBuf;
use tempfile::TempDir;

#[tokio::test]
async fn test_list_skills() {
    let temp_dir = TempDir::new().unwrap();
    let config = ServiceConfig {
        skill_storage_path: temp_dir.path().to_path_buf(),
        ..Default::default()
    };

    let mut service = FastSkillService::new(config).await.unwrap();
    service.initialize().await.unwrap();

    let skills = service.skill_manager().list_skills(None).await.unwrap();
    assert!(skills.is_empty()); // Should be empty in test environment
}

Integration Testing with HTTP API

# Test health endpoint
curl -X GET http://localhost:8080/api/status

# Test skills endpoint
curl -X GET http://localhost:8080/api/skills

Performance Considerations

Rust Library

Use Arc to share service instances across tasks
Batch operations when possible
Use async/await for concurrent operations

use futures::future::join_all;

// Execute multiple operations concurrently
let queries = vec!["text", "data", "file"];
let tasks: Vec<_> = queries.iter()
    .map(|q| service.metadata_service().discover_skills(q))
    .collect();

let results = join_all(tasks).await;

HTTP API

Use connection pooling for HTTP clients
Cache responses when appropriate
Use compression (enabled by default)

Troubleshooting

Connection Issues

Connection refused: Ensure the FastSkill HTTP server is running.

# Check if server is running
curl http://localhost:8080/api/status

Timeout errors: Check network connectivity and service health. The server may be overloaded.

Authentication Issues

JWT token errors: Verify your token is valid and not expired. Generate a new token if needed.

curl -X POST http://localhost:8080/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

The FastSkill API is designed to be intuitive and consistent. Start with the Rust library for the best development experience, then use the HTTP API for production deployments and cross-language integration.

Getting Started

Configuration

Skill Management

Discovery & Routing

Tool Calling

Progressive Loading

API Reference

CLI Reference

Registry

Examples & Tutorials

Advanced Topics

Integration

Community

​API Overview

​API Types

​1. Rust Library API

​2. HTTP REST API

​Skills Management Endpoints

​Search Endpoints

​Reindex Endpoints

​Status Endpoints

​Authentication Endpoints

​Claude Code API Endpoints

​Registry Endpoints (when —enable-registry is used)

​Manifest Endpoints (when —enable-registry is used)

​API Architecture

​Request Flow

​Response Format

​Common Patterns

​Error Handling

​Filtering Skills

​Starting the HTTP Server

​Basic Server

​With Registry UI

​Integration Examples

​Rust Application

​HTTP Client (cURL)

​HTTP Client (Rust reqwest)

​Testing APIs

​Unit Testing with Rust Library

​Integration Testing with HTTP API

​Performance Considerations

​Rust Library

​HTTP API

​Troubleshooting

API Overview

API Types

1. Rust Library API

2. HTTP REST API

Skills Management Endpoints

Search Endpoints

Reindex Endpoints

Status Endpoints

Authentication Endpoints

Claude Code API Endpoints

Registry Endpoints (when —enable-registry is used)

Manifest Endpoints (when —enable-registry is used)

API Architecture

Request Flow

Response Format

Common Patterns

Error Handling

Filtering Skills

Starting the HTTP Server

Basic Server

With Registry UI

Integration Examples

Rust Application

HTTP Client (cURL)

HTTP Client (Rust reqwest)

Testing APIs

Unit Testing with Rust Library

Integration Testing with HTTP API

Performance Considerations

Rust Library

HTTP API

Troubleshooting