Skip to main content

​
Overview

The Skills API provides endpoints for publishing, discovering, and downloading AI agent skills.

​
Publish Skill

Endpoint: POST /api/v1/skills Publish a new skill or skill version. This is a two-phase process:
  1. POST /skills - Create version record and get upload URL
  2. Upload tarball to signed URL
  3. POST /skills/confirm - Trigger security scan and finalize
Requires skills:publish scope.

​
Request

​
manifest
object
required
Skill manifest matching skills.json schema
​
readme
string
README.md content (markdown)
​
files
array
List of file paths in tarball (for UI display)
Example: 
{
  "manifest": {
    "name": "@tank/hello-world",
    "version": "1.0.0",
    "description": "A friendly greeting skill",
    "repository": "https://github.com/tank/hello-world",
    "visibility": "public",
    "permissions": {
      "network": false,
      "filesystem": false
    }
  },
  "readme": "# Hello World\n\nA simple greeting skill.",
  "files": ["SKILL.md", "index.ts", "skills.json"]
}

​
Response

​
uploadUrl
string
Signed URL for uploading the tarball (valid for 1 hour)
​
skillId
string
UUID of the skill record
​
versionId
string
UUID of the version record
{
  "uploadUrl": "https://storage.example.com/signed-url",
  "skillId": "550e8400-e29b-41d4-a716-446655440000",
  "versionId": "660e8400-e29b-41d4-a716-446655440001"
}

​
Error Responses

409 Conflict - Version already exists: 
{
  "error": "Version 1.0.0 already exists for @tank/hello-world"
}
400 Bad Request - Invalid manifest: 
{
  "error": "Invalid manifest",
  "details": {
    "name": ["Required"],
    "version": ["Must follow semver format"]
  }
}
403 Forbidden - Organization membership required: 
{
  "error": "You are not a member of org 'acme'"
}
400 Bad Request - Permission escalation detected: 
{
  "error": "Permission escalation detected",
  "details": [
    "Patch version added 'network' permission (requires minor/major bump)"
  ]
}

​
Confirm Upload

Endpoint: POST /api/v1/skills/confirm Finalize the publish after uploading the tarball. Triggers security scan.

​
Request

​
versionId
string
required
Version ID from publish response
​
integrity
string
required
SHA-512 hash of the tarball (format: sha512-base64hash)
​
fileCount
integer
Number of files in the tarball
​
tarballSize
integer
Size in bytes
​
readme
string
README.md content (if not provided in initial publish)
Example: 
{
  "versionId": "660e8400-e29b-41d4-a716-446655440001",
  "integrity": "sha512-abc123...",
  "fileCount": 3,
  "tarballSize": 4096
}

​
Response

​
success
boolean
Always true on successful confirmation
​
name
string
Skill name
​
version
string
Version number
​
auditScore
number
Audit score (0-10) based on security scan
​
scanVerdict
string
Security scan verdict: pass, pass_with_notes, flagged, or fail
{
  "success": true,
  "name": "@tank/hello-world",
  "version": "1.0.0",
  "auditScore": 9,
  "scanVerdict": "pass"
}

​
Get Skill Metadata

Endpoint: GET /api/v1/skills/{name} Retrieve metadata for a skill.

​
Path Parameters

​
name
string
required
Skill name (URL-encoded for scoped packages)
Example: 
GET /api/v1/skills/@tank%2Fhello-world

​
Response

​
name
string
Skill name
​
description
string
Description from manifest
​
visibility
string
public or private
​
latestVersion
string
Latest published version
​
publisher
object
Publisher information
​
createdAt
string
ISO 8601 timestamp
​
updatedAt
string
ISO 8601 timestamp
{
  "name": "@tank/hello-world",
  "description": "A friendly greeting skill",
  "visibility": "public",
  "latestVersion": "1.0.0",
  "publisher": {
    "name": "Jane Doe"
  },
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}

​
List Versions

Endpoint: GET /api/v1/skills/{name}/versions List all published versions of a skill.

​
Response

​
name
string
Skill name
​
versions
array
Array of version objects (sorted by publish date, newest first)
{
  "name": "@tank/hello-world",
  "versions": [
    {
      "version": "1.0.0",
      "integrity": "sha512-abc123...",
      "auditScore": 9,
      "auditStatus": "completed",
      "publishedAt": "2026-01-15T10:30:00Z"
    }
  ]
}

​
Get Version Details

Endpoint: GET /api/v1/skills/{name}/{version} Get detailed information about a specific version, including download URL.

​
Response

​
name
string
Skill name
​
version
string
Version number
​
description
string
Description from manifest
​
integrity
string
SHA-512 hash for verification
​
permissions
object
Declared permissions
​
auditScore
number
Audit score (0-10)
​
auditStatus
string
Scan status
​
downloadUrl
string
Signed URL for downloading tarball (valid for 1 hour)
​
publishedAt
string
ISO 8601 timestamp
​
downloads
integer
Download count (last 7 days)
​
scanVerdict
string
Security scan verdict (if available)
​
scanFindings
array
Security findings from scan
{
  "name": "@tank/hello-world",
  "version": "1.0.0",
  "description": "A friendly greeting skill",
  "integrity": "sha512-abc123...",
  "permissions": {
    "network": false,
    "filesystem": false
  },
  "auditScore": 9,
  "auditStatus": "completed",
  "downloadUrl": "https://storage.example.com/signed-url",
  "publishedAt": "2026-01-15T10:30:00Z",
  "downloads": 42,
  "scanVerdict": "pass",
  "scanFindings": []
}

​
Download Workflow

  1. GET /api/v1/skills/{name}/{version} to get downloadUrl and integrity
  2. Download tarball from downloadUrl
  3. Verify SHA-512 hash matches integrity
  4. Extract tarball to local directory
Example (using tank install): 
tank install @tank/[email protected]

​
Next Steps

Search API

Discover skills with search

Security Scanning

Learn about security analysis

Build docs developers (and LLMs) love

Get started for freeTalk to us