docs/index.tsxpublic api v1.1
RESTOpenAPI 3.1Bearer Auth
> Skills Marketplace API Docs
文档页现在围绕“浏览和筛选技能”来组织。你可以只传分类、标签，也可以叠加关键词，再按热度或最近更新排序。
readme.flowrecommended path
先在 Dashboard 生成 API Key，再复制示例请求测试筛选能力。
确认响应结构后，再根据配额头和错误码补齐客户端的异常处理。
如果你要导入工具链、生成 SDK 或同步团队文档，直接使用 OpenAPI JSON。
quickstart.sh3 steps
01 · 获取密钥
在 Dashboard 创建 `sk_live_*` API Key。
02 · 发起第一个请求
curl example
curl -X GET "https://your-domain.com/api/v1/skills/search?category=Utilities&tag=search&page=1&limit=10&sortBy=popular" \ -H "Authorization: Bearer sk_live_your_api_key"
03 · 处理响应与配额
读取 `success/data/page/limit/total/totalPages/filters`，并同时关注 `X-RateLimit-Daily-*` 响应头。
auth.mdbearer
鉴权
将控制台生成的 API Key 放入 Authorization 头中：
authorization header
Authorization: Bearer sk_live_your_api_key
缺少或格式错误时返回 `401 MISSING_API_KEY`；值无效时返回 `401 INVALID_API_KEY`。
rate-limit.mdutc daily quota
配额与响应头
每个 API Key 都有独立的每日调用上限，按 UTC 0 点重置。
X-RateLimit-Daily-Limit
当前密钥日配额上限。
X-RateLimit-Daily-Remaining
当前 UTC 日剩余成功请求数。
当配额用尽时，接口返回 `429 DAILY_QUOTA_EXCEEDED`。
GET /api/v1/skills/searchbrowse + filter
这是公开技能发现接口。你可以只传 `category`、`tag` 做筛选，也可以叠加 `q` 关键词，再用 `sortBy` 控制排序。
qstringrequired: 否
可选关键词，匹配 name、description、category、tags
categorystringrequired: 否
按分类筛选，例如 Utilities
tagstringrequired: 否
按标签筛选，精确匹配单个 tag
pageintegerrequired: 否
页码，从 1 开始，默认 1
limitintegerrequired: 否
每页数量，默认 24，最大 100
sortByrecent | popularrequired: 否
recent 按更新时间倒序，其他值按热度排序
response example
{
"success": true,
"data": [
{
"id": "cm0abc123xyz",
"slug": "csv-pipeline",
"name": "CSV Pipeline",
"description": "Process, transform, and analyze CSV datasets.",
"category": "data",
"tags": ["csv", "etl", "analysis"],
"status": "APPROVED",
"filePath": "skills/csv-pipeline/SKILL.md",
"frontmatter": null,
"frontmatterRaw": null,
"downloads": 128,
"createdAt": "2026-03-01T09:30:00.000Z",
"updatedAt": "2026-03-08T14:12:00.000Z",
"authorId": "user_123"
}
],
"page": 1,
"limit": 10,
"total": 42,
"totalPages": 5,
"filters": {
"q": null,
"category": "Utilities",
"tag": "search",
"sortBy": "popular"
}
}GET /api/v1/skills/ai-searchexperimental alias
`AI Search` 当前仍是实验性别名接口，返回结构与普通搜索一致，适合作为未来智能检索入口的兼容地址。
curl example
curl -X GET "https://your-domain.com/api/v1/skills/ai-search?q=spreadsheet%20automation&sortBy=recent" \ -H "Authorization: Bearer sk_live_your_api_key"
errors.tsstandard envelope
MISSING_API_KEYHTTP 401
未提供 Authorization 头或格式不正确
INVALID_API_KEYHTTP 401
API Key 无效或已不可用
DAILY_QUOTA_EXCEEDEDHTTP 429
超过当前 UTC 日配额
error example
{
"success": false,
"error": {
"code": "DAILY_QUOTA_EXCEEDED",
"message": "Daily API quota exceeded"
}
}openapi.jsonmachine-readable spec
OpenAPI 3.1 文档
推荐先直接打开 JSON 导入 Postman、Insomnia 或 SDK 生成器。只有在需要人工检查字段时再展开完整内容。
展开完整 OpenAPI JSON
{
"openapi": "3.1.0",
"info": {
"title": "Skills Marketplace API",
"version": "1.1.0",
"description": "REST API for browsing approved agent skills with API key authentication and daily quota limits."
},
"servers": [
{
"url": "/",
"description": "Current deployment"
}
],
"tags": [
{
"name": "Skills",
"description": "Public skill discovery endpoints"
}
],
"components": {
"securitySchemes": {
"BearerApiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "API Key",
"description": "Use the API key value returned from the dashboard, e.g. Bearer sk_live_xxx"
}
},
"schemas": {
"Skill": {
"type": "object",
"required": [
"id",
"slug",
"name",
"description",
"tags",
"status",
"filePath",
"downloads",
"createdAt",
"updatedAt",
"authorId"
],
"properties": {
"id": {
"type": "string",
"example": "cm0abc123xyz"
},
"slug": {
"type": "string",
"example": "csv-pipeline"
},
"name": {
"type": "string",
"example": "CSV Pipeline"
},
"description": {
"type": "string",
"example": "Process, transform, and analyze CSV datasets."
},
"category": {
"type": [
"string",
"null"
],
"example": "data"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"csv",
"etl",
"analysis"
]
},
"status": {
"type": "string",
"enum": [
"PENDING",
"APPROVED",
"REJECTED"
],
"example": "APPROVED"
},
"filePath": {
"type": "string",
"example": "skills/csv-pipeline/SKILL.md"
},
"frontmatter": {
"description": "Raw frontmatter JSON when available.",
"nullable": true
},
"frontmatterRaw": {
"type": [
"string",
"null"
],
"example": "name: CSV Pipeline"
},
"downloads": {
"type": "integer",
"example": 128
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"authorId": {
"type": "string",
"example": "user_123"
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"success",
"data",
"page",
"limit",
"total",
"totalPages",
"filters"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Skill"
}
},
"page": {
"type": "integer",
"example": 1
},
"limit": {
"type": "integer",
"example": 24
},
"total": {
"type": "integer",
"example": 42
},
"totalPages": {
"type": "integer",
"example": 2
},
"filters": {
"type": "object",
"properties": {
"q": {
"type": [
"string",
"null"
],
"example": "csv"
},
"category": {
"type": [
"string",
"null"
],
"example": "data"
},
"tag": {
"type": [
"string",
"null"
],
"example": "analysis"
},
"sortBy": {
"type": "string",
"enum": [
"popular",
"recent"
],
"example": "popular"
}
}
},
"note": {
"type": "string",
"nullable": true
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"MISSING_API_KEY",
"INVALID_API_KEY",
"DAILY_QUOTA_EXCEEDED"
],
"example": "INVALID_API_KEY"
},
"message": {
"type": "string",
"example": "Invalid API key"
}
}
}
}
}
},
"parameters": {
"Query": {
"name": "q",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Optional keyword query. Matches name, description, category, and tags."
},
"Category": {
"name": "category",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Optional category filter."
},
"Tag": {
"name": "tag",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Optional exact tag filter."
},
"Page": {
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "1-based page number."
},
"Limit": {
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 24
},
"description": "Page size. Values above 100 are clamped to 100."
},
"SortBy": {
"name": "sortBy",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"recent",
"popular"
]
},
"description": "Sort order. `recent` sorts by update time descending. Any other value falls back to popularity."
}
},
"responses": {
"Unauthorized": {
"description": "Authorization header is missing, malformed, or the API key is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"QuotaExceeded": {
"description": "Daily quota exhausted for this API key.",
"headers": {
"X-RateLimit-Daily-Limit": {
"schema": {
"type": "string"
},
"description": "Configured daily quota limit."
},
"X-RateLimit-Daily-Remaining": {
"schema": {
"type": "string"
},
"description": "Remaining successful requests for the current UTC day."
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"paths": {
"/api/v1/skills/search": {
"get": {
"tags": [
"Skills"
],
"summary": "Browse approved skills",
"description": "Browse approved skills with optional keyword, category, tag, paging, and sorting parameters.",
"security": [
{
"BearerApiKey": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/Query"
},
{
"$ref": "#/components/parameters/Category"
},
{
"$ref": "#/components/parameters/Tag"
},
{
"$ref": "#/components/parameters/Page"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/SortBy"
}
],
"responses": {
"200": {
"description": "Search result page.",
"headers": {
"X-RateLimit-Daily-Limit": {
"schema": {
"type": "string"
},
"description": "Configured daily quota limit."
},
"X-RateLimit-Daily-Remaining": {
"schema": {
"type": "string"
},
"description": "Remaining successful requests for the current UTC day."
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/QuotaExceeded"
}
}
}
},
"/api/v1/skills/ai-search": {
"get": {
"tags": [
"Skills"
],
"summary": "AI-assisted skill search",
"description": "Experimental alias for search. Current retrieval logic is the same as the standard search endpoint.",
"security": [
{
"BearerApiKey": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/Query"
},
{
"$ref": "#/components/parameters/Category"
},
{
"$ref": "#/components/parameters/Tag"
},
{
"$ref": "#/components/parameters/Page"
},
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/SortBy"
}
],
"responses": {
"200": {
"description": "AI search result page.",
"headers": {
"X-RateLimit-Daily-Limit": {
"schema": {
"type": "string"
},
"description": "Configured daily quota limit."
},
"X-RateLimit-Daily-Remaining": {
"schema": {
"type": "string"
},
"description": "Remaining successful requests for the current UTC day."
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/QuotaExceeded"
}
}
}
}
}
}