Back to Details

pinterest-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pinterest Automation Dashboard — API Reference

Pinterest Automation Dashboard — API Reference

API endpoints on the 
/api/
prefix require authentication via either:
  • Session cookie (browser login)
  • API key in 
    Authorization: Bearer <key>
    header
Base URL for API endpoints: 
http://<host>:5000/api/
Authentication endpoints (login/logout) are on the root path, not 
/api/
.
所有以
/api/
为前缀的API端点需要通过以下方式之一进行认证：
  • Session cookie（浏览器登录）
  • API key，放在
    Authorization: Bearer <key>
    请求头中
API端点的基础URL：
http://<host>:5000/api/
认证端点（登录/登出）位于根路径，而非
/api/
下。

Authentication

认证

These endpoints are not under 
/api/
— they use the root URL 
http://<host>:5000/
.
MethodEndpointDescription
POST
/auth/login
Login with username/password. Sets session cookie. Body: form 
username
+ 
password
.
GET
/auth/logout
Logout and clear session.
python
import requests

session = requests.Session()
session.post("http://host:5000/auth/login", data={"username": "admin", "password": "pass"})
For all subsequent examples, we use API key auth instead of session cookies:
python
import requests

BASE = "http://host:5000/api"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
这些端点不在
/api/
下——它们使用根URL 
http://<host>:5000/
。
MethodEndpointDescription
POST
/auth/login
使用用户名/密码登录。设置会话Cookie。请求体为表单格式，包含
username
和
password
字段。
GET
/auth/logout
登出并清除会话。
python
import requests

session = requests.Session()
session.post("http://host:5000/auth/login", data={"username": "admin", "password": "pass"})
在后续所有示例中，我们使用API key认证而非会话Cookie：
python
import requests

BASE = "http://host:5000/api"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

Accounts

账户

List & Detail

列表与详情

MethodEndpointDescription
GET
/accounts
List all accounts with stats (paginated).
GET
/accounts/<username>
Get full account detail: proxy, boards, stats, limits.
GET /accounts query params:
  • page
    (int, default 1)
  • per_page
    (int, default 50, max 200)
  • search
    (string) — filter by username
  • category
    (string) — filter by category name
  • category_id
    (int) — filter by category ID
  • proxy_mode
    (string) — 
    iproyal
    , 
    custom
    , or 
    direct
  • status
    (string) — automation status filter
  • direct_save
    (string) — filter by direct save enabled
  • week
    (string) — filter by smart saves week
Python:
python
resp = requests.get(f"{BASE}/accounts", headers=HEADERS, params={"per_page": 100})
data = resp.json()
MethodEndpointDescription
GET
/accounts
列出所有带统计数据的账户（支持分页）。
GET
/accounts/<username>
获取账户完整详情：代理、看板、统计数据、限制。
GET /accounts 查询参数：
  • page
    （整数，默认值1）
  • per_page
    （整数，默认值50，最大值200）
  • search
    （字符串）——按用户名筛选
  • category
    （字符串）——按分类名称筛选
  • category_id
    （整数）——按分类ID筛选
  • proxy_mode
    （字符串）——
    iproyal
    、
    custom
    或
    direct
  • status
    （字符串）——按自动化状态筛选
  • direct_save
    （字符串）——按是否启用直接保存筛选
  • week
    （字符串）——按智能保存周数筛选
Python示例：
python
resp = requests.get(f"{BASE}/accounts", headers=HEADERS, params={"per_page": 100})
data = resp.json()

{"accounts": [...], "total": 13, "page": 1, "per_page": 100, "total_pages": 1,

{"accounts": [...], "total": 13, "page": 1, "per_page": 100, "total_pages": 1,

"total_all": 13, "categories_tree": [...], "uncategorized_count": 2}

"total_all": 13, "categories_tree": [...], "uncategorized_count": 2}

detail = requests.get(f"{BASE}/accounts/mindfulrecipes", headers=HEADERS).json()
detail = requests.get(f"{BASE}/accounts/mindfulrecipes", headers=HEADERS).json()

{"username": "mindfulrecipes", "has_cookies": true, "has_fingerprint": true,

{"username": "mindfulrecipes", "has_cookies": true, "has_fingerprint": true,

"proxy": "http://...", "proxy_mode": "direct", "boards": [...], "board_count": 12,

"proxy": "http://...", "proxy_mode": "direct", "boards": [...], "board_count": 12,

"stats": {"total_sessions": 61, "total_saved": 357, "today_saves": 0, ...}}

"stats": {"total_sessions": 61, "total_saved": 357, "today_saves": 0, ...}}


**cURL:**
```bash
curl -H "Authorization: Bearer $KEY" "http://host:5000/api/accounts?per_page=100"
curl -H "Authorization: Bearer $KEY" "http://host:5000/api/accounts/mindfulrecipes"

**cURL示例：**
```bash
curl -H "Authorization: Bearer $KEY" "http://host:5000/api/accounts?per_page=100"
curl -H "Authorization: Bearer $KEY" "http://host:5000/api/accounts/mindfulrecipes"

Add & Import

添加与导入

MethodEndpointDescription
POST
/accounts/add
Add single account. Multipart form: 
username
, 
cookies
(file), 
fingerprint
(file, optional), 
proxy
, 
proxy_mode
, 
category
.
POST
/accounts/bulk-import
Import multiple accounts from JSON body.
POST
/accounts/bulk-upload
Upload multiple accounts with files. Multipart form with folder structure.
POST
/accounts/sync
One-time CSV→DB import. Reads 
accounts.csv
+ 
Accounts/
directories into DB.
Python — add single account:
python
with open("cookies.json", "rb") as c, open("fingerprint.json", "rb") as f:
    resp = requests.post(f"{BASE}/accounts/add", headers=HEADERS,
        data={"username": "myaccount", "proxy_mode": "iproyal", "category": "food"},
        files={"cookies": c, "fingerprint": f})
