{
  "openapi": "3.1.0",
  "info": {
    "title": "NexusMC Bot Events API",
    "version": "1.0.0",
    "description": "机器人事件与回复 API。机器人是独立 user 主体；请求必须使用绑定机器人自身的 Bot PAT，或使用经审核的机器人 OAuth 应用签发、且已获得机器人权限 grant 的 OAuth access token。两种凭据均以 bot user 为主体，Cookie、人工令牌与普通 OAuth 应用令牌会被拒绝。"
  },
  "servers": [
    {
      "url": "http://127.0.0.1:4520"
    }
  ],
  "components": {
    "securitySchemes": {
      "botBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Bot PAT or OAuth access token",
        "description": "仅接受绑定机器人自身的 nxm_ Bot PAT，或经审核机器人 OAuth 应用 client_credentials 签发的 nxo_ access token；OAuth 应用审核与 bot 权限 grant 均必须通过，令牌主体始终是 bot user。禁止 Cookie、人工 PAT、普通 OAuth 应用令牌和 query token。"
      }
    }
  },
  "paths": {
    "/v1/bots/me/events": {
      "get": {
        "operationId": "listBotEvents",
        "summary": "读取机器人事件",
        "security": [
          {
            "botBearer": []
          }
        ],
        "x-required-scope": "bot:events:read",
        "parameters": [
          {
            "name": "after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,19}$",
              "maxLength": 19
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^(?:[1-9]|[1-4][0-9]|50)$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "event_id": {
                            "type": "string"
                          },
                          "seq": {
                            "type": "string",
                            "pattern": "^[0-9]{1,19}$",
                            "maxLength": 19
                          },
                          "message_id": {
                            "type": "string"
                          },
                          "room_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "conversation_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "trigger_kind": {
                            "type": "string",
                            "enum": [
                              "dm",
                              "mention",
                              "slash"
                            ]
                          },
                          "command_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "command_revision": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "args": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "content": {
                            "type": "string"
                          },
                          "author_id": {
                            "type": "string"
                          },
                          "created_at": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "event_id",
                          "seq",
                          "message_id",
                          "room_id",
                          "conversation_id",
                          "trigger_kind",
                          "command_id",
                          "command_revision",
                          "args",
                          "content",
                          "author_id",
                          "created_at"
                        ],
                        "additionalProperties": false
                      },
                      "maxItems": 50
                    },
                    "next_after": {
                      "type": "string",
                      "pattern": "^[0-9]{1,19}$",
                      "maxLength": 19
                    }
                  },
                  "required": [
                    "events",
                    "next_after"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "events": [],
                  "next_after": "0"
                }
              }
            }
          },
          "401": {
            "description": "缺少、无效或已过期的机器人凭据",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "机器人凭据、OAuth 应用审核或 bot 权限 grant 不满足要求",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "机器人请求或连接数量超过限制",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "description": "使用机器人自身 Bot PAT 或经审核机器人 OAuth 应用签发的 OAuth access token，按十进制游标读取当前仍有权限查看的私信和房间指令事件，每页最多 50 条；断线后可用 next_after 补取。OAuth 应用审核和 bot 权限 grant 均必须有效；令牌主体始终是绑定的 bot user。事件保留 90 天，清理不重置序号；无新事件时 next_after 不小于请求的 after。",
        "tags": [
          "Bots"
        ],
        "x-cookie-policy": "reject",
        "x-legacy-api-path": "/api/bots/me/events"
      }
    },
    "/v1/bots/me/replies": {
      "post": {
        "operationId": "replyBotEvent",
        "summary": "回复机器人事件",
        "security": [
          {
            "botBearer": []
          }
        ],
        "x-required-scope": "bot:events:read",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_id": {
                    "type": "string",
                    "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$"
                  },
                  "action_key": {
                    "type": "string",
                    "pattern": "^[-\\w:.]{1,64}$"
                  },
                  "content": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 10000
                  }
                },
                "required": [
                  "event_id",
                  "action_key",
                  "content"
                ],
                "additionalProperties": false
              },
              "example": {
                "event_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "action_key": "reply-1",
                "content": "已收到。"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message_id": {
                      "type": "string"
                    },
                    "duplicate": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "message_id",
                    "duplicate"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "message_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                  "duplicate": false
                }
              }
            }
          },
          "401": {
            "description": "缺少、无效或已过期的机器人凭据",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "机器人凭据、OAuth 应用审核或 bot 权限 grant 不满足要求",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "机器人请求或连接数量超过限制",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "error": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、权限或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "description": "使用机器人自身 Bot PAT 或经审核机器人 OAuth 应用签发的 OAuth access token 回复当前可见且获准响应的事件；OAuth 应用审核和 bot 权限 grant 均必须有效，令牌主体始终是绑定的 bot user。同一机器人、event_id 与 action_key 以首次提交为准，即使重试的 content 不同也返回原 message_id（duplicate=true），不修改或重复发送。发送新内容须使用新的 action_key。",
        "tags": [
          "Bots"
        ],
        "x-cookie-policy": "reject",
        "x-legacy-api-path": "/api/bots/me/replies"
      }
    }
  },
  "x-websocket": {
    "path": "/v1/bots/me/events/stream",
    "authentication": "Bot PAT or OAuth access token in Authorization Bearer header only; OAuth tokens must come from a reviewed bot application with an active bot permission grant and are always bound to the bot user; no Cookie or query token",
    "messages": [
      {
        "event": "bot_events_changed"
      }
    ],
    "maxAgeSeconds": 1800,
    "perTokenConnections": 2,
    "instanceConnections": 64
  }
}
