{
  "openapi": "3.1.0",
  "info": {
    "title": "Hook API",
    "version": "1.0.0",
    "description": "Push notifications, iOS Live Activities, Lock Screen metrics and approvals for your iPhone. Authenticate every request with `Authorization: Bearer hk_...`."
  },
  "servers": [
    {
      "url": "https://gethook.app"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "paths": {
    "/api/publish": {
      "post": {
        "operationId": "publish",
        "summary": "Publish a notification",
        "description": "Send JSON with `Content-Type: application/vnd.hook.message+json`. The same fields can be set with `Hook-*` headers or query parameters. Returns 202.",
        "requestBody": {
          "required": true,
          "content": {
            "application/vnd.hook.message+json": {
              "schema": {
                "$ref": "#/components/schemas/Message"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "accepted": {
                      "type": "boolean"
                    },
                    "workspaceKey": {
                      "type": "string"
                    },
                    "identifier": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "source": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "workspace_missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/publish/{topic}": {
      "post": {
        "operationId": "publishToTopic",
        "summary": "Publish a notification to a topic",
        "parameters": [
          {
            "name": "topic",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/vnd.hook.message+json": {
              "schema": {
                "$ref": "#/components/schemas/Message"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "accepted": {
                      "type": "boolean"
                    },
                    "workspaceKey": {
                      "type": "string"
                    },
                    "identifier": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "source": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "workspace_missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/me": {
      "get": {
        "operationId": "getMe",
        "summary": "Current user, plan and workspace",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "email": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "plan": {
                      "type": "object",
                      "properties": {
                        "pro": {
                          "type": "boolean"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "usage": {
                          "type": "integer"
                        },
                        "historyDays": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      }
                    },
                    "notificationsEnabled": {
                      "type": "boolean"
                    },
                    "workspace": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "key": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/messages": {
      "get": {
        "operationId": "listMessages",
        "summary": "List messages (newest first)",
        "parameters": [
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Cursor: `nextCursor` of the previous page."
          },
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "archived",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "enum": [
                "mail"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MessageSummary"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "workspace_missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/messages/{id}/notification": {
      "delete": {
        "operationId": "dismissNotification",
        "summary": "Remove a delivered notification from the lock screen",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dismissed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Message not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/badge": {
      "post": {
        "operationId": "setBadge",
        "summary": "Set the app icon badge",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "count"
                ],
                "properties": {
                  "count": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 99999
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "devices": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/live-activity/streams": {
      "get": {
        "operationId": "listStreams",
        "summary": "List Live Activity streams",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "streams": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Stream"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/live-activity/stream/{key}": {
      "parameters": [
        {
          "name": "key",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"
          }
        }
      ],
      "put": {
        "operationId": "putStream",
        "summary": "Start or update a Live Activity stream",
        "description": "Starts the activity if the stream is not live, otherwise updates it. `skipped` means nothing changed. 409 `no_device` if no iPhone can show Live Activities yet.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StreamRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "result": {
                      "enum": [
                        "started",
                        "updated",
                        "skipped"
                      ]
                    },
                    "stream": {
                      "$ref": "#/components/schemas/Stream"
                    },
                    "warning": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "no_device",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "payload_too_large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "getStream",
        "summary": "Get a stream",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "stream": {
                      "$ref": "#/components/schemas/Stream"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "endStream",
        "summary": "End a stream",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content_state": {
                    "$ref": "#/components/schemas/ContentState"
                  },
                  "auto_dismiss_minutes": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 240,
                    "default": 2
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "result": {
                      "enum": [
                        "ended",
                        "already_ended"
                      ]
                    },
                    "stream": {
                      "$ref": "#/components/schemas/Stream"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/metrics": {
      "get": {
        "operationId": "listMetrics",
        "summary": "List Lock Screen widget metrics",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "metrics": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Metric"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/metrics/{key}": {
      "parameters": [
        {
          "name": "key",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"
          }
        }
      ],
      "put": {
        "operationId": "putMetric",
        "summary": "Create or update a metric",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "value"
                ],
                "properties": {
                  "value": {
                    "oneOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "string",
                        "maxLength": 24
                      }
                    ]
                  },
                  "label": {
                    "type": "string",
                    "maxLength": 30
                  },
                  "unit": {
                    "type": "string",
                    "maxLength": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "metric": {
                      "$ref": "#/components/schemas/Metric"
                    },
                    "created": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteMetric",
        "summary": "Delete a metric",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/approvals": {
      "post": {
        "operationId": "requestApproval",
        "summary": "Ask for approval on the iPhone",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "details": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "approve_label": {
                    "type": "string",
                    "maxLength": 30,
                    "default": "Approve"
                  },
                  "deny_label": {
                    "type": "string",
                    "maxLength": 30,
                    "default": "Deny"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "approval": {
                      "$ref": "#/components/schemas/Approval"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listApprovals",
        "summary": "List approvals",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ApprovalStatus"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "approvals": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Approval"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/approvals/{id}": {
      "get": {
        "operationId": "getApproval",
        "summary": "Get an approval, optionally long-polling",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "wait",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 50
            },
            "description": "Seconds to hold the request while the approval is pending (max 50). Loop for longer waits."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "approval": {
                      "$ref": "#/components/schemas/Approval"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/approvals/{id}/decision": {
      "post": {
        "operationId": "decideApproval",
        "summary": "Cancel a pending approval",
        "description": "Tokens can send `cancel`; approve/deny come from the phone.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "decision"
                ],
                "properties": {
                  "decision": {
                    "enum": [
                      "cancel",
                      "approve",
                      "deny"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "approval": {
                      "$ref": "#/components/schemas/Approval"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "already_decided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Hook API token, `hk_...`. Create one in the web app."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "string",
            "examples": [
              "invalid_content_state"
            ]
          },
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Priority": {
        "oneOf": [
          {
            "type": "integer",
            "minimum": 1,
            "maximum": 5
          },
          {
            "enum": [
              "min",
              "low",
              "default",
              "high",
              "urgent",
              "max"
            ]
          }
        ]
      },
      "Message": {
        "type": "object",
        "description": "At least title or message is needed for a formatted notification.",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 250
          },
          "message": {
            "type": "string",
            "maxLength": 4096
          },
          "priority": {
            "$ref": "#/components/schemas/Priority"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 64
            },
            "maxItems": 10
          },
          "click": {
            "type": "string",
            "format": "uri"
          },
          "icon": {
            "type": "string",
            "format": "uri"
          },
          "media": {
            "type": "string",
            "format": "uri"
          },
          "id": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[A-Za-z0-9_.:-]+$",
            "description": "Same id replaces/collapses the earlier notification."
          },
          "badge": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99999
          },
          "markdown": {
            "type": "boolean"
          },
          "actions": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/OpenAction"
                },
                {
                  "$ref": "#/components/schemas/HttpAction"
                }
              ]
            }
          }
        }
      },
      "OpenAction": {
        "type": "object",
        "required": [
          "type",
          "label",
          "url"
        ],
        "properties": {
          "type": {
            "const": "open"
          },
          "label": {
            "type": "string",
            "maxLength": 40
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "HttpAction": {
        "type": "object",
        "required": [
          "type",
          "label",
          "url"
        ],
        "properties": {
          "type": {
            "const": "http"
          },
          "label": {
            "type": "string",
            "maxLength": 40
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "method": {
            "enum": [
              "GET",
              "POST",
              "PUT",
              "PATCH",
              "DELETE"
            ],
            "default": "POST"
          },
          "body": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object"
              }
            ],
            "description": "Max 4096 characters once serialised."
          }
        }
      },
      "MessageSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string"
          },
          "topic": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "enum": [
              "mail",
              "webhook"
            ]
          },
          "priority": {
            "type": "integer"
          },
          "isSeen": {
            "type": "boolean"
          },
          "isArchived": {
            "type": "boolean"
          }
        }
      },
      "Color": {
        "type": "string",
        "description": "A name or #rrggbb.",
        "examples": [
          "blue",
          "#ff8800"
        ]
      },
      "ContentStateBase": {
        "type": "object",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 120
          },
          "subtitle": {
            "type": "string",
            "maxLength": 120
          },
          "message": {
            "type": "string",
            "maxLength": 300
          },
          "color": {
            "$ref": "#/components/schemas/Color"
          },
          "icon": {
            "type": "string",
            "maxLength": 60,
            "description": "SF Symbol name."
          },
          "badge": {
            "type": "string",
            "maxLength": 24
          }
        }
      },
      "MetricItem": {
        "type": "object",
        "required": [
          "label",
          "value"
        ],
        "properties": {
          "label": {
            "type": "string",
            "maxLength": 30
          },
          "value": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "unit": {
            "type": "string",
            "maxLength": 10
          }
        }
      },
      "ContentState": {
        "description": "Fields by activity type: value needs `value`; stats/metrics need `metrics` (1-6); progress needs `percentage`; segmented_progress needs `number_of_steps` and `current_step`; timer needs `end_date` or `duration_seconds`; alert needs only the base fields.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/ValueState"
          },
          {
            "$ref": "#/components/schemas/StatsState"
          },
          {
            "$ref": "#/components/schemas/AlertState"
          },
          {
            "$ref": "#/components/schemas/MetricsState"
          },
          {
            "$ref": "#/components/schemas/SegmentedProgressState"
          },
          {
            "$ref": "#/components/schemas/ProgressState"
          },
          {
            "$ref": "#/components/schemas/TimerState"
          }
        ]
      },
      "ValueState": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentStateBase"
          },
          {
            "properties": {
              "value": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  }
                ],
                "description": "Up to 40 characters."
              }
            }
          }
        ]
      },
      "StatsState": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentStateBase"
          },
          {
            "properties": {
              "metrics": {
                "type": "array",
                "minItems": 1,
                "maxItems": 6,
                "items": {
                  "$ref": "#/components/schemas/MetricItem"
                }
              }
            }
          }
        ]
      },
      "AlertState": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentStateBase"
          },
          {
            "properties": {}
          }
        ]
      },
      "MetricsState": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentStateBase"
          },
          {
            "properties": {
              "metrics": {
                "type": "array",
                "minItems": 1,
                "maxItems": 6,
                "items": {
                  "$ref": "#/components/schemas/MetricItem"
                }
              }
            }
          }
        ]
      },
      "SegmentedProgressState": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentStateBase"
          },
          {
            "properties": {
              "number_of_steps": {
                "type": "integer",
                "minimum": 1,
                "maximum": 12
              },
              "current_step": {
                "type": "integer",
                "minimum": 0,
                "maximum": 12
              }
            }
          }
        ]
      },
      "ProgressState": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentStateBase"
          },
          {
            "properties": {
              "percentage": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "TimerState": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentStateBase"
          },
          {
            "properties": {
              "start_date": {
                "oneOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "string"
                  }
                ],
                "description": "Epoch seconds/ms or ISO 8601. Defaults to now."
              },
              "end_date": {
                "oneOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "string"
                  }
                ]
              },
              "duration_seconds": {
                "type": "number",
                "minimum": 1,
                "maximum": 28800
              }
            }
          }
        ]
      },
      "ActivityType": {
        "enum": [
          "value",
          "stats",
          "alert",
          "metrics",
          "segmented_progress",
          "progress",
          "timer"
        ]
      },
      "ActivityButton": {
        "type": "object",
        "required": [
          "title",
          "url"
        ],
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 30
          },
          "type": {
            "enum": [
              "open_url",
              "webhook"
            ],
            "default": "open_url"
          },
          "url": {
            "type": "string",
            "description": "http(s) or shortcuts:// (open_url); http(s) only for webhook."
          },
          "method": {
            "enum": [
              "GET",
              "POST"
            ],
            "default": "POST"
          },
          "body": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object"
              }
            ]
          }
        }
      },
      "StreamRequest": {
        "type": "object",
        "required": [
          "type",
          "content_state"
        ],
        "properties": {
          "type": {
            "$ref": "#/components/schemas/ActivityType"
          },
          "content_state": {
            "$ref": "#/components/schemas/ContentState"
          },
          "action": {
            "$ref": "#/components/schemas/ActivityButton"
          },
          "secondary_action": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ActivityButton"
              }
            ],
            "description": "alert, progress and segmented_progress only."
          }
        }
      },
      "Stream": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "type": {
            "$ref": "#/components/schemas/ActivityType"
          },
          "state": {
            "type": "string",
            "description": "e.g. live, ended"
          },
          "contentState": {
            "type": "object",
            "additionalProperties": true
          },
          "devices": {
            "type": "integer"
          },
          "updatedAt": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "Metric": {
        "type": "object",
        "required": [
          "key",
          "value"
        ],
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ]
          },
          "label": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "updatedAt": {
            "type": "integer"
          }
        }
      },
      "ApprovalStatus": {
        "enum": [
          "pending",
          "approved",
          "denied",
          "cancelled",
          "expired"
        ]
      },
      "Approval": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "message": {
            "type": [
              "string",
              "null"
            ]
          },
          "details": {
            "type": [
              "object",
              "null"
            ]
          },
          "options": {
            "type": "object",
            "properties": {
              "approve": {
                "type": "string"
              },
              "deny": {
                "type": "string"
              }
            }
          },
          "status": {
            "$ref": "#/components/schemas/ApprovalStatus"
          },
          "createdAt": {
            "type": "integer"
          },
          "expiresAt": {
            "type": "integer"
          },
          "decidedAt": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      }
    }
  }
}