MethodEndpointDescription
POST
/accounts/add
添加单个账户。多部分表单格式：
username
、
cookies
（文件）、
fingerprint
（可选文件）、
proxy
、
proxy_mode
、
category
。
POST
/accounts/bulk-import
通过JSON请求体批量导入多个账户。
POST
/accounts/bulk-upload
上传包含文件的多个账户。带文件夹结构的多部分表单格式。
POST
/accounts/sync
一次性CSV→数据库导入。读取
accounts.csv
和
Accounts/
目录内容到数据库。
Python示例——添加单个账户：
python
with open("cookies.json", "rb") as c, open("fingerprint.json", "rb") as f:
    resp = requests.post(f"{BASE}/accounts/add", headers=HEADERS,
        data={"username": "myaccount", "proxy_mode": "iproyal", "category": "food"},
        files={"cookies": c, "fingerprint": f})

{"success": true, "username": "myaccount", "sync": {"fetched_boards": 12, ...}}

{"success": true, "username": "myaccount", "sync": {"fetched_boards": 12, ...}}


**Python — bulk import (JSON):**
```python
resp = requests.post(f"{BASE}/accounts/bulk-import", headers=HEADERS, json={
    "accounts": [
        {"username": "user1", "proxy": "http://...", "category": "food"},
        {"username": "user2"}
    ]
})

**Python示例——批量导入（JSON格式）：**
```python
resp = requests.post(f"{BASE}/accounts/bulk-import", headers=HEADERS, json={
    "accounts": [
        {"username": "user1", "proxy": "http://...", "category": "food"},
        {"username": "user2"}
    ]
})

{"success": true, "imported": 2, "skipped": 0, "sync_queued": 2, "errors": []}

{"success": true, "imported": 2, "skipped": 0, "sync_queued": 2, "errors": []}


**cURL — add account:**
```bash
curl -X POST -H "Authorization: Bearer $KEY" \
  -F "username=myaccount" -F "proxy_mode=iproyal" -F "cookies=@cookies.json" \
  http://host:5000/api/accounts/add

**cURL示例——添加账户：**
```bash
curl -X POST -H "Authorization: Bearer $KEY" \
  -F "username=myaccount" -F "proxy_mode=iproyal" -F "cookies=@cookies.json" \
  http://host:5000/api/accounts/add

Modify

修改

