API Reference

Base URL: https://api.siteskills.ai

All endpoints return JSON. Authenticated endpoints require either a session cookie or an API key in the Authorization: Bearer sk_live_xxx header.

Authentication

Register

POST /api/auth/register

Field	Type	Required	Description
email	string	Yes	Valid email address
username	string	Yes	3-50 chars, unique
password	string	Yes	Min 8 chars

Rate limit: 5/min

Verify Email

POST /api/auth/verify-email

Field	Type	Required	Description
token	string	Yes	Token from verification email

Rate limit: 10/min

Login

POST /api/auth/login

Field	Type	Required	Description
email	string	Yes	Account email
password	string	Yes	Account password

Returns a session cookie. Rate limit: 10/min.

Logout

POST /api/auth/logout

Auth: Session required.

OAuth

GET /api/auth/github           # Redirect to GitHub OAuth
GET /api/auth/github/callback  # GitHub OAuth callback
GET /api/auth/google           # Redirect to Google OAuth
GET /api/auth/google/callback  # Google OAuth callback

Password Reset

POST /api/auth/forgot-password

Field	Type	Required
email	string	Yes

Rate limit: 3/min

POST /api/auth/reset-password

Field	Type	Required
token	string	Yes
password	string	Yes

Rate limit: 5/min

Current User

GET /api/auth/me

Auth: Session required. Returns the authenticated user object.

---

Skills

Browse / Search

GET /api/skills

Param	Type	Description
q	string	Search query (full-text)
category	string	Filter by category
agent	string	Filter by compatible agent
domain	string	Filter by target domain
difficulty	string	easy, medium, hard, expert
pricing	string	free, paid, freemium
sort	string	popular, newest, rating, success
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 50)

Auth: None. Rate limit: 60/min.

Response:

{
  "skills": [
    {
      "slug": "amazon-add-to-cart",
      "display_name": "Amazon -- Add Product to Cart",
      "description": "...",
      "version": "1.2.0",
      "author": { "username": "siteskills-official", "display_name": "SiteSkills Official" },
      "categories": ["e-commerce"],
      "tags": ["amazon", "cart"],
      "difficulty": "medium",
      "pricing_model": "free",
      "download_count": 3245,
      "avg_rating": 4.7,
      "success_rate": 89.0,
      "published_at": "2026-02-10T00:00:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "pages": 8
}

Skill Detail

GET /api/skills/:slug

Auth: None. Rate limit: 60/min.

Returns full skill metadata including siteskills.json content, download stats, and scan score.

Download Skill

GET /api/skills/:slug/download

Auth: None. Rate limit: 30/min.

Returns a signed URL to download the skill zip file.

Response:

{
  "download_url": "https://cdn.siteskills.ai/skills/amazon-add-to-cart/1.2.0/abc123.zip?sig=...",
  "version": "1.2.0",
  "file_size_bytes": 12400,
  "sha256": "abc123..."
}

Upload Skill

POST /api/skills

Auth: Session required. Rate limit: 10/hr.

Content-Type: multipart/form-data

Field	Type	Description
file	file	Zip file (max 5 MB)

The upload triggers the automated scan pipeline. Returns immediately with status pending.

Response (201):

{
  "skill": {
    "id": "uuid",
    "slug": "my-awesome-skill",
    "status": "pending"
  }
}

Update Skill (New Version)

PUT /api/skills/:slug

Auth: Session required (must be author). Rate limit: 10/hr.

Same multipart format as upload. The version in siteskills.json must be higher than the current version.

Delete Skill

DELETE /api/skills/:slug

Auth: Session required (author or admin).

Report Skill

POST /api/skills/:slug/report

Auth: Session required. Rate limit: 5/hr.

Field	Type	Required	Description
reason	string	Yes	Report category
description	string	No	Details

List Versions

GET /api/skills/:slug/versions

Auth: None. Rate limit: 30/min.

List Reviews

GET /api/skills/:slug/reviews

Auth: None. Rate limit: 60/min.

Create Review

POST /api/skills/:slug/reviews

Auth: Session required. Rate limit: 10/hr. One review per user per skill.

Field	Type	Required	Description
rating	integer	Yes	1-5
title	string	No	Max 200 chars
body	string	No	Review text
execution_success	boolean	No	Did the skill work?
agent_used	string	No	Which agent was used

---

User Dashboard

All endpoints require session authentication.

Method	Path	Description
GET	/api/user/dashboard	Dashboard overview data
PUT	/api/user/profile	Update profile
GET	/api/user/skills	List my skills (all statuses)
GET	/api/user/skills/:id	My skill detail + scan report
GET	/api/user/notifications	List notifications
PUT	/api/user/notifications/:id/read	Mark notification read
PUT	/api/user/notifications/read-all	Mark all notifications read
GET	/api/user/api-keys	List API keys
POST	/api/user/api-keys	Create API key
DELETE	/api/user/api-keys/:id	Revoke API key
GET	/api/user/email-preferences	Get email preferences
PUT	/api/user/email-preferences	Update email preferences

---

Admin

All endpoints require admin role.

Method	Path	Description
GET	/api/admin/review-queue	Pending skills with scan scores
GET	/api/admin/review/:id	Skill detail + full scan report
POST	/api/admin/review/:id/approve	Approve skill
POST	/api/admin/review/:id/reject	Reject with reason
GET	/api/admin/stats	Platform statistics
GET	/api/admin/users	User management list
PUT	/api/admin/users/:id/ban	Ban user
PUT	/api/admin/users/:id/unban	Unban user
GET	/api/admin/reports	Community reports queue
PUT	/api/admin/reports/:id	Resolve report

---

Telemetry

Submit Execution Report

POST /api/telemetry/execution

Auth: API key required.

Field	Type	Required	Description
skill_slug	string	Yes	Skill that was executed
skill_version	string	No	Version that was executed
success	boolean	Yes	Whether execution succeeded
steps_completed	integer	No	Steps completed before stop
failure_step	integer	No	Step where failure occurred
failure_reason	string	No	What went wrong
failure_mode_id	string	No	Matches failure mode ID from skill
execution_time_ms	integer	No	Total execution time
agent_type	string	No	Agent name
agent_version	string	No	Agent version
target_domain	string	No	Domain the skill ran against

---

Health

GET /api/health

Auth: None. Returns status of database, Redis, and scanner.

---

Error Format

All errors follow this format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

Error Codes

Code	HTTP	Description
VALIDATION_ERROR	400	Request validation failed
UNAUTHORIZED	401	No valid session or API key
EMAIL_NOT_VERIFIED	401	Email verification required
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource does not exist
CONFLICT	409	Duplicate email, username, slug, or hash
RATE_LIMITED	429	Too many requests
FILE_TOO_LARGE	413	Upload exceeds 5 MB
INVALID_FILE	422	Zip structure invalid
SCAN_FAILED	422	Scanner could not process skill
INTERNAL_ERROR	500	Unexpected server error