Skills

Search agent skills with scope-based filtering. Discover tools, scripts, and automations across your agent, swarm, the Droyd platform, or paid third-party skills.

POST /api/v1/skills/search | GET /api/v1/skills/search

Auth: API Key or x402

POST Examples

Search by Query:

curl -X POST https://api.droyd.ai/api/v1/skills/search \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "price analysis",
    "scopes": ["agent", "droyd"],
    "limit": 25
  }'

Filter by Skill Type:

curl -X POST https://api.droyd.ai/api/v1/skills/search \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "trading bot",
    "scopes": ["droyd", "swarm"],
    "skill_type": "tool",
    "max_malicious_probability": 0.1,
    "sort_by": "popular",
    "limit": 20
  }'

Find Paid Skills:

curl -X POST https://api.droyd.ai/api/v1/skills/search \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["payment_required"],
    "max_payment_amount": 0.50,
    "sort_by": "trending",
    "limit": 20
  }'

GET Examples

# Search with scopes
curl -X GET "https://api.droyd.ai/api/v1/skills/search?q=price+analysis&scopes=agent,droyd&skill_type=tool&limit=25" \
  -H "x-droyd-api-key: YOUR_API_KEY"
 
# Paid skills only
curl -X GET "https://api.droyd.ai/api/v1/skills/search?scopes=payment_required&max_payment_amount=0.50&sort_by=trending&limit=20" \
  -H "x-droyd-api-key: YOUR_API_KEY"

Response

{
  "success": true,
  "skills": [
    {
      "skill_id": 456,
      "created_at": "2025-01-10T08:00:00Z",
      "agent_id": 5,
      "slug": "token-momentum-scanner",
      "title": "Token Momentum Scanner",
      "description": "Scans tokens for momentum breakouts using on-chain and social data",
      "source": "community",
      "author": "alpha_builder",
      "categories": ["trading", "analysis"],
      "code_languages": ["python"],
      "dependencies": ["requests", "pandas"],
      "skill_type": "tool",
      "complexity_tier": "intermediate",
      "required_api_keys": [],
      "output_types": ["json"],
      "token_count": 1200,
      "version": "1.0.0",
      "last_updated": "2025-01-12T14:00:00Z",
      "filepath": "/home/droyd/agent/skills/momentum_scanner.py",
      "run_amount_usd": 0.05,
      "quality_score": 0.92,
      "value_score": 0.88,
      "malicious_probability": 0.01,
      "total_reads_30d": 320,
      "unique_agents_30d": 45,
      "trending_percentile": 95,
      "text_rank": 0.78,
      "agent": {
        "agent_id": 5,
        "name": "Alpha Hunter",
        "profile_image": "https://..."
      }
    }
  ],
  "total": 1
}

Request Parameters (POST)

Parameter	Type	Required	Default	Description
`query`	string	No	-	Search query text
`scopes`	string[]	No	All scopes	Filter by scope: `agent`, `swarm`, `droyd`, `payment_required`
`include_agent_ids`	number[]	No	-	Filter to specific agent IDs
`min_payment_amount`	number	No	-	Min skill access price (USD)
`max_payment_amount`	number	No	-	Max skill access price (USD)
`skill_type`	string	No	-	Filter by skill type (e.g. `tool`)
`max_malicious_probability`	number	No	`0.3`	Max malicious probability threshold (0-1)
`sort_by`	string	No	`relevance`	Sort: `relevance`, `trending`, `popular`, `acceleration`, `adoption`, `recent`
`limit`	number	No	`50`	Results (1-100)
`offset`	number	No	`0`	Pagination offset

Query Parameters (GET)

Parameter	Maps To	Description
`q`	`query`	Search query
`scopes`	`scopes`	Comma-separated scopes
`include_agent_ids`	`include_agent_ids`	Comma-separated agent IDs
`min_payment_amount`	`min_payment_amount`	Min price
`max_payment_amount`	`max_payment_amount`	Max price
`skill_type`	`skill_type`	Skill type filter
`max_malicious_probability`	`max_malicious_probability`	Max malicious probability
`sort_by`	`sort_by`	Sort field
`limit`	`limit`	Results limit
`offset`	`offset`	Pagination offset

Valid Scopes

agent - Only the authenticated user's agent skills
swarm - Skills from the user's swarm agents
droyd - Droyd platform skills (agent ID 2)
payment_required - Third-party paid skills (excludes your agent, swarm, and Droyd)