MethodEndpointDescription
PUT/POST
/accounts/<username>/update
Update account files/proxy/category. Multipart form: 
cookies
(file), 
fingerprint
(file), 
proxy
, 
category
, 
category_id
.
POST
/accounts/<username>/rename
Rename account. Body: 
{"new_username": "..."}
POST
/accounts/<username>/proxy-mode
Set proxy mode. Body: `{"mode": "iproyal
Python:
python
resp = requests.post(f"{BASE}/accounts/myaccount/proxy-mode", headers=HEADERS,
    json={"mode": "direct"})
MethodEndpointDescription
PUT/POST
/accounts/<username>/update
更新账户文件/代理/分类。多部分表单格式：
cookies
（文件）、
fingerprint
（文件）、
proxy
、
category
、
category_id
。
POST
/accounts/<username>/rename
重命名账户。请求体：
{"new_username": "..."}
POST
/accounts/<username>/proxy-mode
设置代理模式。请求体：`{"mode": "iproyal
Python示例：
python
resp = requests.post(f"{BASE}/accounts/myaccount/proxy-mode", headers=HEADERS,
    json={"mode": "direct"})

{"success": true, "proxy_mode": "direct", "proxy": "", "location": ""}

{"success": true, "proxy_mode": "direct", "proxy": "", "location": ""}

undefined
undefined

Delete

删除

MethodEndpointDescription
DELETE
/accounts/<username>
Delete single account (removes folder + DB records).
POST
/accounts/batch/delete
Batch delete. Body: 
{"usernames": ["user1", "user2"]}
cURL:
bash
curl -X DELETE -H "Authorization: Bearer $KEY" http://host:5000/api/accounts/myaccount
MethodEndpointDescription
DELETE
/accounts/<username>
删除单个账户（移除文件夹和数据库记录）。
POST
/accounts/batch/delete
批量删除。请求体：
{"usernames": ["user1", "user2"]}
cURL示例：
bash
curl -X DELETE -H "Authorization: Bearer $KEY" http://host:5000/api/accounts/myaccount

Batch Operations

批量操作

MethodEndpointDescription
POST
/accounts/batch/set-category
Set category for multiple accounts. Body: 
{"usernames": [...], "category_id": 5}
POST
/accounts/batch/proxy-mode
Set proxy mode for multiple accounts. Body: 
{"usernames": [...], "mode": "direct"}
MethodEndpointDescription
POST
/accounts/batch/set-category
为多个账户设置分类。请求体：
{"usernames": [...], "category_id": 5}
POST
/accounts/batch/proxy-mode
为多个账户设置代理模式。请求体：
{"usernames": [...], "mode": "direct"}

Sync Status

同步状态

MethodEndpointDescription
GET
/accounts/sync-status
Check bulk board sync progress after import.
MethodEndpointDescription
GET
/accounts/sync-status
检查导入后的批量看板同步进度。

Automation (Save)

自动化（保存）

Enable/Disable

启用/禁用

MethodEndpointDescription
POST
/automation/<username>/enable
Enable save automation for account.
POST
/automation/<username>/disable
Disable save automation for account.
POST
/automation/batch/enable
Batch enable. Body: 
{"usernames": [...]}
POST
/automation/batch/disable
Batch disable. Body: 
{"usernames": [...]}
Python:
python
requests.post(f"{BASE}/automation/mindfulrecipes/enable", headers=HEADERS)
MethodEndpointDescription
POST
/automation/<username>/enable
启用账户的保存自动化功能。
POST
/automation/<username>/disable
禁用账户的保存自动化功能。
POST
/automation/batch/enable
批量启用。请求体：
{"usernames": [...]}
POST
/automation/batch/disable
批量禁用。请求体：
{"usernames": [...]}
Python示例：
python
requests.post(f"{BASE}/automation/mindfulrecipes/enable", headers=HEADERS)

{"success": true, "message": "Automation enabled for mindfulrecipes"}

{"success": true, "message": "Automation enabled for mindfulrecipes"}

requests.post(f"{BASE}/automation/batch/enable", headers=HEADERS, json={"usernames": ["user1", "user2", "user3"]})
requests.post(f"{BASE}/automation/batch/enable", headers=HEADERS, json={"usernames": ["user1", "user2", "user3"]})

{"success": true, "results": {"user1": "enabled", "user2": "enabled", ...}}

{"success": true, "results": {"user1": "enabled", "user2": "enabled", ...}}


**cURL:**
```bash
curl -X POST -H "Authorization: Bearer $KEY" http://host:5000/api/automation/mindfulrecipes/enable

**cURL示例：**
```bash
curl -X POST -H "Authorization: Bearer $KEY" http://host:5000/api/automation/mindfulrecipes/enable

Status

状态

MethodEndpointDescription
GET
/automation/status
Get all automation statuses (running, sleeping, waiting, error).
Response:
json
{
  "jobs": {
    "mindfulrecipes": {
      "active": true, "status": "sleeping", "next_run": 1713300000,
      "sessions_today": 1, "sessions_remaining": 2,
      "pins_saved": 15, "pins_created": 0, "error": null
    }
  }
}
MethodEndpointDescription
GET
/automation/status
获取所有自动化任务状态（运行中、休眠、等待、错误）。
响应示例：
json
{
  "jobs": {
    "mindfulrecipes": {
      "active": true, "status": "sleeping", "next_run": 1713300000,
      "sessions_today": 1, "sessions_remaining": 2,
      "pins_saved": 15, "pins_created": 0, "error": null
    }
  }
}

Limits

限制

MethodEndpointDescription
POST
/accounts/<username>/saves-limit
Set daily saves limit override. Body: 
{"daily_saves_limit_max": 30}
or 
{"clear": true}
POST
/automation/batch/saves-limit
Batch set saves limit. Body: 
{"usernames": [...], "daily_saves_limit_max": 30}
MethodEndpointDescription
POST
/accounts/<username>/saves-limit
设置每日保存上限覆盖值。请求体：
{"daily_saves_limit_max": 30}
或
{"clear": true}
POST
/automation/batch/saves-limit
批量设置保存上限。请求体：
{"usernames": [...], "daily_saves_limit_max": 30}

Schedule

调度

MethodEndpointDescription
GET
/accounts/<username>/schedule
Get account schedule (smart automation managed).
POST
/accounts/<username>/schedule
Update schedule (currently smart-managed, returns info).
MethodEndpointDescription
GET
/accounts/<username>/schedule
获取账户调度信息（由智能自动化管理）。
POST
/accounts/<username>/schedule
更新调度信息（当前为智能管理，返回相关信息）。

Automation (Create)

自动化（创建）

Enable/Disable

启用/禁用

MethodEndpointDescription
POST
/automation/<username>/create/enable
Enable create automation.
POST
/automation/<username>/create/disable
Disable create automation.
POST
/automation/batch/create/enable
Batch enable create. Body: 
{"usernames": [...]}
POST
/automation/batch/create/disable
Batch disable create. Body: 
{"usernames": [...]}
MethodEndpointDescription
POST
/automation/<username>/create/enable
启用创建自动化功能。
POST
/automation/<username>/create/disable
禁用创建自动化功能。
POST
/automation/batch/create/enable
批量启用创建功能。请求体：
{"usernames": [...]}
POST
/automation/batch/create/disable
批量禁用创建功能。请求体：
{"usernames": [...]}

Status & Limits

状态与限制

MethodEndpointDescription
GET
/automation/create/status
Get create automation statuses.
POST
/accounts/<username>/creates-limit
Set daily creates limit. Body: 
{"daily_creates": 10}
POST
/automation/batch/creates-limit
Batch set creates limit. Body: 
{"usernames": [...], "daily_creates": 10}
MethodEndpointDescription
GET
/automation/create/status
获取创建自动化任务状态。
POST
/accounts/<username>/creates-limit
设置每日创建上限。请求体：
{"daily_creates": 10}
POST
/automation/batch/creates-limit
批量设置创建上限。请求体：
{"usernames": [...], "daily_creates": 10}

Direct Save

直接保存

MethodEndpointDescription
PATCH
/accounts/<username>/direct-save
Toggle direct save. Body: 
{"enabled": true}
POST
/accounts/batch/direct-save
Batch toggle. Body: 
{"usernames": [...], "enabled": true}
Python:
python
requests.patch(f"{BASE}/accounts/mindfulrecipes/direct-save", headers=HEADERS,
    json={"enabled": True})
MethodEndpointDescription
PATCH
/accounts/<username>/direct-save
切换直接保存功能。请求体：
{"enabled": true}
POST
/accounts/batch/direct-save
批量切换直接保存功能。请求体：
{"usernames": [...], "enabled": true}
Python示例：
python
requests.patch(f"{BASE}/accounts/mindfulrecipes/direct-save", headers=HEADERS,
    json={"enabled": True})

{"success": true, "direct_save_enabled": true}

{"success": true, "direct_save_enabled": true}


---

---

Boards

看板

MethodEndpointDescription
GET
/accounts/<username>/boards
List boards for account.
POST
/accounts/<username>/sync-boards
Fetch boards from Pinterest API and sync locally.
POST
/accounts/<username>/create-board
Create board(s) on Pinterest.
POST
/accounts/<username>/upload-boards
Upload boards CSV file.
DELETE
/accounts/<username>/boards/<board_id>
Delete a board on Pinterest.
POST /accounts/<username>/create-board body (single):
json
{"name": "Board Name", "description": "...", "privacy": "public"}
POST /accounts/<username>/create-board body (multiple):
json
{
  "boards": [
    {"name": "Board 1", "description": "...", "privacy": "public"},
    {"name": "Board 2", "privacy": "secret"}
  ]
}
Or using names array:
json
{"names": ["Board 1", "Board 2"], "description": "...", "privacy": "public"}
Python — sync boards:
python
resp = requests.post(f"{BASE}/accounts/mindfulrecipes/sync-boards", headers=HEADERS)
MethodEndpointDescription
GET
/accounts/<username>/boards
列出账户的看板。
POST
/accounts/<username>/sync-boards
从Pinterest API获取看板并同步到本地。
POST
/accounts/<username>/create-board
在Pinterest上创建看板。
POST
/accounts/<username>/upload-boards
上传看板CSV文件。
DELETE
/accounts/<username>/boards/<board_id>
在Pinterest上删除看板。
POST /accounts/<username>/create-board 请求体（单个看板）：
json
{"name": "Board Name", "description": "...", "privacy": "public"}
POST /accounts/<username>/create-board 请求体（多个看板）：
json
{
  "boards": [
    {"name": "Board 1", "description": "...", "privacy": "public"},
    {"name": "Board 2", "privacy": "secret"}
  ]
}
或使用名称数组：
json
{"names": ["Board 1", "Board 2"], "description": "...", "privacy": "public"}
Python示例——同步看板：
python
resp = requests.post(f"{BASE}/accounts/mindfulrecipes/sync-boards", headers=HEADERS)

{"success": true, "fetched_boards": 12, "created_boards": 0, "errors": [],

{"success": true, "fetched_boards": 12, "created_boards": 0, "errors": [],

"boards": [{"name": "Easy Recipes", "board_id": "123456789", "privacy": "public"}, ...]}

"boards": [{"name": "Easy Recipes", "board_id": "123456789", "privacy": "public"}, ...]}


**Python — upload boards CSV:**
```python
with open("boards.csv", "rb") as f:
    resp = requests.post(f"{BASE}/accounts/mindfulrecipes/upload-boards",
        headers=HEADERS, files={"csv": f})

**Python示例——上传看板CSV：**
```python
with open("boards.csv", "rb") as f:
    resp = requests.post(f"{BASE}/accounts/mindfulrecipes/upload-boards",
        headers=HEADERS, files={"csv": f})

{"success": true, "board_count": 12, "synced": true, "boards": [...]}

{"success": true, "board_count": 12, "synced": true, "boards": [...]}


**cURL:**
```bash
curl -X POST -H "Authorization: Bearer $KEY" http://host:5000/api/accounts/mindfulrecipes/sync-boards
curl -X POST -H "Authorization: Bearer $KEY" -F "csv=@boards.csv" http://host:5000/api/accounts/mindfulrecipes/upload-boards

**cURL示例：**
```bash
curl -X POST -H "Authorization: Bearer $KEY" http://host:5000/api/accounts/mindfulrecipes/sync-boards
curl -X POST -H "Authorization: Bearer $KEY" -F "csv=@boards.csv" http://host:5000/api/accounts/mindfulrecipes/upload-boards

Pin Queue (Create)

Pin创建队列

MethodEndpointDescription
GET
/accounts/<username>/pins/queue
List pin creation queue. Returns pins array + counts.
POST
/accounts/<username>/pins/queue
Add single pin to queue.
PUT
/accounts/<username>/pins/queue/<index>
Edit pin at index.
DELETE
/accounts/<username>/pins/queue/<index>
Remove pin at index.
POST
/accounts/<username>/pins/upload-csv
Upload pins CSV file to queue.
POST
/accounts/<username>/pins/create-run
Start pin creation job. Optional body: 
{"indices": [0, 2, 5]}
GET
/accounts/<username>/pins/create-status
Check pin creation job status.
POST /accounts/<username>/pins/queue body:
json
{
  "board_id": "123456789",
  "image_url": "https://example.com/image.jpg",
  "title": "My Pin",
  "description": "Pin description",
  "link": "https://example.com",
  "alt_text": "Alt text"
}
Python — upload CSV and start creation:
python
with open("pins.csv", "rb") as f:
    resp = requests.post(f"{BASE}/accounts/mindfulrecipes/pins/upload-csv",
        headers=HEADERS, files={"csv": f})
MethodEndpointDescription
GET
/accounts/<username>/pins/queue
列出Pin创建队列，返回Pin数组和统计数量。
POST
/accounts/<username>/pins/queue
添加单个Pin到队列。
PUT
/accounts/<username>/pins/queue/<index>
编辑队列中指定索引的Pin。
DELETE
/accounts/<username>/pins/queue/<index>
删除队列中指定索引的Pin。
POST
/accounts/<username>/pins/upload-csv
上传Pin CSV文件到队列。
POST
/accounts/<username>/pins/create-run
启动Pin创建任务。可选请求体：
{"indices": [0, 2, 5]}
GET
/accounts/<username>/pins/create-status
检查Pin创建任务状态。
POST /accounts/<username>/pins/queue 请求体：
json
{
  "board_id": "123456789",
  "image_url": "https://example.com/image.jpg",
  "title": "My Pin",
  "description": "Pin description",
  "link": "https://example.com",
  "alt_text": "Alt text"
}
Python示例——上传CSV并启动创建任务：
python
with open("pins.csv", "rb") as f:
    resp = requests.post(f"{BASE}/accounts/mindfulrecipes/pins/upload-csv",
        headers=HEADERS, files={"csv": f})

{"success": true, "added": 25, "skipped": 0, "total": 25}

{"success": true, "added": 25, "skipped": 0, "total": 25}

requests.post(f"{BASE}/accounts/mindfulrecipes/pins/create-run", headers=HEADERS)
requests.post(f"{BASE}/accounts/mindfulrecipes/pins/create-run", headers=HEADERS)

{"success": true, "message": "Pin creation started for mindfulrecipes"}

{"success": true, "message": "Pin creation started for mindfulrecipes"}

import time while True: status = requests.get(f"{BASE}/accounts/mindfulrecipes/pins/create-status", headers=HEADERS).json() print(f"{status['status']}: {status['created']}/{status['target']}") if status["status"] in ("completed", "failed", "idle"): break time.sleep(5)

**cURL:**
```bash
curl -H "Authorization: Bearer $KEY" -F "csv=@pins.csv" http://host:5000/api/accounts/mindfulrecipes/pins/upload-csv
curl -X POST -H "Authorization: Bearer $KEY" http://host:5000/api/accounts/mindfulrecipes/pins/create-run
curl -H "Authorization: Bearer $KEY" http://host:5000/api/accounts/mindfulrecipes/pins/create-status
import time while True: status = requests.get(f"{BASE}/accounts/mindfulrecipes/pins/create-status", headers=HEADERS).json() print(f"{status['status']}: {status['created']}/{status['target']}") if status["status"] in ("completed", "failed", "idle"): break time.sleep(5)

**cURL示例：**
```bash
curl -H "Authorization: Bearer $KEY" -F "csv=@pins.csv" http://host:5000/api/accounts/mindfulrecipes/pins/upload-csv
curl -X POST -H "Authorization: Bearer $KEY" http://host:5000/api/accounts/mindfulrecipes/pins/create-run
curl -H "Authorization: Bearer $KEY" http://host:5000/api/accounts/mindfulrecipes/pins/create-status

Save Queue

保存队列

MethodEndpointDescription
GET
/accounts/<username>/save-queue
List save queue items with counts.
DELETE
/accounts/<username>/save-queue/<index>
Remove item at index.
POST
/accounts/<username>/save-queue/upload
Upload save queue file (.csv or .txt).
POST
/accounts/<username>/save-queue/clear-done
Remove all completed/failed items from queue.
Python:
python
with open("saves.csv", "rb") as f:
    resp = requests.post(f"{BASE}/accounts/mindfulrecipes/save-queue/upload",
        headers=HEADERS, files={"file": f})
MethodEndpointDescription
GET
/accounts/<username>/save-queue
列出保存队列项及统计数量。
DELETE
/accounts/<username>/save-queue/<index>
删除队列中指定索引的项。
POST
/accounts/<username>/save-queue/upload
上传保存队列文件（.csv或.txt格式）。
POST
/accounts/<username>/save-queue/clear-done
从队列中移除所有已完成/失败的项。
Python示例：
python
with open("saves.csv", "rb") as f:
    resp = requests.post(f"{BASE}/accounts/mindfulrecipes/save-queue/upload",
        headers=HEADERS, files={"file": f})

{"success": true, "added": 50, "total": 50}

{"success": true, "added": 50, "total": 50}

queue = requests.get(f"{BASE}/accounts/mindfulrecipes/save-queue", headers=HEADERS).json()
queue = requests.get(f"{BASE}/accounts/mindfulrecipes/save-queue", headers=HEADERS).json()

{"items": [...], "counts": {"total": 50, "pending": 48, "saved": 2, "failed": 0}}

{"items": [...], "counts": {"total": 50, "pending": 48, "saved": 2, "failed": 0}}


---

---

Bulk Import (Files)

批量导入（文件）

MethodEndpointDescription
POST
/import/cookies
Upload ZIP of cookies/fingerprints. Structure: 
username/cookies.json
.
POST
/import/pins
Upload pin CSVs. Files named 
username_pins.csv
or ZIP of them.
POST
/import/save-queue
Upload save queue files. Named 
username_saves.csv
or 
username_saves.txt
, or ZIP.
POST
/import/boards
Upload board CSVs. Files named 
username_boards.csv
or ZIP of them.
Python — import cookies ZIP:
python
with open("cookies.zip", "rb") as f:
    resp = requests.post(f"{BASE}/import/cookies", headers=HEADERS, files={"zip": f})
MethodEndpointDescription
POST
/import/cookies
上传包含Cookie和指纹的ZIP文件。结构：
username/cookies.json
。
POST
/import/pins
上传Pin CSV文件。文件名格式为
username_pins.csv
或包含此类文件的ZIP包。
POST
/import/save-queue
上传保存队列文件。文件名格式为
username_saves.csv
或
username_saves.txt
，或包含此类文件的ZIP包。
POST
/import/boards
上传看板CSV文件。文件名格式为
username_boards.csv
或包含此类文件的ZIP包。
Python示例——导入Cookie ZIP包：
python
with open("cookies.zip", "rb") as f:
    resp = requests.post(f"{BASE}/import/cookies", headers=HEADERS, files={"zip": f})

{"success": true, "updated_count": 5, "skipped_count": 0, "error_count": 0,

{"success": true, "updated_count": 5, "skipped_count": 0, "error_count": 0,

"updated": [{"username": "user1", "cookies": true, "fingerprint": true}, ...]}

"updated": [{"username": "user1", "cookies": true, "fingerprint": true}, ...]}


**cURL:**
```bash
curl -X POST -H "Authorization: Bearer $KEY" -F "zip=@cookies.zip" http://host:5000/api/import/cookies
curl -X POST -H "Authorization: Bearer $KEY" -F "zip=@pins.zip" http://host:5000/api/import/pins

**cURL示例：**
```bash
curl -X POST -H "Authorization: Bearer $KEY" -F "zip=@cookies.zip" http://host:5000/api/import/cookies
curl -X POST -H "Authorization: Bearer $KEY" -F "zip=@pins.zip" http://host:5000/api/import/pins

Proxy Management

代理管理

IPRoyal Configuration

IPRoyal配置

MethodEndpointDescription
GET
/proxy/iproyal-config
Get IPRoyal settings (password masked).
POST
/proxy/iproyal-config
Save IPRoyal settings.
POST /proxy/iproyal-config body:
json
{
  "username": "ipr_user",
  "password": "ipr_pass",
  "host": "geo.iproyal.com",
  "port": "12321",
  "lifetime": "24h",
  "high_end": "0",
  "skip_static": "0"
}
MethodEndpointDescription
GET
/proxy/iproyal-config
获取IPRoyal设置（密码已掩码）。
POST
/proxy/iproyal-config
保存IPRoyal设置。
POST /proxy/iproyal-config 请求体：
json
{
  "username": "ipr_user",
  "password": "ipr_pass",
  "host": "geo.iproyal.com",
  "port": "12321",
  "lifetime": "24h",
  "high_end": "0",
  "skip_static": "0"
}

City Pool

城市池

MethodEndpointDescription
GET
/proxy/city-pool
Get city pool + location usage counts.
POST
/proxy/city-pool
Update city pool. Body: 
{"pool": [{"city": "chicago", "state": "illinois", "country": "us"}]}
MethodEndpointDescription
GET
/proxy/city-pool
获取城市池及位置使用统计。
POST
/proxy/city-pool
更新城市池。请求体：
{"pool": [{"city": "chicago", "state": "illinois", "country": "us"}]}

Proxy Operations

代理操作

MethodEndpointDescription
POST
/proxy/generate
Generate IPRoyal proxy for account. Body: 
{"username": "...", "assign": true}
POST
/proxy/bulk-assign
Assign IPRoyal proxies to all accounts. Body: 
{"overwrite": false}
POST
/proxy/assign-cities
Assign cities to accounts without one.
POST
/proxy/test
Test a proxy connection. Body: 
{"proxy": "http://..."}
(omit to test IPRoyal config).
Python:
python
result = requests.post(f"{BASE}/proxy/test", headers=HEADERS,
    json={"proxy": "http://user:pass@host:port"}).json()
MethodEndpointDescription
POST
/proxy/generate
为账户生成IPRoyal代理。请求体：
{"username": "...", "assign": true}
POST
/proxy/bulk-assign
为所有账户分配IPRoyal代理。请求体：
{"overwrite": false}
POST
/proxy/assign-cities
为未分配城市的账户分配城市。
POST
/proxy/test
测试代理连接。请求体：
{"proxy": "http://..."}
（省略则测试IPRoyal配置）。
Python示例：
python
result = requests.post(f"{BASE}/proxy/test", headers=HEADERS,
    json={"proxy": "http://user:pass@host:port"}).json()

{"ok": true, "ip": "1.2.3.4", "response_time": 1.23}

{"ok": true, "ip": "1.2.3.4", "response_time": 1.23}

requests.post(f"{BASE}/proxy/bulk-assign", headers=HEADERS, json={"overwrite": False})
requests.post(f"{BASE}/proxy/bulk-assign", headers=HEADERS, json={"overwrite": False})

{"ok": true, "assigned": 10, "skipped": 3, "total": 13}

{"ok": true, "assigned": 10, "skipped": 3, "total": 13}


**cURL:**
```bash
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"proxy":"http://user:pass@host:port"}' http://host:5000/api/proxy/test

**cURL示例：**
```bash
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"proxy":"http://user:pass@host:port"}' http://host:5000/api/proxy/test

