Skip to main content

​
Introduction

The Tank Registry API is a RESTful HTTP API for publishing, discovering, and downloading AI agent skills. It powers the tank CLI and is available for integration with custom tooling.

​
Base URL

All API endpoints are relative to the registry base URL: 
https://registry.tank.dev/api/v1
For local development: 
http://localhost:3000/api/v1

​
API Versioning

The API uses URL-based versioning with the /v1 prefix. This ensures backward compatibility as the API evolves.
  • Current version: v1
  • Stability: Production-ready
  • Breaking changes: Will result in a new version (e.g., /v2)

​
Request Format

All POST/PUT requests accept JSON payloads: 
Content-Type: application/json

​
Response Format

All responses return JSON with appropriate HTTP status codes:
  • 2xx: Success
  • 4xx: Client errors (invalid input, auth required, not found)
  • 5xx: Server errors

​
Success Response

{
  "name": "@tank/hello-world",
  "version": "1.0.0",
  "description": "A simple greeting skill"
}

​
Error Response

{
  "error": "Skill not found"
}
Some endpoints include additional error details: 
{
  "error": "Invalid manifest",
  "details": {
    "name": ["Required"],
    "version": ["Must follow semver"]
  }
}

​
Rate Limiting

API keys have configurable rate limits:
  • Default: 1000 requests per day
  • Headers: Rate limit info included in responses
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Pagination

Endpoints that return lists support pagination:
​
page
integer
default:"1"
Page number (1-indexed)
​
limit
integer
default:"20"
Results per page (max 50)

​
Paginated Response

{
  "results": [...],
  "page": 1,
  "limit": 20,
  "total": 42
}

​
Skill Visibility

Skills can be public or private:
  • Public: Visible to all users, discoverable in search
  • Private: Only visible to publisher, organization members, or granted users
Authenticated requests can access private skills if the user has permission.

​
Scoped Packages

Skills can be scoped to organizations:
  • Format: @org-slug/skill-name
  • Publishing: Requires organization membership
  • Example: @acme/internal-tools

​
Health Check

Check API availability: 
GET /api/health
Response: 
{
  "status": "ok"
}

​
Error Codes

CodeMeaning
400Bad Request - Invalid input or malformed JSON
401Unauthorized - Missing or invalid authentication
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
409Conflict - Resource already exists (e.g., version)
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server-side failure

​
Next Steps

Authentication

Learn how to authenticate with API keys

Skills API

Publish and manage skills

Search API

Discover skills with full-text search

Security Scanning

Understand security analysis endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us