ToolsShow API Reference

Base URL: /api/v1

All JSON responses (except binary download stream) use the wrapper:

{
  "code": 0,
  "message": "ok",
  "data": {},
  "traceId": "uuid",
  "timestamp": "2026-03-26T10:10:00.000Z"
}

Public APIs

Method	Path	Description
GET	`/health`	Liveness/readiness check
GET	`/tools`	Query tools list (query/category/sort/page/pageSize)
GET	`/tools/:id`	Tool detail
POST	`/tools/:id/launch`	Unified launch (web/download)
GET	`/downloads/:ticket`	Consume ticket and stream artifact
GET	`/categories`	Category list with tool count
GET	`/keywords/hot`	Hot keyword list
GET	`/overview`	KPI overview

`GET /tools` query params

Param	Type	Required	Default
`query`	string	No	-
`category`	string	No	`all`
`sortBy`	`popular \| latest \| rating \| name`	No	`latest`
`page`	number	No	`1`
`pageSize`	number (1-50)	No	`6`

`POST /tools/:id/launch` body

{
  "channel": "official",
  "clientVersion": "web-1.0.0"
}

Web mode response:

{
  "mode": "web",
  "actionUrl": "https://example.com",
  "openIn": "new_tab"
}

Download mode response:

{
  "mode": "download",
  "ticket": "dl_tk_xxx",
  "expiresInSec": 120,
  "actionUrl": "/api/v1/downloads/dl_tk_xxx"
}

Admin Auth APIs

Auth header for protected admin APIs:

Authorization: Bearer <accessToken>

Method	Path	Auth	Description
POST	`/admin/auth/login`	No	Admin login
POST	`/admin/auth/refresh`	No	Refresh tokens
POST	`/admin/auth/logout`	Yes	Admin logout
GET	`/admin/auth/me`	Yes	Current admin profile

Default seeded admin account:

username: admin
password: admin123456

Admin Tool APIs

Method	Path	Description
GET	`/admin/tools`	Query tools
POST	`/admin/tools`	Create tool
GET	`/admin/tools/:id`	Tool detail
PATCH	`/admin/tools/:id`	Update tool
PATCH	`/admin/tools/:id/status`	Update tool status
PATCH	`/admin/tools/:id/access-mode`	Switch access mode
DELETE	`/admin/tools/:id`	Soft delete tool

Create/Update tool payload core fields

{
  "name": "Tool Name",
  "categoryId": "cat_dev",
  "description": "Tool description",
  "rating": 4.5,
  "tags": ["tag_hot", "tag_free"],
  "features": ["Feature A", "Feature B"],
  "accessMode": "web",
  "openUrl": "https://example.com",
  "openInNewTab": true,
  "status": "draft"
}

Admin Artifact APIs

Method	Path	Description
POST	`/admin/tools/:id/artifacts`	Upload artifact (`multipart/form-data`)
GET	`/admin/tools/:id/artifacts`	List artifacts
PATCH	`/admin/tools/:id/artifacts/:artifactId/latest`	Set latest artifact
PATCH	`/admin/tools/:id/artifacts/:artifactId/status`	Update artifact status
DELETE	`/admin/tools/:id/artifacts/:artifactId`	Soft delete artifact metadata

Upload form fields

Field	Type	Required
`file`	binary	Yes
`version`	string	Yes
`releaseNotes`	string	No
`isLatest`	boolean	No (default `true`)

Admin Audit APIs

Method	Path	Description
GET	`/admin/audit-logs`	Query admin audit logs

Query params:

Param	Type	Required
`action`	string	No
`resourceType`	string	No
`adminUserId`	string	No
`page`	number	No
`pageSize`	number	No

Error Codes

Code	Meaning
`1001`	validation failed
`1002`	unauthorized
`1003`	forbidden
`1004`	resource not found
`1005`	conflict
`1010`	invalid credentials
`1011`	token invalid/expired
`1201`	GitLab upload failed
`1202`	GitLab download failed
`1203`	artifact not available
`1204`	download ticket invalid/expired
`1210`	tool access mode mismatch
`1211`	web open URL not configured
`1500`	internal server error

4.0 KiB Raw Permalink Blame History