Categories

分类

MethodEndpointDescription
GET
/categories
List all categories (flat).
GET
/categories/tree
Get categories as nested tree.
POST
/categories
Create category. Body: 
{"name": "...", "parent_id": null}
PUT
/categories/<id>
Rename/move category. Body: 
{"name": "...", "parent_id": 5}
DELETE
/categories/<id>
Delete category.
Python:
python
resp = requests.post(f"{BASE}/categories", headers=HEADERS,
    json={"name": "Food", "parent_id": None})
MethodEndpointDescription
GET
/categories
列出所有分类（扁平结构）。
GET
/categories/tree
获取分类的嵌套树形结构。
POST
/categories
创建分类。请求体：
{"name": "...", "parent_id": null}
PUT
/categories/<id>
重命名/移动分类。请求体：
{"name": "...", "parent_id": 5}
DELETE
/categories/<id>
删除分类。
Python示例：
python
resp = requests.post(f"{BASE}/categories", headers=HEADERS,
    json={"name": "Food", "parent_id": None})

{"success": true, "category": {"id": 1, "name": "Food", "parent_id": null, "path": "Food"}}

{"success": true, "category": {"id": 1, "name": "Food", "parent_id": null, "path": "Food"}}


---

---

Dashboard & Activity

仪表盘与活动

