Documentation

Build with trust

Everything you need to install, verify, and understand agent skills. Security scanning, cryptographic signing, and full transparency.

The Vett registry exposes a REST API for searching skills, fetching metadata, downloading signed artifacts, and resolving skills for installation. All endpoints are available at https://vett.sh/api/v1.

No authentication required
The public API doesn't require authentication. Rate limits apply to prevent abuse. Contact us for higher limits or enterprise access.

Search Skills

GET/api/v1/skills
Search and list skills in the registry.
Query Parameters
qstring
Search query (matches name, description, owner)
riskstring
Filter by risk level (none, low, medium, high, critical)
sortBystring
Sort order: installs (default), newest, trending
limitnumber
Results per page (default: 20, max: 250)
offsetnumber
Pagination offset
Response
200 OK
1{
2  "skills": [
3    {
4      "id": "550e8400-e29b-41d4-a716-446655440000",
5      "slug": "cursor/skills/frontend-design",
6      "owner": "cursor",
7      "repo": "skills",
8      "name": "frontend-design",
9      "description": "Frontend design patterns and component architecture",
10      "installCount": 2847,
11      "createdAt": "2024-11-15T10:30:00Z",
12      "latestVersion": {
13        "version": "2.1.0",
14        "risk": "low",
15        "scanStatus": "completed"
16      }
17    }
18  ],
19  "pagination": {
20    "limit": 20,
21    "offset": 0,
22    "total": 128
23  }
24}

Skill Detail

GET/api/v1/skills/{slug}
Get full skill detail by slug, including all versions.
Path Parameters
slug*string
Skill slug: owner/repo/name (GitHub) or owner/name (domain sources)
Example
request
GET /api/v1/skills/cursor/skills/frontend-design
200 OK
1{
2  "id": "550e8400-e29b-41d4-a716-446655440000",
3  "slug": "cursor/skills/frontend-design",
4  "owner": "cursor",
5  "repo": "skills",
6  "name": "frontend-design",
7  "description": "Frontend design patterns and component architecture",
8  "sourceUrl": "https://github.com/cursor/skills",
9  "installCount": 2847,
10  "createdAt": "2024-11-15T10:30:00Z",
11  "versions": [
12    {
13      "version": "2.1.0",
14      "hash": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
15      "artifactUrl": "https://artifacts.vett.sh/skills/e5f6a7b8...signed-url",
16      "size": 4231,
17      "risk": "low",
18      "summary": "Provides frontend design patterns with React focus",
19      "scanStatus": "completed",
20      "gitRef": "main",
21      "commitSha": "abc123def456789...",
22      "sourceUrl": "https://github.com/cursor/skills/tree/abc123.../frontend-design",
23      "sigstoreBundle": { "mediaType": "application/vnd.dev.sigstore.bundle+json;version=0.2", "..." : "..." },
24      "rekorLogIndex": "12345678",
25      "createdAt": "2025-01-15T09:00:00Z"
26    }
27  ]
28}

Resolve

POST/api/v1/resolve
Find or ingest a skill. Accepts a slug reference or URL. Returns the skill immediately if it exists and is fresh, or starts ingestion and returns a job ID.
Request Body
application/json
{
  "input": "cursor/skills/frontend-design"
}

The input field accepts:

  • Slug reference: owner/repo/name or owner/name
  • Pinned version: owner/repo/name@1.2.0
  • URL: https://github.com/owner/repo/tree/main/skill
Response (skill exists and is fresh)
200 OK
1{
2  "status": "ready",
3  "skill": {
4    "id": "550e8400-e29b-41d4-a716-446655440000",
5    "slug": "cursor/skills/frontend-design",
6    "owner": "cursor",
7    "repo": "skills",
8    "name": "frontend-design",
9    "versions": [ ... ]
10  }
11}
Response (ingestion started)
200 OK
1{
2  "status": "processing",
3  "jobId": "770e8400-e29b-41d4-a716-446655440003",
4  "slug": "cursor/skills/frontend-design"
5}
Response (pinned version not found)
404 Not Found
{
  "status": "not_found",
  "message": "Version 1.2.0 not found for cursor/skills/frontend-design"
}
Async processing
When the response status is processing, poll the job status endpoint to track progress. Analysis typically completes in 5-15 seconds.

Jobs

GET/api/v1/jobs/{id}
Check the status of an ingestion job.
Response (pending)
200 OK
{
  "id": "770e8400-e29b-41d4-a716-446655440003",
  "status": "processing",
  "error": null,
  "result": null,
  "createdAt": "2025-01-20T10:00:00Z",
  "startedAt": "2025-01-20T10:00:01Z",
  "completedAt": null
}
Response (complete)
200 OK
1{
2  "id": "770e8400-e29b-41d4-a716-446655440003",
3  "status": "completed",
4  "error": null,
5  "result": {
6    "skill": {
7      "id": "550e8400-e29b-41d4-a716-446655440000",
8      "owner": "owner",
9      "repo": "repo",
10      "name": "my-skill"
11    },
12    "version": {
13      "id": "660e8400-e29b-41d4-a716-446655440001",
14      "version": "1.0.0",
15      "hash": "...",
16      "risk": "low"
17    }
18  },
19  "createdAt": "2025-01-20T10:00:00Z",
20  "startedAt": "2025-01-20T10:00:01Z",
21  "completedAt": "2025-01-20T10:00:08Z"
22}
Job Statuses
pendingJob queued, waiting to start
processingFetching skill and running analysis
completedAnalysis finished, result available
failedError occurred, check error field

Download

GET/api/v1/download/{ref}
Download a signed skill artifact. Returns a redirect to a signed URL.
Path Parameters
ref*string
Download reference in the format {skillId}@{version}
Example
request
GET /api/v1/download/550e8400-e29b-41d4-a716-446655440000@2.1.0
302 Found
Location: https://artifacts.vett.sh/skills/e5f6a7b8...?X-Amz-Signature=...
Signed URLs
Download URLs are signed and expire after 60 seconds. Always fetch a fresh URL before downloading.

Signing Keys

The CLI embeds the ECDSA P-256 public key used to verify Sigstore bundles. The current signing key ID is v1-ecdsa-2025-02-04.

Sigstore verification
Each version includes a sigstoreBundle containing the ECDSA P-256 signature and a Rekor transparency log entry. The CLI verifies bundles using its embedded public key, matched against the bundle's publicKey.hint. Key rotations require a CLI update.

Error Responses

All endpoints return consistent error responses with an error field.

400 Bad Request
{
  "error": "Invalid query parameters",
  "details": {
    "fieldErrors": {
      "limit": ["Expected number, received string"]
    }
  }
}
404 Not Found
{
  "error": "Skill not found"
}
500 Internal Server Error
{
  "error": "Failed to fetch skills"
}

HTTP Status Codes

200Success
400Bad request (invalid parameters)
404Not found
429Rate limit exceeded
500Internal server error

Rate Limits

The public API is rate-limited to prevent abuse. Current limits:

Search / detail endpoints60 requests/minute
Resolve (ingestion)5 requests/minute
Download endpoint30 requests/minute
Need higher limits?
Contact us for enterprise access with higher rate limits, SLAs, and dedicated support.