Skip to main content
Asterismbeta
← Back to Documentation

API Reference

The Asterism REST API allows you to interact with the registry programmatically.

Download OpenAPI SpecSDKs & LibrariesError Codes

Base URL

https://api.joinasterism.com/v1

Authentication

Authenticated endpoints require a Bearer token. Get your API key from the dashboard.

Authorization: Bearer aster_live_xxxxxxxxxxxx

Rate Limits

PlanRequests/minute
Free60
Pro300
Team600
Enterprise6,000

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset

Endpoints

GET/api/v1/skills

List and search skills

Parameters:

  • q(string)Search query
  • page(number)Page number (default: 1)
  • limit(number)Results per page (default: 20, max: 100)
  • sort(string)Sort by: downloads, recent, stars
GET/api/v1/skills/:name

Get skill details

GET/api/v1/skills/:name/skill.md

Get skill content (SKILL.md)

PUT/api/v1/skillsAuth Required

Publish or update a skill

POST/api/v1/skills/:name/forkAuth Required

Fork a skill to your account

Parameters:

  • newName(string)Name for the forked skill
GET/api/v1/stacks

List skill stacks

Parameters:

  • q(string)Search query
  • featured(boolean)Show featured only
  • official(boolean)Show official only
POST/api/v1/stacksAuth Required

Create a skill stack

GET/api/v1/api-keysAuth Required

List your API keys

POST/api/v1/api-keysAuth Required

Create a new API key

Parameters:

  • name(string)Key name/description
DELETE/api/v1/api-keys/:idAuth Required

Delete an API key

GET/api/v1/users/meAuth Required

Get current user info

POST/api/v1/skills/:name/report-copyAuth Required

Report a skill as plagiarism/copy

Parameters:

  • originalSkillId(string)ID of the original skill
  • evidence(string)Evidence description
GET/api/v1/skills/:name/similarity

Get similarity scan results

GET/api/v1/skills/:name/provenance

Get skill provenance/authorship record

POST/api/v1/dmca

Submit DMCA takedown request

GET/api/v1/dmca/:id

Get DMCA request status

POST/api/v1/dmca/:id/counter-notice

Submit counter-notice to DMCA request

GET/api/v1/users/:username/reputation

Get author reputation profile

POST/api/v1/users/:username/verifyAuth Required

Request author verification

Parameters:

  • method(string)Verification method: github, domain, manual
  • proof(string)Verification proof
GET/api/v1/reputation/leaderboard

Get top authors by reputation

Parameters:

  • limit(number)Number of results (default: 10, max: 100)
POST/api/v1/execute/premiumAuth Required

Execute a premium hosted-only skill

Parameters:

  • skillName(string)Skill to execute
  • inputs(object)Skill inputs
  • licenseKey(string)License key (if required)
GET/api/v1/skills/:name/licenseAuth Required

Validate a skill license

Parameters:

  • licenseKey(string)License key to validate
POST/api/v1/skills/:name/configureAuth Required

Configure premium skill settings (publishers only)

GET/api/v1/external

List indexed external skills (from GitHub, skills.sh, etc.)

Parameters:

  • registry(string)Filter by source: skills.sh, github, all
  • verified(boolean)Only security-scanned skills
  • limit(number)Results to return (default: 20, max: 100)
POST/api/v1/external/scanAuth Required

Security scan an external skill URL/content

Parameters:

  • url(string)GitHub URL or external skill URL
  • content(string)Raw skill content to scan
POST/api/v1/track

Track skill install (anonymous telemetry for leaderboard)

Parameters:

  • skillName(string)Name of the skill installed
  • source(string)Source: registry, github, external
  • agents(array)Agent IDs where skill was installed
  • repoUrl(string)GitHub repo URL (for github source)
GET/api/v1/trending

Get trending skills with velocity metrics

Parameters:

  • period(string)Time period: day, week, month
  • category(string)Filter by category
  • limit(number)Results to return (default: 10)

Example: Search Skills

curl -X GET "https://api.joinasterism.com/v1/skills?q=pdf&limit=5" \
  -H "Authorization: Bearer aster_live_xxxx"

Response:

{
  "skills": [
    {
      "fullName": "@askskills/pdf-tools",
      "description": "Extract and manipulate PDF documents",
      "downloads": 1234,
      "securityScore": 95
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 12,
    "hasMore": true
  }
}