MethodEndpointDescription
GET
/dashboard/stats
Dashboard overview: total accounts, sessions, saves, creates, pending pins.
GET
/activity/recent
Recent automation runs. Query: 
?limit=50
(max 200).
GET
/accounts/active-tasks
Currently running tasks per account.
Python:
python
stats = requests.get(f"{BASE}/dashboard/stats", headers=HEADERS).json()
MethodEndpointDescription
GET
/dashboard/stats
仪表盘概览：账户总数、会话数、保存数、创建数、待处理Pin数。
GET
/activity/recent
最近的自动化任务运行记录。查询参数：
?limit=50
（最大值200）。
GET
/accounts/active-tasks
每个账户当前运行的任务。
Python示例：
python
stats = requests.get(f"{BASE}/dashboard/stats", headers=HEADERS).json()

{"total_accounts": 13, "connected_accounts": 3, "total_sessions": 61,

{"total_accounts": 13, "connected_accounts": 3, "total_sessions": 61,

"total_saved": 758, "total_created": 0, "total_pending_pins": 0, ...}

"total_saved": 758, "total_created": 0, "total_pending_pins": 0, ...}

recent = requests.get(f"{BASE}/activity/recent", headers=HEADERS, params={"limit": 10}).json()
recent = requests.get(f"{BASE}/activity/recent", headers=HEADERS, params={"limit": 10}).json()

