API 參考概覽
Vecstruct REST API 讓你直接用 HTTP 呼叫所有功能，不依賴任何 SDK。
Base URL
https://api.vecstruct.com/v1
認證
所有請求都需要在 Header 帶入 Bearer Token：
Authorization: Bearer sk-your-api-key
回應格式
所有 API 回應的 JSON 結構如下：
{
"success": true,
"code": 1000,
"message": "Success",
"data": { ... }
}
| 欄位 | 類型 | 說明 |
|---|---|---|
success | boolean | 請求是否成功 |
code | number | 業務狀態碼（1000 代表成功） |
message | string | 狀態描述或錯誤訊息 |
data | object / array | 回應的資料主體 |
例外：
- AI Gateway 端點
POST /v1/chat/completions、POST /v1/embeddings、POST /v1/rerank使用 OpenAI 相容格式，並附加vecstruct擴充欄位。
分頁
列表型 API 回傳分頁結構：
{
"success": true,
"code": 1000,
"message": "Success",
"data": {
"items": [...],
"total": 150,
"page": 1,
"page_size": 20,
"total_pages": 8
}
}
常見錯誤碼
| HTTP | Code 範圍 | 說明 |
|---|---|---|
| 400 | 1002-1004, 1200-1204 | 請求格式或參數錯誤 |
| 401 | 1100-1112 | API Key 缺失或無效 |
| 402 | 1500-1508, 2400 | 餘額、配額不足或預算上限已達 |
| 403 | 1105, 1113 | 權限不足 |
| 404 | 1300-1310 | 資源不存在 |
| 429 | 1007 | 速率限制 |
| 500 | 1900-1905 | 伺服器錯誤 |
API 端點清單
| 類別 | 端點 |
|---|---|
| 認證 | GET /v1/auth/me |
| Chat Completions | POST /v1/chat/completions |
| Embeddings | POST /v1/embeddings |
| Rerank | POST /v1/rerank |
| Models | GET /v1/models |
| RAG 查詢 | POST /v1/rag/query |
| Memory | GET/POST/PUT/DELETE /v1/memories |
| Documents | GET/POST/DELETE/PATCH /v1/documents |
| Audit Logs | GET /v1/audit/logs、GET /v1/audit/logs/{audit_id}、POST /v1/audit/logs/export |
| 健康檢查 | GET /v1/health |