{
  "openapi": "3.1.0",
  "info": {
    "title": "天工内容 API",
    "version": "1.0.0",
    "description": "内容、收藏、定时收集与异步发布。写操作默认保存草稿，202 需要查询任务状态。"
  },
  "servers": [
    {
      "url": "https://spark.tlec.top"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "ContentInput": {
        "type": "object",
        "required": [
          "section",
          "slug",
          "versions"
        ],
        "properties": {
          "section": {
            "enum": [
              "plays",
              "blog",
              "news"
            ]
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          },
          "mode": {
            "enum": [
              "draft",
              "publish"
            ],
            "default": "draft"
          },
          "expectedRevision": {
            "type": "integer"
          },
          "versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": false,
            "properties": {
              "zh": {
                "type": "object",
                "required": [
                  "title",
                  "body"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "body": {
                    "type": "string",
                    "maxLength": 100000
                  },
                  "description": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string",
                    "format": "uri"
                  },
                  "category": {
                    "type": "string"
                  },
                  "tools": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "models": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "tested": {
                    "type": "boolean"
                  },
                  "cover": {
                    "type": "string",
                    "description": "原图公网 HTTP(S) URL 或本站 /covers/ 路径；后台验证、压缩并缓存。"
                  },
                  "coverAlt": {
                    "type": "string",
                    "description": "封面替代文本"
                  },
                  "coverSource": {
                    "type": "string",
                    "description": "原始图片出处"
                  },
                  "coverCredit": {
                    "type": "string",
                    "description": "图片来源署名"
                  }
                }
              },
              "en": {
                "type": "object",
                "required": [
                  "title",
                  "body"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "body": {
                    "type": "string",
                    "maxLength": 100000
                  },
                  "description": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string",
                    "format": "uri"
                  },
                  "category": {
                    "type": "string"
                  },
                  "tools": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "models": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "tested": {
                    "type": "boolean"
                  },
                  "cover": {
                    "type": "string",
                    "description": "原图公网 HTTP(S) URL 或本站 /covers/ 路径；后台验证、压缩并缓存。"
                  },
                  "coverAlt": {
                    "type": "string",
                    "description": "封面替代文本"
                  },
                  "coverSource": {
                    "type": "string",
                    "description": "原始图片出处"
                  },
                  "coverCredit": {
                    "type": "string",
                    "description": "图片来源署名"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/status": {
      "get": {
        "summary": "配置、队列与条目统计",
        "operationId": "get__api_v1_status",
        "responses": {
          "200": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          }
        }
      }
    },
    "/api/v1/content": {
      "get": {
        "summary": "分页列出内容",
        "operationId": "get__api_v1_content",
        "responses": {
          "200": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          }
        },
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "section",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer"
            }
          }
        ]
      },
      "post": {
        "summary": "创建草稿或发布内容",
        "operationId": "post__api_v1_content",
        "responses": {
          "201": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          },
          "202": {
            "description": "异步任务已排队；查询返回的 job.id 直到 succeeded 或 failed"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContentInput"
              }
            }
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          }
        ]
      }
    },
    "/api/v1/content/{id}": {
      "get": {
        "summary": "读取正文与 revision",
        "operationId": "get__api_v1_content_id",
        "responses": {
          "200": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          }
        ]
      },
      "put": {
        "summary": "替换完整内容，必须提供 expectedRevision",
        "operationId": "put__api_v1_content_id",
        "responses": {
          "200": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          },
          "202": {
            "description": "异步任务已排队；查询返回的 job.id 直到 succeeded 或 failed"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ContentInput"
                  },
                  {
                    "type": "object",
                    "required": [
                      "expectedRevision"
                    ],
                    "properties": {
                      "expectedRevision": {
                        "type": "integer",
                        "minimum": 1
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          }
        ]
      }
    },
    "/api/v1/content/{id}/publish": {
      "post": {
        "summary": "发布构建",
        "operationId": "post__api_v1_content_id_publish",
        "responses": {
          "202": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          }
        ]
      }
    },
    "/api/v1/content/{id}/enrich": {
      "post": {
        "summary": "把原始内容整理为双语草稿",
        "operationId": "post__api_v1_content_id_enrich",
        "responses": {
          "202": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          }
        ]
      }
    },
    "/api/v1/submissions": {
      "post": {
        "summary": "保存原始链接/正文；有模型和足够正文时自动整理",
        "operationId": "post__api_v1_submissions",
        "responses": {
          "201": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          },
          "202": {
            "description": "异步任务已排队；查询返回的 job.id 直到 succeeded 或 failed"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "note": {
                    "type": "string"
                  },
                  "section": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          }
        ]
      }
    },
    "/api/v1/collect": {
      "post": {
        "summary": "立即收集来源，生成候选与待审草稿",
        "operationId": "post__api_v1_collect",
        "responses": {
          "202": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          }
        ]
      }
    },
    "/api/v1/jobs": {
      "get": {
        "summary": "最近任务列表",
        "operationId": "get__api_v1_jobs",
        "responses": {
          "200": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          }
        }
      }
    },
    "/api/v1/jobs/{id}": {
      "get": {
        "summary": "任务详情、结果与错误",
        "operationId": "get__api_v1_jobs_id",
        "responses": {
          "200": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "同一操作重试沿用同一个键"
          }
        ]
      }
    },
    "/api/v1/audit": {
      "get": {
        "summary": "最近操作记录",
        "operationId": "get__api_v1_audit",
        "responses": {
          "200": {
            "description": "成功；202 表示已排队，需轮询任务"
          },
          "401": {
            "description": "令牌无效"
          },
          "409": {
            "description": "重复、版本冲突或正在处理"
          }
        }
      }
    },
    "/api/v1/covers/backfill": {
      "post": {
        "operationId": "backfillCovers",
        "summary": "为现有内容补齐封面并重建已发布页面；不发布草稿",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "refresh": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "补图任务已排队，查询 job.id 查看进度和上线结果"
          }
        }
      }
    },
    "/api/v1/covers/{filename}": {
      "get": {
        "operationId": "previewCover",
        "summary": "认证后预览尚未发布的封面",
        "parameters": [
          {
            "in": "path",
            "name": "filename",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}\\.(webp|png|jpg|gif|avif|svg)$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "封面图片",
            "content": {
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "需要内容令牌"
          }
        }
      }
    },
    "/api/v1/traffic": {
      "get": {
        "operationId": "getTraffic",
        "summary": "访问与爬虫统计（从日志启用后开始，Asia/Taipei）",
        "parameters": [
          {
            "in": "query",
            "name": "days",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                7,
                30
              ],
              "default": 7
            }
          },
          {
            "in": "query",
            "name": "kind",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "bots",
                "verified"
              ],
              "default": "all"
            }
          },
          {
            "in": "query",
            "name": "includeTests",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "今日指标、按日统计、爬虫列表、最近 100 条请求、页面排行和核验状态；来源 IP 脱敏。"
          },
          "401": {
            "description": "需要内容管理令牌"
          }
        }
      }
    }
  }
}