{"runs": [{"username": "mindfulrecipes", "run_type": "save", "pins_saved": 8, ...}, ...]}

{"runs": [{"username": "mindfulrecipes", "run_type": "save", "pins_saved": 8, ...}, ...]}


**cURL:**
```bash
curl -H "Authorization: Bearer $KEY" http://host:5000/api/dashboard/stats
curl -H "Authorization: Bearer $KEY" "http://host:5000/api/activity/recent?limit=10"

**cURL示例：**
```bash
curl -H "Authorization: Bearer $KEY" http://host:5000/api/dashboard/stats
curl -H "Authorization: Bearer $KEY" "http://host:5000/api/activity/recent?limit=10"

Analytics

分析

Profile Analytics

个人资料分析

MethodEndpointDescription
POST
/analytics/check
Start async analytics job (fetches Pinterest profile data for all accounts).
GET
/analytics/status?job_id=<id>
Poll job status. Returns results when complete.
Python:
python
job = requests.post(f"{BASE}/analytics/check", headers=HEADERS).json()
MethodEndpointDescription
POST
/analytics/check
启动异步分析任务（获取所有账户的Pinterest个人资料数据）。
GET
/analytics/status?job_id=<id>
轮询任务状态。任务完成后返回结果。
Python示例：
python
job = requests.post(f"{BASE}/analytics/check", headers=HEADERS).json()

{"job_id": "a1b2c3d4", "checker_username": "mindfulrecipes", "total": 13}

{"job_id": "a1b2c3d4", "checker_username": "mindfulrecipes", "total": 13}

import time while True: status = requests.get(f"{BASE}/analytics/status", headers=HEADERS, params={"job_id": job["job_id"]}).json() if status["status"] == "complete": for r in status["results"]: print(f"{r['username']}: {r['follower_count']} followers, {r['pin_count']} pins") break elif status["status"] == "error": print(f"Error: {status['error']}") break time.sleep(3)
undefined
import time while True: status = requests.get(f"{BASE}/analytics/status", headers=HEADERS, params={"job_id": job["job_id"]}).json() if status["status"] == "complete": for r in status["results"]: print(f"{r['username']}: {r['follower_count']} followers, {r['pin_count']} pins") break elif status["status"] == "error": print(f"Error: {status['error']}") break time.sleep(3)
undefined

