{
  "openapi": "3.1.0",
  "info": {
    "title": "全球 IT 论坛 API",
    "version": "1",
    "description": "Read, post and reply on 全球 IT 论坛 as a member, with the API key that member created at https://bbs.it.com/settings/api-keys/ (it starts with sbk_). Everything posted is the member's own post; the forum rules (https://bbs.it.com/rules.md) apply in full. How-to and etiquette: https://bbs.it.com/skill.md. Field-by-field reference: https://bbs.it.com/api.md. Errors are {\"error\": code, \"error_description\": text}; show error_description to the member. Paths end in a slash."
  },
  "servers": [{ "url": "https://bbs.it.com" }],
  "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer sbk_..." },
      "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "The same key in an X-API-Key header, for tools that cannot set Authorization. Never put the key in the URL." }
    },
    "parameters": {
      "TopicID": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
      "ReplyID": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
      "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The previous page's next value; absent for the first page." },
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "minLength": 8, "maxLength": 64 }, "description": "A new random string per action; resend the same one when retrying." }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "retry_after": { "type": "integer" } }
      },
      "Member": {
        "type": "object",
        "properties": { "uid": { "type": "integer" }, "username": { "type": "string" }, "url": { "type": "string" }, "avatar": { "type": "string" } }
      },
      "Forum": {
        "type": "object",
        "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "can_post": { "type": "boolean" }, "can_reply": { "type": "boolean" }, "post_interval_seconds": { "type": "integer" } }
      },
      "TopicRow": {
        "type": "object",
        "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" }, "forum": { "$ref": "#/components/schemas/Forum" }, "author": { "$ref": "#/components/schemas/Member" }, "created_at": { "type": "string", "format": "date-time" }, "last_reply_at": { "type": "string", "format": "date-time" }, "reply_count": { "type": "integer" }, "closed": { "type": "boolean" } }
      },
      "Reply": {
        "type": "object",
        "properties": { "id": { "type": "integer" }, "no": { "type": "integer", "description": "Floor number" }, "parent_no": { "type": "integer" }, "root_no": { "type": "integer" }, "author": { "$ref": "#/components/schemas/Member" }, "body_html": { "type": "string" }, "body": { "type": "string", "description": "Markdown source; only on the member's own replies" }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string" } }
      },
      "Topic": {
        "type": "object",
        "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" }, "forum": { "$ref": "#/components/schemas/Forum" }, "author": { "$ref": "#/components/schemas/Member" }, "body_html": { "type": "string" }, "body": { "type": "string" }, "reply_count": { "type": "integer" }, "can_reply": { "type": "boolean" }, "layout": { "type": "string", "enum": ["flat", "tree"] }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/Reply" } }, "floors": { "type": "array", "items": { "$ref": "#/components/schemas/Reply" } }, "next": { "type": "string" } }
      },
      "Created": {
        "type": "object",
        "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "held": { "type": "boolean", "description": "Held for review: do not resend" }, "review": { "type": "boolean" }, "message": { "type": "string" } }
      }
    },
    "responses": {
      "Error": { "description": "Refused; see error and error_description", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "paths": {
    "/api/v1/": {
      "get": {
        "operationId": "ping",
        "summary": "Connection test: the site, and whether the key was recognised",
        "responses": { "200": { "description": "signed_in is true with a valid key", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "signed_in": { "type": "boolean" }, "username": { "type": "string" } } } } } } }
      }
    },
    "/api/v1/site/": {
      "get": {
        "operationId": "getSite",
        "summary": "Boards and limits",
        "responses": { "200": { "description": "forums[] (pick one whose can_post is true) and limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "forums": { "type": "array", "items": { "$ref": "#/components/schemas/Forum" } }, "limits": { "type": "object" } } } } } } }
      }
    },
    "/api/v1/me/": {
      "get": {
        "operationId": "getMe",
        "summary": "The member the key belongs to",
        "responses": { "200": { "description": "can_speak false means muted", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/v1/topics/": {
      "get": {
        "operationId": "listTopics",
        "summary": "Topic list",
        "parameters": [
          { "name": "forum", "in": "query", "schema": { "type": "string" }, "description": "Board slug; omit for the front page" },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["post", "comment"] } },
          { "name": "author", "in": "query", "schema": { "type": "integer" }, "description": "Member uid" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 50 } },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": { "200": { "description": "Page of topics", "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "$ref": "#/components/schemas/TopicRow" } }, "next": { "type": "string" } } } } } } }
      },
      "post": {
        "operationId": "createTopic",
        "summary": "Post a new topic",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["forum", "title", "body"], "properties": { "forum": { "type": "string", "description": "Board slug" }, "title": { "type": "string" }, "body": { "type": "string", "description": "Markdown" } } } } } },
        "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Created" } } } }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/v1/topics/{id}/": {
      "get": {
        "operationId": "getTopic",
        "summary": "A topic and a page of its replies",
        "parameters": [
          { "$ref": "#/components/parameters/TopicID" },
          { "name": "layout", "in": "query", "schema": { "type": "string", "enum": ["flat", "tree"] }, "description": "flat: every reply in floor order (recommended)" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100 } },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": { "200": { "description": "The topic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topic" } } } }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/v1/topics/{id}/replies/": {
      "post": {
        "operationId": "createReply",
        "summary": "Reply to a topic. To answer one floor, start the body with \"@username #floor \"",
        "parameters": [{ "$ref": "#/components/parameters/TopicID" }, { "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["body"], "properties": { "body": { "type": "string", "description": "Markdown" } } } } } },
        "responses": { "201": { "description": "Created; also no, root_no and reply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Created" } } } }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/v1/topics/{id}/edit/": {
      "post": {
        "operationId": "editTopic",
        "summary": "Edit the member's own topic",
        "parameters": [{ "$ref": "#/components/parameters/TopicID" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Saved" }, "403": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/v1/replies/{id}/edit/": {
      "post": {
        "operationId": "editReply",
        "summary": "Edit the member's own reply",
        "parameters": [{ "$ref": "#/components/parameters/ReplyID" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Saved" }, "403": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/v1/search/": {
      "get": {
        "operationId": "search",
        "summary": "Search topics, replies or members",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "field", "in": "query", "schema": { "type": "string", "enum": ["title", "body", "reply", "user"] } },
          { "name": "forum", "in": "query", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": { "200": { "description": "topics (or users for field=user) and next", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/notifications/": {
      "get": {
        "operationId": "listNotifications",
        "summary": "The member's notifications (replies, mentions...)",
        "parameters": [{ "$ref": "#/components/parameters/Cursor" }],
        "responses": { "200": { "description": "notifications[] and unread", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/me/posting-notice/": {
      "get": {
        "operationId": "getPostingNotice",
        "summary": "First-post notice: required true means start, wait, then acknowledge before the first post",
        "responses": { "200": { "description": "required, notice", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/me/posting-notice/start/": {
      "post": {
        "operationId": "startPostingNotice",
        "summary": "Start the notice's clock; returns remaining seconds",
        "responses": { "200": { "description": "required, remaining", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/me/posting-notice/acknowledge/": {
      "post": {
        "operationId": "acknowledgePostingNotice",
        "summary": "Acknowledge the notice once remaining has passed",
        "responses": { "200": { "description": "required false" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    }
  }
}
