{ "openapi": "3.1.0", "info": { "title": "Marketide Agent API", "version": "0.1.0", "description": "个人内容与日历API。Webhook和邮件调度尚未实现。" }, "servers": [ { "url": "https://marketide.kokoship.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "读取当前用户和时区", "responses": { "200": { "description": "成功，JSON 响应" } } }, "patch": { "operationId": "setTimezone", "summary": "设置用户显示时区，不修改排期时刻", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "timezone" ], "properties": { "timezone": { "type": "string", "example": "Asia/Shanghai" } } } } } }, "responses": { "200": { "description": "成功，JSON 响应" } } } }, "/contents": { "get": { "operationId": "listContents", "summary": "查询内容，时间范围只筛选具体排期", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "成功，JSON 响应" } } }, "post": { "operationId": "createContents", "summary": "创建一篇或原子批量创建最多50篇草稿", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 }, "description": "同一逻辑请求重试时保持相同键、内容和批次顺序" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContentInput" }, { "type": "object", "required": [ "contents" ], "properties": { "contents": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/ContentInput" } } } } ] } } } }, "responses": { "201": { "description": "成功，JSON 响应" } } } }, "/contents/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getContent", "responses": { "200": { "description": "成功，JSON 响应" } } }, "patch": { "operationId": "updateContent", "summary": "部分更新，必传version；与其他入口冲突时返回409", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version" ], "properties": { "title": { "type": "string", "maxLength": 200 }, "body": { "type": "string", "maxLength": 100000 }, "channel": { "type": "string", "enum": [ "X", "小红书", "公众号", "邮件", "其他" ], "default": "其他" }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "link": { "type": "string" }, "plannedDate": { "type": [ "string", "null" ], "format": "date" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedUrl": { "type": "string" }, "version": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "成功，JSON 响应" }, "409": { "description": "内容版本冲突" } } }, "delete": { "operationId": "deleteContent", "summary": "删除内容及其图片，不能撤销", "responses": { "200": { "description": "成功，JSON 响应" } } } }, "/contents/{id}/copy": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "copyContent", "summary": "复制正文和图片为未排期新草稿", "responses": { "201": { "description": "成功，JSON 响应" } } } }, "/assets": { "post": { "operationId": "uploadImage", "summary": "上传PNG/JPEG/GIF/WebP，每张最多10MB，每篇最多12张", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "contentId", "file" ], "properties": { "contentId": { "type": "string" }, "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "成功，JSON 响应" } } } }, "/assets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getImage", "summary": "需认证的图片文件", "responses": { "200": { "description": "图片二进制" } } }, "patch": { "operationId": "reorderImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "position" ], "properties": { "position": { "type": "integer", "minimum": 0, "maximum": 12 } } } } } }, "responses": { "200": { "description": "成功，JSON 响应" } } }, "delete": { "operationId": "deleteImage", "responses": { "200": { "description": "成功，JSON 响应" } } } }, "/contents/{id}/asset-order": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "reorderContentImages", "summary": "原子调整该内容的全部图片顺序，ids必须完整且不重复", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "maxItems": 12, "uniqueItems": true } } } } } }, "responses": { "200": { "description": "排序已更新" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "网页登录后创建个人API Key" } }, "schemas": { "ContentInput": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 200 }, "body": { "type": "string", "maxLength": 100000 }, "channel": { "type": "string", "enum": [ "X", "小红书", "公众号", "邮件", "其他" ], "default": "其他" }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "link": { "type": "string" }, "plannedDate": { "type": [ "string", "null" ], "format": "date" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedUrl": { "type": "string" } } } } } }