Analytics Dashboard

分析仪表盘

MethodEndpointDescription
GET
/analytics/dashboard
System overview, daily trends, account performance, hourly distribution. Query: 
?days=30
(max 90).
Response:
json
{
  "overview": {"today": {"saves": 15}, "yesterday": {"saves": 22}, "avg_7d": {"saves": 18}},
  "trends": [{"date": "2025-04-15", "saves": 22, "creates": 0, "sessions": 3}, ...],
  "performance": [{"username": "mindfulrecipes", "saves": 357, "sessions": 61}, ...],
  "hourly": [{"hour": 8, "saves": 5}, {"hour": 9, "saves": 8}, ...]
}
MethodEndpointDescription
GET
/analytics/dashboard
系统概览、每日趋势、账户表现、小时分布。查询参数：
?days=30
（最大值90）。
响应示例：
json
{
  "overview": {"today": {"saves": 15}, "yesterday": {"saves": 22}, "avg_7d": {"saves": 18}},
  "trends": [{"date": "2025-04-15", "saves": 22, "creates": 0, "sessions": 3}, ...],
  "performance": [{"username": "mindfulrecipes", "saves": 357, "sessions": 61}, ...],
  "hourly": [{"hour": 8, "saves": 5}, {"hour": 9, "saves": 8}, ...]
}

Health

健康状态

MethodEndpointDescription
GET
/health/accounts
Health status for all accounts (healthy/warning/critical/inactive) with 24h stats.
Python:
python
health = requests.get(f"{BASE}/health/accounts", headers=HEADERS).json()
MethodEndpointDescription
GET
/health/accounts
所有账户的健康状态（健康/警告/严重/未激活）及24小时统计数据。
Python示例：
python
health = requests.get(f"{BASE}/health/accounts", headers=HEADERS).json()

{"summary": {"total": 13, "healthy": 2, "warning": 1, "critical": 0, "inactive": 10},

{"summary": {"total": 13, "healthy": 2, "warning": 1, "critical": 0, "inactive": 10},

"accounts": [{"username": "mindfulrecipes", "health_status": "healthy",

"accounts": [{"username": "mindfulrecipes", "health_status": "healthy",

"total_sessions_24h": 3, "total_saves_24h": 15, "failure_rate": 0, ...}, ...]}

"total_sessions_24h": 3, "total_saves_24h": 15, "failure_rate": 0, ...}, ...]}


**cURL:**
```bash
curl -H "Authorization: Bearer $KEY" http://host:5000/api/health/accounts

**cURL示例：**
```bash
curl -H "Authorization: Bearer $KEY" http://host:5000/api/health/accounts

Logs

日志

MethodEndpointDescription
GET
/logs/accounts
List accounts that have log files.
GET
/logs/download-all
Download all logs as ZIP.
GET
/logs/download/<username>
Download logs for single account as ZIP.
cURL:
bash
curl -H "Authorization: Bearer $KEY" -o all_logs.zip http://host:5000/api/logs/download-all
curl -H "Authorization: Bearer $KEY" -o user_logs.zip http://host:5000/api/logs/download/mindfulrecipes
MethodEndpointDescription
GET
/logs/accounts
列出拥有日志文件的账户。
GET
/logs/download-all
下载所有日志为ZIP包。
GET
/logs/download/<username>
下载单个账户的日志为ZIP包。
cURL示例：
bash
curl -H "Authorization: Bearer $KEY" -o all_logs.zip http://host:5000/api/logs/download-all
curl -H "Authorization: Bearer $KEY" -o user_logs.zip http://host:5000/api/logs/download/mindfulrecipes

Simulator

模拟器

MethodEndpointDescription
GET
/simulator/status
Get simulation status.
POST
/simulator/start
Start simulation.
POST
/simulator/stop
Stop running simulation.
GET
/simulator/logs?since=<timestamp>
Get simulation logs.
POST
/simulator/cleanup-logs
Clean up simulation log files.
POST /simulator/start body:
json
{
  "accounts": ["user1", "user2"],
  "days": 3,
  "fast": false,
  "max_workers": 6,
  "stages": [
    {"week": 1, "days": 3},
    {"week": 2, "days": 4}
  ]
}
MethodEndpointDescription
GET
/simulator/status
获取模拟状态。
POST
/simulator/start
启动模拟。
POST
/simulator/stop
停止正在运行的模拟。
GET
/simulator/logs?since=<timestamp>
获取模拟日志。
POST
/simulator/cleanup-logs
清理模拟日志文件。
POST /simulator/start 请求体：
json
{
  "accounts": ["user1", "user2"],
  "days": 3,
  "fast": false,
  "max_workers": 6,
  "stages": [
    {"week": 1, "days": 3},
    {"week": 2, "days": 4}
  ]
}

Backup & Restore

备份与恢复

MethodEndpointDescription
GET
/backup/settings
Get S3 backup settings.
POST
/backup/settings
Save S3 backup settings.
POST
/backup/test-connection
Test S3 connection.
POST
/backup/create
Create a new backup.
GET
/backup/list
List available backups.
GET
/backup/status
Get current backup/restore status.
POST
/backup/restore
Restore from backup. Body: 
{"key": "backup_key"}
DELETE
/backup/<key>
Delete a backup.
Python:
python
requests.post(f"{BASE}/backup/create", headers=HEADERS)
MethodEndpointDescription
GET
/backup/settings
获取S3备份设置。
POST
/backup/settings
保存S3备份设置。
POST
/backup/test-connection
测试S3连接。
POST
/backup/create
创建新备份。
GET
/backup/list
列出可用备份。
GET
/backup/status
获取当前备份/恢复状态。
POST
/backup/restore
从备份恢复。请求体：
{"key": "backup_key"}
DELETE
/backup/<key>
删除备份。
Python示例：
python
requests.post(f"{BASE}/backup/create", headers=HEADERS)

{"ok": true, "message": "Backup started"}

{"ok": true, "message": "Backup started"}

