API Reference
REST API documentation for programmatic access to ZhenSkill
Endpoints
Base URL
All API requests should be made to:
https://www.zhenskill.com/api
Authentication
Most marketplace catalog endpoints are publicly accessible. Authenticated buyer and developer flows currently use the signed-in web session rather than self-issued API keys from this site.
Current Auth Model
- Buyer delivery uses the logged-in website session.
- Developer publishing uses the logged-in website session plus subscription checks.
- Managed API credentials will converge through the shared platform console later, not this main site.
Session-Based Requests
For browser-based authenticated requests, keep the session cookie and send requests with credentials.
fetch("/api/developer/dashboard", {
credentials: "include",
})
Private Integrations
If you need a private integration path before the platform console is unified, contact support instead of relying on an in-site API key workflow.
GET /api/skills
Retrieve a list of all skills.
Request
GET /api/skills
Query Parameters
| Parameter | Type | Description | Default |
|---|---|---|---|
category | string | Filter by category slug | - |
search | string | Search query | - |
featured | boolean | Show only featured skills | false |
sort | string | Sort by: downloads, rating, date | downloads |
limit | number | Number of results (max 100) | 20 |
offset | number | Pagination offset | 0 |
Example Request
curl "https://www.zhenskill.com/api/skills?category=video-media&limit=10"
Response
{
"skills": [
{
"id": "uuid",
"name": "video-generator",
"display_name": "Video Generator",
"description": "Generate videos with AI",
"version": "2.1.0",
"author": "ZhenRobotics",
"category_id": "uuid",
"downloads_count": 1523,
"rating_average": 4.8,
"rating_count": 47,
"featured": true,
"tags": ["video", "media", "ai"],
"platform": ["macos", "linux", "windows"],
"requires_api_key": true,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-02-20T15:45:00Z"
}
],
"total": 50,
"limit": 10,
"offset": 0
}
GET /api/skills/[name]
Get detailed information about a specific skill.
Request
GET /api/skills/[name]
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | Skill name (URL path parameter) |
Example Request
curl "https://www.zhenskill.com/api/skills/video-generator"
Response
{
"id": "uuid",
"name": "video-generator",
"display_name": "Video Generator",
"description": "Generate videos with AI",
"long_description": "# Video Generator\n\nDetailed markdown...",
"version": "2.1.0",
"author": "ZhenRobotics",
"author_email": "hello@zhenrobotics.com",
"license": "MIT",
"category_id": "uuid",
"categories": {
"name": "Video & Media",
"slug": "video-media"
},
"tags": ["video", "media", "ai"],
"icon_url": "https://cdn.zhenskill.com/icons/video-gen.png",
"repository_url": "https://github.com/ZhenRobotics/video-generator",
"homepage_url": "https://zhenrobotics.com/video-generator",
"download_url": "https://cdn.zhenskill.com/skills/video-generator-2.1.0.tar.gz",
"install_command": "clawhub install video-generator",
"downloads_count": 1523,
"rating_average": 4.8,
"rating_count": 47,
"status": "active",
"featured": true,
"platform": ["macos", "linux", "windows"],
"requires_api_key": true,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-02-20T15:45:00Z",
"published_at": "2024-01-15T10:30:00Z"
}
Error Response (404)
{
"error": "Skill not found",
"code": "SKILL_NOT_FOUND"
}
GET /api/categories
Get all skill categories.
Request
GET /api/categories
Example Request
curl "https://www.zhenskill.com/api/categories"
Response
{
"categories": [
{
"id": "uuid",
"name": "Video & Media",
"slug": "video-media",
"description": "Video editing and media processing skills",
"icon": "🎬",
"skill_count": 12
},
{
"id": "uuid",
"name": "Development",
"slug": "development",
"description": "Development tools and utilities",
"icon": "💻",
"skill_count": 15
}
]
}
Rate Limits
To ensure fair usage and service stability, the ZhenSkill API implements rate limiting.
Limits
| Endpoint Type | Unauthenticated | Authenticated |
|---|---|---|
| Read operations (GET) | 100 requests/hour | 1000 requests/hour |
| Write operations (POST/PUT) | N/A | 100 requests/hour |
Rate Limit Headers
Every API response includes rate limit information:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1614556800
Exceeding Rate Limits
If you exceed the rate limit, you'll receive a 429 Too Many Requests response:
{
"error": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED",
"retry_after": 3600
}
Error Handling
The API uses standard HTTP status codes and returns errors in a consistent format.
HTTP Status Codes
| Code | Description |
|---|---|
200 | Success |
201 | Created |
400 | Bad Request - Invalid parameters |
401 | Unauthorized - Invalid or missing API key |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Resource doesn't exist |
429 | Too Many Requests - Rate limit exceeded |
500 | Internal Server Error |
503 | Service Unavailable |
Error Response Format
All errors follow this format:
{
"error": "Human-readable error message",
"code": "ERROR_CODE",
"details": {
"field": "Additional context (optional)"
}
}
Common Error Codes
| Code | Description |
|---|---|
SKILL_NOT_FOUND | Requested skill doesn't exist |
INVALID_PARAMETERS | Request parameters are invalid |
UNAUTHORIZED | Authentication required or failed |
RATE_LIMIT_EXCEEDED | Too many requests |
VALIDATION_ERROR | Input validation failed |
SDK and Libraries
Official SDKs are available for popular languages:
- JavaScript/TypeScript:
npm install @zhenskill/sdk - Python:
pip install zhenskill - Go:
go get github.com/ZhenRobotics/zhenskill-go
JavaScript Example
import { ZhenSkill } from '@zhenskill/sdk'
const client = new ZhenSkill({
apiKey: 'YOUR_API_KEY'
})
// Get all skills
const skills = await client.skills.list()
// Get a specific skill
const skill = await client.skills.get('video-generator')
Webhooks (Coming Soon)
Webhook support is planned for future releases. You'll be able to subscribe to events like:
- New skill published
- Skill updated
- New review posted
- Download milestone reached
Need Help?
If you have questions about the API:
- Join our Discord community
- Check API examples on GitHub
- Report issues on GitHub