Skip to content

docs(api): add POST /status-page/draft/create to OpenAPI specs #325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
debidong merged 1 commit into from
Aug 31, 2026
Merged

docs(api): add POST /status-page/draft/create to OpenAPI specs #325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 123 additions & 0 deletions api-reference/on-call.openapi.en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12310,6 +12310,92 @@
]
}
},
"/status-page/draft/create": {
"post": {
"operationId": "statusPageDraftCreate",
"summary": "Create status page draft",
"description": "Store a status page event draft so a human can review and publish it from the console.",
"tags": [
"On-call/Status pages"
],
"x-mint": {
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The `draft` payload is stored verbatim (up to 64 KB); the console publish form reads it back to prefill the event.\n- A draft lives for 30 days and is consumed exactly once when the event is published.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
"href": "/en/api-reference/on-call/status-pages/status-page-draft-create",
"metadata": {
"sidebarTitle": "Create status page draft"
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SuccessEnvelope"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/StatusPageDraftCreateResponse"
}
}
}
]
},
"example": {
"request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
"data": {
"draft_id": "draft_3xK9mQ2vN7pR4wT8yH1sJ5",
"created_at": 1788000000
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateStatusPageDraftRequest"
},
"example": {
"draft": {
"v": 1,
"page_id": 5750613685214,
"type": "incident",
"name": "Web Console Degraded Performance",
"message": "We are investigating degraded performance affecting the web console.",
"affected_components": [
{
"component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
"status": "degraded"
}
]
},
"source": "ai_sre:sess_01KC3H2A9ZQ8W7E6R5T4Y3U2I1"
}
}
}
}
}
},
"/enrichment/mapping/api/create": {
"post": {
"operationId": "mapping-api-write-create",
Expand Down Expand Up @@ -20940,6 +21026,24 @@
}
}
},
"CreateStatusPageDraftRequest": {
"type": "object",
"description": "Parameters for storing a status page draft. The `draft` payload is stored verbatim; only the validated fields listed below are interpreted.",
"required": [
"draft"
],
"properties": {
"draft": {
"type": "object",
"description": "Draft payload, stored verbatim, up to 64 KB serialized. Validated fields: `page_id`, `type` (`incident` or `maintenance`), `name`, `message`; optional `change_id` (append an update to an existing event when > 0), `status`, `affected_components`, and `start_time`/`end_time` (Unix epoch seconds, new maintenance only)."
},
"source": {
"type": "string",
"maxLength": 64,
"description": "Opaque marker of the drafting origin, e.g. `ai_sre:sess_xxx`. Up to 64 characters."
}
}
},
"CreateWarRoomRequest": {
"type": "object",
"description": "Parameters for opening an incident war room in an IM integration.",
Expand Down Expand Up @@ -28047,6 +28151,25 @@
}
}
},
"StatusPageDraftCreateResponse": {
"type": "object",
"description": "Result of storing a status page draft.",
"required": [
"draft_id",
"created_at"
],
"properties": {
"draft_id": {
"type": "string",
"description": "Draft ID matching `draft_[A-Za-z0-9]{22}`; the console review link carries it."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Creation time in Unix epoch seconds."
}
}
},
"StatusPageMigrationJob": {
"type": "object",
"description": "A migration job's current state and progress.",
Expand Down
123 changes: 123 additions & 0 deletions api-reference/on-call.openapi.zh.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12310,6 +12310,92 @@
]
}
},
"/status-page/draft/create": {
"post": {
"operationId": "statusPageDraftCreate",
"summary": "创建状态页草稿",
"description": "存储状态页事件草稿，供人工在控制台审核后发布。",
"tags": [
"On-call/状态页"
],
"x-mint": {
"content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- `draft` 载荷将被原样存储（最大 64 KB）；控制台发布表单会读取它来预填事件内容。\n- 草稿保留 30 天，事件发布时被消费且仅可消费一次。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
"href": "/zh/api-reference/on-call/status-pages/status-page-draft-create",
"metadata": {
"sidebarTitle": "创建状态页草稿"
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SuccessEnvelope"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/StatusPageDraftCreateResponse"
}
}
}
]
},
"example": {
"request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
"data": {
"draft_id": "draft_3xK9mQ2vN7pR4wT8yH1sJ5",
"created_at": 1788000000
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateStatusPageDraftRequest"
},
"example": {
"draft": {
"v": 1,
"page_id": 5750613685214,
"type": "incident",
"name": "Web Console Degraded Performance",
"message": "We are investigating degraded performance affecting the web console.",
"affected_components": [
{
"component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
"status": "degraded"
}
]
},
"source": "ai_sre:sess_01KC3H2A9ZQ8W7E6R5T4Y3U2I1"
}
}
}
}
}
},
"/enrichment/mapping/api/create": {
"post": {
"operationId": "mapping-api-write-create",
Expand Down Expand Up @@ -20940,6 +21026,24 @@
}
}
},
"CreateStatusPageDraftRequest": {
"type": "object",
"description": "存储状态页草稿的参数。`draft` 载荷将被原样存储，仅下列被校验的字段会被解析。",
"required": [
"draft"
],
"properties": {
"draft": {
"type": "object",
"description": "草稿载荷，原样存储，序列化后最大 64 KB。被校验的字段：`page_id`、`type`（`incident` 或 `maintenance`）、`name`、`message`；可选 `change_id`（大于 0 时表示向已有事件追加进展）、`status`、`affected_components`，以及 `start_time`/`end_time`（Unix epoch 秒，仅新建维护窗口时使用）。"
},
"source": {
"type": "string",
"maxLength": 64,
"description": "草稿来源的不透明标记，例如 `ai_sre:sess_xxx`。最长 64 个字符。"
}
}
},
"CreateWarRoomRequest": {
"type": "object",
"description": "为故障开启 IM 作战室所需的参数。",
Expand Down Expand Up @@ -28047,6 +28151,25 @@
}
}
},
"StatusPageDraftCreateResponse": {
"type": "object",
"description": "存储状态页草稿的结果。",
"required": [
"draft_id",
"created_at"
],
"properties": {
"draft_id": {
"type": "string",
"description": "草稿 ID，格式为 `draft_[A-Za-z0-9]{22}`；控制台审核链接会携带它。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间，Unix epoch 秒。"
}
}
},
"StatusPageMigrationJob": {
"type": "object",
"description": "迁移任务的当前状态及进度。",
Expand Down
Loading
Loading