import time while True: status = requests.get(f"{BASE}/backup/status", headers=HEADERS).json() if not status.get("running"): break time.sleep(10)
backups = requests.get(f"{BASE}/backup/list", headers=HEADERS).json()
import time while True: status = requests.get(f"{BASE}/backup/status", headers=HEADERS).json() if not status.get("running"): break time.sleep(10)
backups = requests.get(f"{BASE}/backup/list", headers=HEADERS).json()

{"backups": [{"key": "backups/20250416_020000.tar.gz", "size": 1234567, ...}]}

{"backups": [{"key": "backups/20250416_020000.tar.gz", "size": 1234567, ...}]}


**cURL:**
```bash
curl -X POST -H "Authorization: Bearer $KEY" http://host:5000/api/backup/create
curl -H "Authorization: Bearer $KEY" http://host:5000/api/backup/list

**cURL示例：**
```bash
curl -X POST -H "Authorization: Bearer $KEY" http://host:5000/api/backup/create
curl -H "Authorization: Bearer $KEY" http://host:5000/api/backup/list

Settings

设置

General

常规设置

MethodEndpointDescription
GET
/settings
Get current settings (username, concurrency, version).
POST
/settings/password
Change password. Body: 
{"current_password": "...", "new_password": "..."}
POST
/settings/username
Change login username. Body: 
{"new_username": "..."}
POST
/settings/concurrency
Set max concurrent automations (1-20). Body: 
{"max_concurrent": 6}
MethodEndpointDescription
GET
/settings
获取当前设置（用户名、并发数、版本）。
POST
/settings/password
修改密码。请求体：
{"current_password": "...", "new_password": "..."}
POST
/settings/username
修改登录用户名。请求体：
{"new_username": "..."}
POST
/settings/concurrency
设置最大并发自动化任务数（1-20）。请求体：
{"max_concurrent": 6}

Security

安全设置

MethodEndpointDescription
POST
/settings/secret-key/regenerate
Regenerate Flask secret key (invalidates all sessions).
GET
/settings/api-key
Get API key info (exists, prefix).
POST
/settings/api-key/regenerate
Generate new API key. Returns the raw key once.
POST
/settings/api-key/revoke
Revoke API key.
Python:
python
result = requests.post(f"{BASE}/settings/api-key/regenerate", headers=HEADERS).json()
MethodEndpointDescription
POST
/settings/secret-key/regenerate
重新生成Flask密钥（会使所有会话失效）。
GET
/settings/api-key
获取API密钥信息（是否存在、前缀）。
POST
/settings/api-key/regenerate
生成新的API密钥。仅返回一次原始密钥。
POST
/settings/api-key/revoke
吊销API密钥。
Python示例：
python
result = requests.post(f"{BASE}/settings/api-key/regenerate", headers=HEADERS).json()

{"ok": true, "api_key": "18ef47f3a...", "message": "Copy it now — it will not be shown again."}

{"ok": true, "api_key": "18ef47f3a...", "message": "Copy it now — it will not be shown again."}

info = requests.get(f"{BASE}/settings/api-key", headers=HEADERS).json()
info = requests.get(f"{BASE}/settings/api-key", headers=HEADERS).json()

{"exists": true, "prefix": "18ef47f3", "masked": "18ef47f3...************************"}

{"exists": true, "prefix": "18ef47f3", "masked": "18ef47f3...************************"}

undefined
undefined

Smart Saves Schedule

智能保存调度

MethodEndpointDescription
GET
/settings/smart-saves-schedule
Get smart saves schedule (week thresholds + min/max saves).
POST
/settings/smart-saves-schedule
Update schedule.
POST
/settings/smart-saves-schedule/reset
Reset to defaults.
POST /settings/smart-saves-schedule body:
json
{
  "schedule": [
    {"day_threshold": 7, "min_saves": 3, "max_saves": 8},
    {"day_threshold": 14, "min_saves": 5, "max_saves": 15},
    {"day_threshold": 999999, "min_saves": 10, "max_saves": 25}
  ]
}
MethodEndpointDescription
GET
/settings/smart-saves-schedule
获取智能保存调度（周阈值及最小/最大保存数）。
POST
/settings/smart-saves-schedule
更新调度。
POST
/settings/smart-saves-schedule/reset
重置为默认设置。
POST /settings/smart-saves-schedule 请求体：
json
{
  "schedule": [
    {"day_threshold": 7, "min_saves": 3, "max_saves": 8},
    {"day_threshold": 14, "min_saves": 5, "max_saves": 15},
    {"day_threshold": 999999, "min_saves": 10, "max_saves": 25}
  ]
}

Database & Reset

数据库与重置

MethodEndpointDescription
GET
/settings/db-stats
Get row counts for runs, daily_activity, automation_status, active_jobs, csv_pins.
POST
/settings/reset/<target>
Reset history. Target: 
run-history
, 
daily-activity
, 
automation-status
, 
active-jobs
, 
all-history
. Body: 
{"confirm": true}
POST
/settings/reset/csv-pins
Reset all pin CSV statuses to pending. Body: 
{"confirm": true}
MethodEndpointDescription
GET
/settings/db-stats
获取runs、daily_activity、automation_status、active_jobs、csv_pins的行数统计。
POST
/settings/reset/<target>
重置历史数据。目标值：
run-history
、
daily-activity
、
automation-status
、
active-jobs
、
all-history
。请求体：
{"confirm": true}
POST
/settings/reset/csv-pins
将所有Pin CSV状态重置为待处理。请求体：
{"confirm": true}

Error Responses

错误响应

All errors return JSON with an 
error
field:
json
{"error": "Account not found"}
Common HTTP status codes:
  • 400
    — Bad request / validation error
  • 401
    — Not authenticated
  • 403
    — Forbidden (wrong password)
  • 404
    — Resource not found
  • 409
    — Conflict (already exists, already running)
  • 500
    — Server error
  • 502
    — Proxy error (proxy test failures)
所有错误返回包含
error
字段的JSON：
json
{"error": "Account not found"}
常见HTTP状态码：
  • 400
    — 错误请求/验证错误
  • 401
    — 未认证
  • 403
    — 禁止访问（密码错误）
  • 404
    — 资源未找到
  • 409
    — 冲突（已存在、已在运行）
  • 500
    — 服务器错误
  • 502
    — 代理错误（代理测试失败）