{
  "openapi": "3.1.0",
  "info": {
    "title": "Time Tracker REST API",
    "version": "1.4.0",
    "description": "Time-tracking categories and events are separate from the Todo Bootstrap planner. All versioned endpoints require a bearer credential. A signed-in administrator can create scoped app keys from Connected Apps; administrator sessions can use every endpoint. Native apps do not require browser CORS permission. JSON request bodies are limited to 4,194,304 bytes and require Content-Type: application/json when nonempty. Tracking and activity times use UTC epoch seconds; planner times use UTC epoch milliseconds. Use HTTPS for remote access. This API does not schedule operating-system notifications."
  },
  "servers": [
    {
      "url": "/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/tasks": {
      "get": {
        "summary": "List time-tracking categories",
        "operationId": "get__tasks",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tasks": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Task"
                      }
                    }
                  },
                  "required": [
                    "tasks"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required permission: tracking:read"
      },
      "post": {
        "summary": "Create a time-tracking category",
        "operationId": "post__tasks",
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tasks": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Task"
                      }
                    }
                  },
                  "required": [
                    "tasks"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds 4,194,304 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A nonempty request body must use application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Creates or reactivates a category by name. An existing name is not duplicated. Returns the complete active category list. Required permission: tracking:write.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 300,
                    "minLength": 1,
                    "pattern": "\\S",
                    "description": "Surrounding whitespace is trimmed. After trimming, tabs and newlines are not allowed."
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/tracking": {
      "get": {
        "summary": "Read the current task and revision",
        "operationId": "get__tracking",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tracking"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required permission: tracking:read"
      }
    },
    "/tracking/switch": {
      "post": {
        "summary": "Switch the current task atomically",
        "operationId": "post__tracking_switch",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tracking"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds 4,194,304 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A nonempty request body must use application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale expected revision or reused request ID with different content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Requested task or app credential not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Creates an event at the server current time. Reusing a key with the same parsed JSON body returns the original response without reapplying the operation, even after later edits. A different body with that key returns 409. Keys are scoped to the authenticated credential and this operation. Automatic changes require a nonnull expected_revision; stale revisions return 409. Replay responses describe the original operation; GET /tracking for current state. The caller declares automatic; this is a concurrency check, not a permanent manual lock. Required permission: tracking:write.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Switch"
              }
            }
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "\\S"
            },
            "description": "Nonblank request key, trimmed before use. Deduplication is scoped to the authenticated credential and switch/stop operation."
          }
        ]
      }
    },
    "/tracking/stop": {
      "post": {
        "summary": "Switch to Untracked",
        "operationId": "post__tracking_stop",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tracking"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds 4,194,304 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A nonempty request body must use application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale expected revision or reused request ID with different content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Creates an event at the server current time. Reusing a key with the same parsed JSON body returns the original response without reapplying the operation, even after later edits. A different body with that key returns 409. Keys are scoped to the authenticated credential and this operation. Automatic changes require a nonnull expected_revision; stale revisions return 409. Replay responses describe the original operation; GET /tracking for current state. The caller declares automatic; this is a concurrency check, not a permanent manual lock. Required permission: tracking:write.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Stop"
              }
            }
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "\\S"
            },
            "description": "Nonblank request key, trimmed before use. Deduplication is scoped to the authenticated credential and switch/stop operation."
          }
        ]
      }
    },
    "/events": {
      "get": {
        "summary": "Read time-tracking history",
        "operationId": "get__events",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    },
                    "revision": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "events",
                    "revision"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Returns events in timestamp and insertion order within inclusive since/until boundaries. until must be at or after since. It does not include an event preceding since. Required permission: tracking:read.",
        "parameters": [
          {
            "in": "query",
            "name": "since",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 253402300799,
              "description": "UTC epoch seconds; fractional seconds are allowed.",
              "default": 0
            },
            "description": "UTC epoch seconds; inclusive boundary."
          },
          {
            "in": "query",
            "name": "until",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 253402300799,
              "description": "UTC epoch seconds; fractional seconds are allowed."
            },
            "description": "UTC epoch seconds; inclusive boundary."
          }
        ]
      }
    },
    "/activity": {
      "post": {
        "summary": "Record an observation without changing tracking",
        "operationId": "post__activity",
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Activity"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds 4,194,304 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A nonempty request body must use application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale expected revision or reused request ID with different content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Records an observation without switching the running task. Repeated IDs with identical normalized content return the original observation and received_at (also status 201); changed content returns 409. Required permission: activity:write.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActivityInput"
              }
            }
          }
        }
      },
      "get": {
        "summary": "Read observations",
        "operationId": "get__activity",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "activity": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Activity"
                      }
                    }
                  },
                  "required": [
                    "activity"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Lists observations from every source, sorted by server received_at. since filters receipt time inclusively, rather than original observation time. Required permission: activity:read.",
        "parameters": [
          {
            "in": "query",
            "name": "since",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 253402300799,
              "description": "UTC epoch seconds; fractional seconds are allowed.",
              "default": 0
            },
            "description": "Filter by server received_at, UTC epoch seconds."
          }
        ]
      }
    },
    "/tokens": {
      "get": {
        "summary": "List connected apps without their secrets",
        "operationId": "get__tokens",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tokens": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TokenMetadata"
                      }
                    }
                  },
                  "required": [
                    "tokens"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Returns active, unrevoked app credentials without secrets, sorted by creation time. Requires an administrator session; no app scope grants this operation."
      },
      "post": {
        "summary": "Create a revocable app credential",
        "operationId": "post__tokens",
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenCreated"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds 4,194,304 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A nonempty request body must use application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Returns the new secret once. Duplicate scopes are removed and sorted. The server stores a digest of the secret. Requires an administrator session; app credentials cannot create other credentials.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "minLength": 1,
                    "pattern": "\\S"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/Scope"
                    },
                    "minItems": 1
                  }
                },
                "required": [
                  "name",
                  "scopes"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/tokens/{id}": {
      "delete": {
        "summary": "Revoke one app credential",
        "operationId": "delete__tokens_id",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "success"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Requested task or app credential not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Revokes an active credential. Missing or already-revoked IDs return 404. Requires an administrator session.",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/planner": {
      "get": {
        "summary": "Read ordered areas, tasks, subtasks and settings",
        "operationId": "get__planner",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Planner"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Required permission: planner:read"
      },
      "put": {
        "summary": "Save a planner revision atomically",
        "operationId": "put__planner",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Planner"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds 4,194,304 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A nonempty request body must use application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Planner changed; response includes its latest state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlannerConflict"
                }
              }
            }
          },
          "422": {
            "description": "Invalid planner state, revision, timezone or Undo token type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Replaces the complete planner atomically after checking expected_revision. Array order is display order. Omitted areas are removed, not merged, and omitted optional fields reset to defaults, except omitted separate deadline/reminder time defaults preserve their saved values, and an omitted settings.inbox_area_id preserves the current reference while its Area remains. Preserve IDs when editing or reordering. Missing expected_revision is invalid. A conflict returns 409 with the latest state; reconcile your draft instead of blindly overwriting it. The saved revision increments from the current server revision, not state.revision. Required permission: planner:write. New or changed Area timer_category_id links must reference an active category; unchanged links to removed categories do not block unrelated edits. The theme compatibility field is ignored and normalized to #2196f3. Tasks inherit their containing Area category without overrides. Canonical output places timer_category_id only on Areas. Legacy task assignments migrate only when the Area field is absent and exactly one nonnull category is present across its tasks; conflicts leave the Area unassigned. Inbox is an ordinary Area identified by settings.inbox_area_id; renaming it preserves the reference and removing it clears the reference. The API never creates an Inbox or moves tasks implicitly. The four separate deadline/reminder defaults affect newly chosen dates only; existing task dates and recurrence schedules are unchanged. Deprecated shared creation-time fields remain accepted but cannot reset omitted separate defaults.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "state": {
                    "$ref": "#/components/schemas/PlannerInput"
                  },
                  "expected_revision": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  }
                },
                "required": [
                  "state",
                  "expected_revision"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/planner/dismiss": {
      "post": {
        "summary": "Dismiss a task or advance its recurrence",
        "operationId": "post__planner_dismiss",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "$ref": "#/components/schemas/Planner"
                    },
                    "undo_token": {
                      "type": "string"
                    },
                    "action": {
                      "enum": [
                        "advanced",
                        "removed"
                      ]
                    },
                    "undo_expires_at": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 253402300799999,
                      "description": "UTC epoch milliseconds."
                    }
                  },
                  "required": [
                    "state",
                    "undo_token",
                    "action",
                    "undo_expires_at"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds 4,194,304 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A nonempty request body must use application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Requested task or app credential not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Planner changed; response includes its latest state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlannerConflict"
                }
              }
            }
          },
          "422": {
            "description": "Invalid planner state, revision, timezone or Undo token type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Advances a recurring task to its next occurrence and clears all subtask checkmarks. If no next occurrence exists, removes the task. Returns the updated state and a five-second Undo token. The deadline bounds the final local date of recurrence. Required permission: planner:write.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "task_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[A-Za-z0-9_-]+$",
                    "description": "Stable client-generated ID. IDs must be unique across all planner areas, tasks and subtasks."
                  },
                  "expected_revision": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "timezone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100,
                    "pattern": "^[^\\u0000]*$",
                    "minLength": 1,
                    "description": "Optional timezone for this calculation only. Omitted or null uses planner settings.timezone; it does not modify settings."
                  }
                },
                "required": [
                  "task_id",
                  "expected_revision"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/planner/undo": {
      "post": {
        "summary": "Undo dismissal within five seconds",
        "operationId": "post__planner_undo",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "$ref": "#/components/schemas/Planner"
                    }
                  },
                  "required": [
                    "state"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid request type or invalid general API field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds 4,194,304 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A nonempty request body must use application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Planner changed; response includes its latest state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlannerConflict"
                }
              }
            }
          },
          "422": {
            "description": "Invalid planner state, revision, timezone or Undo token type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Undo token expired, is unknown, or was lost during a server restart",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Restores the entire dismissed task, including subtask completion and original list position. Any intervening planner revision causes 409. Tokens expire after five seconds, are single-use, are held in memory, and do not survive a server restart. Expired or unknown tokens return 410. Required permission: planner:write.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "undo_token": {
                    "type": "string"
                  },
                  "expected_revision": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  }
                },
                "required": [
                  "undo_token",
                  "expected_revision"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "Read this API specification",
        "operationId": "get__openapi",
        "description": "Requires any valid bearer credential; no particular app scope is required. The same file is also served publicly at /openapi.json outside the versioned API.",
        "responses": {
          "200": {
            "description": "OpenAPI document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "API specification could not be read",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/planner/tasks/{task_id}/start": {
      "post": {
        "summary": "Start a planner task in its Area timer category",
        "operationId": "post__planner_tasks_task_id_start",
        "description": "Requires both planner:read and tracking:write (administrator sessions also qualify). On the first successful request, the server reads the saved planner task and its containing Area, verifies that the Area category is active, and atomically adds a tracking event with that category, the exact task title as description (including whitespace and newlines), and the stable task ID as planner_task_id. Every task inherits its Area category without task-level overrides. Moving a task or changing its Area category affects future starts; existing time history is unchanged. The task itself is not completed, dismissed or modified. Every new successful command creates a separate interval, including tasks sharing a category or title. Category and description cannot be overridden in the request body. Idempotency keys are scoped to the credential and the planner-start operation across all task IDs. A retry with the same task ID and body returns the original response before resolving planner state or checking revisions again, even if the task was subsequently renamed, moved or deleted, its Area category was changed, or the original category was removed. A reused key with a different task ID or body returns 409. Replayed responses describe the original operation; GET /tracking for current state. An unassigned Area returns 422; a missing/inactive Area category returns 409 and requires reassignment.",
        "parameters": [
          {
            "in": "path",
            "name": "task_id",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "\\S"
            },
            "description": "Use one key for retries of one intended Play command. Use a new key for a later intentional start."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlannerStart"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Original or newly created tracking state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tracking"
                }
              }
            }
          },
          "400": {
            "description": "Invalid task ID, options, retry key, or missing automatic tracking precondition",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bearer credential missing, invalid or revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Both planner:read and tracking:write are required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Planner task does not exist on the first attempt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Area category removed, stale tracking revision, or retry-key conflict; latest planner state is included",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlannerConflict"
                }
              }
            }
          },
          "413": {
            "description": "JSON body exceeds 4,194,304 bytes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "A nonempty request body must use application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The task's containing Area has no timer category",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Planner or tracking data could not be read or saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Use an app credential created by an administrator, or an existing administrator session token. App credentials have the permissions listed by each operation and remain valid until revoked. Credential-management operations require an administrator session."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/Planner"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "Task": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "maxLength": 300
          },
          "position": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "id",
          "name",
          "position"
        ],
        "additionalProperties": false
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "timestamp": {
            "type": "number",
            "description": "UTC epoch seconds, potentially fractional."
          },
          "task_id": {
            "type": "string",
            "format": "uuid"
          },
          "task": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "description": "Source credential ID, a session-derived identifier, web, or migration."
          },
          "planner_task_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Stable originating planner task ID for Play events, or null for manual/legacy tracking events. Survives planner rename or removal; description remains the title snapshot captured when Play succeeded."
          }
        },
        "required": [
          "id",
          "timestamp",
          "task_id",
          "task",
          "description",
          "source",
          "planner_task_id"
        ],
        "additionalProperties": false
      },
      "Tracking": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "current": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Event"
              },
              {
                "type": "null"
              }
            ],
            "description": "Most recent event by timestamp, with insertion order breaking ties. Null if history is empty."
          }
        },
        "required": [
          "revision",
          "current"
        ],
        "additionalProperties": false
      },
      "Switch": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "maxLength": 100,
            "minLength": 1,
            "pattern": "\\S",
            "description": "ID of an active time-tracking category returned by GET /tasks."
          },
          "description": {
            "type": "string",
            "maxLength": 10000,
            "default": "",
            "description": "Optional text attached to the new event; surrounding whitespace is trimmed."
          },
          "expected_revision": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Required and nonnull when automatic is true. A different current revision returns 409."
          },
          "automatic": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "task_id"
        ],
        "additionalProperties": true,
        "allOf": [
          {
            "if": {
              "properties": {
                "automatic": {
                  "const": true
                }
              },
              "required": [
                "automatic"
              ]
            },
            "then": {
              "required": [
                "expected_revision"
              ],
              "properties": {
                "expected_revision": {
                  "type": "integer"
                }
              }
            }
          }
        ]
      },
      "Stop": {
        "type": "object",
        "properties": {
          "expected_revision": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Required and nonnull when automatic is true. A different current revision returns 409."
          },
          "automatic": {
            "type": "boolean",
            "default": false
          },
          "description": {
            "type": "string",
            "maxLength": 10000,
            "default": "",
            "description": "Optional text attached to the new event; surrounding whitespace is trimmed."
          }
        },
        "required": [],
        "additionalProperties": true,
        "allOf": [
          {
            "if": {
              "properties": {
                "automatic": {
                  "const": true
                }
              },
              "required": [
                "automatic"
              ]
            },
            "then": {
              "required": [
                "expected_revision"
              ],
              "properties": {
                "expected_revision": {
                  "type": "integer"
                }
              }
            }
          }
        ]
      },
      "ActivityInput": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 100,
            "minLength": 1,
            "pattern": "\\S",
            "description": "Client event ID, scoped to the credential and trimmed. Identical normalized content is safely deduplicated; different content returns 409."
          },
          "started_at": {
            "oneOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 253402300799,
                "description": "UTC epoch seconds; fractional seconds are allowed."
              },
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp including an explicit timezone, representing an instant in the supported epoch-seconds range."
              }
            ]
          },
          "ended_at": {
            "oneOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 253402300799,
                "description": "UTC epoch seconds; fractional seconds are allowed."
              },
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp including an explicit timezone, representing an instant in the supported epoch-seconds range."
              }
            ]
          },
          "application": {
            "type": "string",
            "maxLength": 2000,
            "description": "Optional metadata; surrounding whitespace is trimmed."
          },
          "window_title": {
            "type": "string",
            "maxLength": 2000,
            "description": "Optional metadata; surrounding whitespace is trimmed."
          },
          "idle": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "started_at",
          "ended_at"
        ],
        "additionalProperties": false,
        "description": "ended_at must be at or after started_at. Activity observations do not change the running task."
      },
      "Scope": {
        "type": "string",
        "enum": [
          "tracking:read",
          "tracking:write",
          "activity:read",
          "activity:write",
          "planner:read",
          "planner:write"
        ]
      },
      "TokenMetadata": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "maxLength": 100,
            "minLength": 1,
            "pattern": "\\S"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            },
            "minItems": 1,
            "uniqueItems": true
          },
          "created_at": {
            "type": "number",
            "minimum": 0,
            "maximum": 253402300799,
            "description": "UTC epoch seconds; fractional seconds are allowed."
          }
        },
        "required": [
          "id",
          "name",
          "scopes",
          "created_at"
        ],
        "additionalProperties": false
      },
      "TokenCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "maxLength": 100,
            "minLength": 1,
            "pattern": "\\S"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            },
            "minItems": 1,
            "uniqueItems": true
          },
          "created_at": {
            "type": "number",
            "minimum": 0,
            "maximum": 253402300799,
            "description": "UTC epoch seconds; fractional seconds are allowed."
          },
          "token": {
            "type": "string",
            "description": "Shown once. Store in your OS credential store."
          }
        },
        "required": [
          "id",
          "name",
          "scopes",
          "created_at",
          "token"
        ],
        "additionalProperties": false
      },
      "Icon": {
        "type": "object",
        "properties": {
          "codePoint": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1114111
          },
          "fontFamily": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[^\\u0000]*$"
          },
          "fontPackage": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[^\\u0000]*$"
          }
        },
        "required": [
          "codePoint",
          "fontFamily",
          "fontPackage"
        ],
        "additionalProperties": false
      },
      "Subtask": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Stable client-generated ID. IDs must be unique across all planner areas, tasks and subtasks."
          },
          "name": {
            "type": "string",
            "maxLength": 2000,
            "pattern": "^[^\\u0000]*$"
          },
          "complete": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "complete"
        ],
        "additionalProperties": false
      },
      "Recurrence": {
        "oneOf": [
          {
            "type": "null"
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "const": "days"
              },
              "n": {
                "type": "integer",
                "minimum": 1,
                "maximum": 3652059
              },
              "recur_on_dismiss": {
                "type": "boolean",
                "description": "When true, calculate n days after the dismissal local date using the original reminder clock time. Otherwise advance on the previous reminder schedule, skipping past occurrences."
              }
            },
            "required": [
              "type",
              "n",
              "recur_on_dismiss"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "const": "weeks"
              },
              "n": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9
              },
              "days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 62
                },
                "uniqueItems": true,
                "maxItems": 63
              }
            },
            "required": [
              "type",
              "n",
              "days"
            ],
            "additionalProperties": false,
            "description": "Selected day indices belong to an n-week cycle anchored on Monday, 2024-01-01. Every index must be less than n*7.",
            "allOf": [
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 1
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 7,
                      "items": {
                        "maximum": 6
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 2
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 14,
                      "items": {
                        "maximum": 13
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 3
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 21,
                      "items": {
                        "maximum": 20
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 4
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 28,
                      "items": {
                        "maximum": 27
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 5
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 35,
                      "items": {
                        "maximum": 34
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 6
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 42,
                      "items": {
                        "maximum": 41
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 7
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 49,
                      "items": {
                        "maximum": 48
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 8
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 56,
                      "items": {
                        "maximum": 55
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 9
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 63,
                      "items": {
                        "maximum": 62
                      }
                    }
                  }
                }
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "const": "monthly"
              },
              "by_date": {
                "type": "boolean"
              },
              "days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 34
                },
                "uniqueItems": true,
                "maxItems": 35
              }
            },
            "required": [
              "type",
              "by_date",
              "days"
            ],
            "additionalProperties": false,
            "allOf": [
              {
                "if": {
                  "properties": {
                    "by_date": {
                      "const": true
                    }
                  },
                  "required": [
                    "by_date"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 31,
                      "items": {
                        "maximum": 30
                      }
                    }
                  }
                }
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "const": "yearly"
              },
              "by_day_of_week": {
                "type": "boolean"
              },
              "days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 34
                },
                "uniqueItems": true,
                "maxItems": 35
              },
              "months": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 11
                },
                "uniqueItems": true,
                "maxItems": 12
              }
            },
            "required": [
              "type",
              "by_day_of_week",
              "days",
              "months"
            ],
            "additionalProperties": false,
            "allOf": [
              {
                "if": {
                  "properties": {
                    "by_day_of_week": {
                      "const": true
                    }
                  },
                  "required": [
                    "by_day_of_week"
                  ]
                },
                "else": {
                  "properties": {
                    "days": {
                      "maxItems": 31,
                      "items": {
                        "maximum": 30
                      }
                    }
                  }
                }
              }
            ]
          }
        ],
        "description": "A nonnull recurrence requires a reminder. Empty selections produce no next occurrence. Dates are evaluated in planner settings.timezone unless dismissal supplies an override. The next occurrence is after the current reminder local date and at or after dismissal time. Calendar arithmetic preserves the reminder wall-clock time; nonexistent DST times move forward through the gap, and ambiguous times use the first occurrence. Selected date indices 0\u201330 mean days 1\u201331 and clamp to month end. Weekday indices 0\u201334 are first/second/third/fourth/last week blocks, each Monday through Sunday. Month indices 0\u201311 mean January through December."
      },
      "PlannerTask": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Stable client-generated ID. IDs must be unique across all planner areas, tasks and subtasks."
          },
          "name": {
            "type": "string",
            "maxLength": 2000,
            "pattern": "^[^\\u0000]*$"
          },
          "notes": {
            "type": "string",
            "maxLength": 100000,
            "pattern": "^[^\\u0000]*$"
          },
          "focus": {
            "type": "boolean"
          },
          "on_fire": {
            "type": "boolean"
          },
          "deadline": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 253402300799999,
            "description": "UTC epoch milliseconds, or null when unset. Its local calendar date also bounds the final recurrence; the deadline clock time does not shorten that final date."
          },
          "reminder": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 253402300799999,
            "description": "UTC epoch milliseconds, or null when unset."
          },
          "subtasks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Subtask"
            },
            "maxItems": 10000
          },
          "recurrence": {
            "$ref": "#/components/schemas/Recurrence"
          }
        },
        "required": [
          "id",
          "name",
          "notes",
          "focus",
          "on_fire",
          "deadline",
          "reminder",
          "subtasks",
          "recurrence"
        ],
        "additionalProperties": false,
        "allOf": [
          {
            "if": {
              "properties": {
                "recurrence": {
                  "type": "object"
                }
              },
              "required": [
                "recurrence"
              ]
            },
            "then": {
              "required": [
                "reminder"
              ],
              "properties": {
                "reminder": {
                  "type": "integer"
                }
              }
            }
          }
        ]
      },
      "Area": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Stable client-generated ID. IDs must be unique across all planner areas, tasks and subtasks."
          },
          "name": {
            "type": "string",
            "maxLength": 500,
            "pattern": "^[^\\u0000]*$"
          },
          "color": {
            "type": "string",
            "pattern": "^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$",
            "description": "Hexadecimal color; normalized to lowercase."
          },
          "icon": {
            "$ref": "#/components/schemas/Icon"
          },
          "tasks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlannerTask"
            },
            "maxItems": 10000
          },
          "timer_category_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Timer category inherited by every task in this Area, from GET /tasks; null means unassigned. Newly assigned or changed links must identify an active category. An unchanged link to a subsequently removed category may remain during unrelated edits, but Play requires the Area to be reassigned. Moving a task changes its inherited category for future starts; existing time history is unchanged."
          }
        },
        "required": [
          "id",
          "name",
          "color",
          "icon",
          "tasks",
          "timer_category_id"
        ],
        "additionalProperties": false
      },
      "Settings": {
        "type": "object",
        "properties": {
          "theme": {
            "type": "string",
            "const": "#2196f3",
            "description": "Fixed blue application theme. Retained for saved-state compatibility; it is not customizable."
          },
          "default_creation_time": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Deprecated shared date default in local HH:MM form, retained for older REST clients. Older stored state uses this value to initialize missing separate deadline/reminder defaults. Updating this compatibility value does not reset saved separate defaults; set the new fields explicitly.",
            "deprecated": true,
            "minLength": 5,
            "maxLength": 5
          },
          "default_creation_time_today": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Deprecated shared date default in local HH:MM form, retained for older REST clients. Older stored state uses this value to initialize missing separate deadline/reminder defaults. Updating this compatibility value does not reset saved separate defaults; set the new fields explicitly.",
            "deprecated": true,
            "minLength": 5,
            "maxLength": 5
          },
          "timezone": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[^\\u0000]*$",
            "minLength": 1,
            "description": "IANA timezone key available on the server, such as America/Denver or UTC."
          },
          "inbox_area_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Stable ID of the ordinary Area used as Inbox, independent of its display name; null means no Inbox is assigned. A valid-format ID that does not identify an Area normalizes to null. Reading state never creates an Inbox or moves tasks. Older saved data defaults to null."
          },
          "default_deadline_time": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Local HH:MM default for deadline dates on other dates, interpreted in settings.timezone. If absent from older saved data, inherits default_creation_time (00:00 if that legacy field is absent). This setting never changes existing task timestamps or recurrence schedules.",
            "minLength": 5,
            "maxLength": 5
          },
          "default_deadline_time_today": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Local HH:MM default for deadline dates on today's date, interpreted in settings.timezone. If absent from older saved data, inherits default_creation_time_today (11:00 if that legacy field is absent). This setting never changes existing task timestamps or recurrence schedules.",
            "minLength": 5,
            "maxLength": 5
          },
          "default_reminder_time": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Local HH:MM default for reminder dates on other dates, interpreted in settings.timezone. If absent from older saved data, inherits default_creation_time (00:00 if that legacy field is absent). This setting never changes existing task timestamps or recurrence schedules.",
            "minLength": 5,
            "maxLength": 5
          },
          "default_reminder_time_today": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Local HH:MM default for reminder dates on today's date, interpreted in settings.timezone. If absent from older saved data, inherits default_creation_time_today (11:00 if that legacy field is absent). This setting never changes existing task timestamps or recurrence schedules.",
            "minLength": 5,
            "maxLength": 5
          }
        },
        "required": [
          "theme",
          "default_creation_time",
          "default_creation_time_today",
          "timezone",
          "inbox_area_id",
          "default_deadline_time",
          "default_deadline_time_today",
          "default_reminder_time",
          "default_reminder_time_today"
        ],
        "additionalProperties": false
      },
      "Planner": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "areas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Area"
            },
            "maxItems": 10000
          },
          "settings": {
            "$ref": "#/components/schemas/Settings"
          }
        },
        "required": [
          "revision",
          "areas",
          "settings"
        ],
        "additionalProperties": false,
        "description": "Normalized full state. IDs are unique across all areas, tasks and subtasks; their combined count is at most 10,000. Array order is display order. Planner and tracking revisions are independent."
      },
      "Activity": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 100,
            "minLength": 1,
            "pattern": "\\S",
            "description": "Client event ID, scoped to the credential and trimmed. Identical normalized content is safely deduplicated; different content returns 409."
          },
          "started_at": {
            "type": "number",
            "minimum": 0,
            "maximum": 253402300799,
            "description": "UTC epoch seconds; fractional seconds are allowed."
          },
          "ended_at": {
            "type": "number",
            "minimum": 0,
            "maximum": 253402300799,
            "description": "UTC epoch seconds; fractional seconds are allowed."
          },
          "application": {
            "type": "string",
            "maxLength": 2000,
            "description": "Optional metadata; surrounding whitespace is trimmed."
          },
          "window_title": {
            "type": "string",
            "maxLength": 2000,
            "description": "Optional metadata; surrounding whitespace is trimmed."
          },
          "idle": {
            "type": "boolean"
          },
          "source": {
            "type": "string",
            "description": "Authenticated source credential ID or session-derived identifier."
          },
          "received_at": {
            "type": "number",
            "minimum": 0,
            "maximum": 253402300799,
            "description": "UTC epoch seconds; fractional seconds are allowed."
          }
        },
        "required": [
          "id",
          "started_at",
          "ended_at",
          "source",
          "received_at"
        ],
        "additionalProperties": false,
        "description": "ended_at must be at or after started_at. Activity observations do not change the running task."
      },
      "PlannerConflict": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/Planner"
          }
        },
        "required": [
          "error",
          "state"
        ],
        "additionalProperties": false
      },
      "IconInput": {
        "type": "object",
        "properties": {
          "codePoint": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1114111,
            "default": 57691
          },
          "fontFamily": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[^\\u0000]*$",
            "default": null
          },
          "fontPackage": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "pattern": "^[^\\u0000]*$",
            "default": null
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "SubtaskInput": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Stable client-generated ID. IDs must be unique across all planner areas, tasks and subtasks."
          },
          "name": {
            "type": "string",
            "maxLength": 2000,
            "pattern": "^[^\\u0000]*$",
            "default": ""
          },
          "complete": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false
      },
      "RecurrenceInput": {
        "oneOf": [
          {
            "type": "null"
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "const": "days"
              },
              "n": {
                "type": "integer",
                "minimum": 1,
                "maximum": 3652059
              },
              "recur_on_dismiss": {
                "type": "boolean",
                "description": "When true, calculate n days after the dismissal local date using the original reminder clock time. Otherwise advance on the previous reminder schedule, skipping past occurrences.",
                "default": false
              }
            },
            "required": [
              "type",
              "n"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "const": "weeks"
              },
              "n": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9
              },
              "days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 62
                },
                "uniqueItems": true,
                "maxItems": 63,
                "default": []
              }
            },
            "required": [
              "type",
              "n"
            ],
            "additionalProperties": false,
            "description": "Selected day indices belong to an n-week cycle anchored on Monday, 2024-01-01. Every index must be less than n*7.",
            "allOf": [
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 1
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 7,
                      "items": {
                        "maximum": 6
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 2
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 14,
                      "items": {
                        "maximum": 13
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 3
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 21,
                      "items": {
                        "maximum": 20
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 4
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 28,
                      "items": {
                        "maximum": 27
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 5
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 35,
                      "items": {
                        "maximum": 34
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 6
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 42,
                      "items": {
                        "maximum": 41
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 7
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 49,
                      "items": {
                        "maximum": 48
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 8
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 56,
                      "items": {
                        "maximum": 55
                      }
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "n": {
                      "const": 9
                    }
                  },
                  "required": [
                    "n"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 63,
                      "items": {
                        "maximum": 62
                      }
                    }
                  }
                }
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "const": "monthly"
              },
              "by_date": {
                "type": "boolean",
                "default": false
              },
              "days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 34
                },
                "uniqueItems": true,
                "maxItems": 35,
                "default": []
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false,
            "allOf": [
              {
                "if": {
                  "properties": {
                    "by_date": {
                      "const": true
                    }
                  },
                  "required": [
                    "by_date"
                  ]
                },
                "then": {
                  "properties": {
                    "days": {
                      "maxItems": 31,
                      "items": {
                        "maximum": 30
                      }
                    }
                  }
                }
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "const": "yearly"
              },
              "by_day_of_week": {
                "type": "boolean",
                "default": false
              },
              "days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 34
                },
                "uniqueItems": true,
                "maxItems": 35,
                "default": []
              },
              "months": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 11
                },
                "uniqueItems": true,
                "maxItems": 12,
                "default": []
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false,
            "allOf": [
              {
                "if": {
                  "properties": {
                    "by_day_of_week": {
                      "const": true
                    }
                  },
                  "required": [
                    "by_day_of_week"
                  ]
                },
                "else": {
                  "properties": {
                    "days": {
                      "maxItems": 31,
                      "items": {
                        "maximum": 30
                      }
                    }
                  }
                }
              }
            ]
          }
        ],
        "description": "A nonnull recurrence requires a reminder. Empty selections produce no next occurrence. Dates are evaluated in planner settings.timezone unless dismissal supplies an override. The next occurrence is after the current reminder local date and at or after dismissal time. Calendar arithmetic preserves the reminder wall-clock time; nonexistent DST times move forward through the gap, and ambiguous times use the first occurrence. Selected date indices 0\u201330 mean days 1\u201331 and clamp to month end. Weekday indices 0\u201334 are first/second/third/fourth/last week blocks, each Monday through Sunday. Month indices 0\u201311 mean January through December."
      },
      "PlannerTaskInput": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Stable client-generated ID. IDs must be unique across all planner areas, tasks and subtasks."
          },
          "name": {
            "type": "string",
            "maxLength": 2000,
            "pattern": "^[^\\u0000]*$",
            "default": ""
          },
          "notes": {
            "type": "string",
            "maxLength": 100000,
            "pattern": "^[^\\u0000]*$",
            "default": ""
          },
          "focus": {
            "type": "boolean",
            "default": false
          },
          "on_fire": {
            "type": "boolean",
            "default": false
          },
          "deadline": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 253402300799999,
            "description": "UTC epoch milliseconds, or null when unset. Its local calendar date also bounds the final recurrence; the deadline clock time does not shorten that final date.",
            "default": null
          },
          "reminder": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 253402300799999,
            "description": "UTC epoch milliseconds, or null when unset.",
            "default": null
          },
          "subtasks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SubtaskInput"
            },
            "maxItems": 10000,
            "default": []
          },
          "recurrence": {
            "$ref": "#/components/schemas/RecurrenceInput",
            "default": null
          },
          "timer_category_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Deprecated migration input only; never returned in canonical task state and never a per-task override. Used only when the containing Area omits timer_category_id: one distinct nonnull legacy task category migrates to the Area, while conflicting categories leave it unassigned. Any explicit Area value, including null, takes precedence.",
            "deprecated": true
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false,
        "allOf": [
          {
            "if": {
              "properties": {
                "recurrence": {
                  "type": "object"
                }
              },
              "required": [
                "recurrence"
              ]
            },
            "then": {
              "required": [
                "reminder"
              ],
              "properties": {
                "reminder": {
                  "type": "integer"
                }
              }
            }
          }
        ]
      },
      "AreaInput": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Stable client-generated ID. IDs must be unique across all planner areas, tasks and subtasks."
          },
          "name": {
            "type": "string",
            "maxLength": 500,
            "pattern": "^[^\\u0000]*$",
            "default": ""
          },
          "color": {
            "type": "string",
            "pattern": "^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$",
            "description": "Hexadecimal color; normalized to lowercase.",
            "default": "#2196f3"
          },
          "icon": {
            "$ref": "#/components/schemas/IconInput",
            "description": "If omitted, defaults to codePoint 57691, fontFamily MaterialIcons and fontPackage null. If present, omitted codePoint defaults to 57691 and omitted font fields to null."
          },
          "tasks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlannerTaskInput"
            },
            "maxItems": 10000,
            "default": []
          },
          "timer_category_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Timer category inherited by every task in this Area, from GET /tasks; null means unassigned. Newly assigned or changed links must identify an active category. An unchanged link to a subsequently removed category may remain during unrelated edits, but Play requires the Area to be reassigned. Moving a task changes its inherited category for future starts; existing time history is unchanged. If present, including explicit null, this value is authoritative and deprecated task-level values are discarded. If omitted, exactly one distinct nonnull legacy task category in the Area is migrated here; no categories or conflicting categories result in null."
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false
      },
      "SettingsInput": {
        "type": "object",
        "properties": {
          "theme": {
            "deprecated": true,
            "default": "#2196f3",
            "description": "Compatibility field only. Submitted and previously saved values are ignored; normalized state always returns #2196f3."
          },
          "default_creation_time": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Deprecated shared date default in local HH:MM form, retained for older REST clients. Older stored state uses this value to initialize missing separate deadline/reminder defaults. Updating this compatibility value does not reset saved separate defaults; set the new fields explicitly.",
            "default": "00:00",
            "deprecated": true,
            "minLength": 5,
            "maxLength": 5
          },
          "default_creation_time_today": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Deprecated shared date default in local HH:MM form, retained for older REST clients. Older stored state uses this value to initialize missing separate deadline/reminder defaults. Updating this compatibility value does not reset saved separate defaults; set the new fields explicitly.",
            "default": "11:00",
            "deprecated": true,
            "minLength": 5,
            "maxLength": 5
          },
          "timezone": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[^\\u0000]*$",
            "minLength": 1,
            "description": "IANA timezone key available on the server, such as America/Denver or UTC.",
            "default": "America/Denver"
          },
          "inbox_area_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Stable ID of the ordinary Area used as Inbox, independent of its display name; null means no Inbox is assigned. A valid-format ID that does not identify an Area normalizes to null. Reading state never creates an Inbox or moves tasks. Older saved data defaults to null. On PUT, omitting this field preserves the current Inbox reference if its Area remains, for older-client compatibility. Explicit null clears it; deleting the referenced Area also clears it. Create an Inbox lazily by submitting its Area, this pointer, and the captured task together in one revision-checked planner PUT."
          },
          "default_deadline_time": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Local HH:MM default for deadline dates on other dates, interpreted in settings.timezone. If absent from older saved data, inherits default_creation_time (00:00 if that legacy field is absent). This setting never changes existing task timestamps or recurrence schedules. On PUT, omission preserves the currently saved value, including when all settings are omitted. An explicit value overrides it.",
            "minLength": 5,
            "maxLength": 5
          },
          "default_deadline_time_today": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Local HH:MM default for deadline dates on today's date, interpreted in settings.timezone. If absent from older saved data, inherits default_creation_time_today (11:00 if that legacy field is absent). This setting never changes existing task timestamps or recurrence schedules. On PUT, omission preserves the currently saved value, including when all settings are omitted. An explicit value overrides it.",
            "minLength": 5,
            "maxLength": 5
          },
          "default_reminder_time": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Local HH:MM default for reminder dates on other dates, interpreted in settings.timezone. If absent from older saved data, inherits default_creation_time (00:00 if that legacy field is absent). This setting never changes existing task timestamps or recurrence schedules. On PUT, omission preserves the currently saved value, including when all settings are omitted. An explicit value overrides it.",
            "minLength": 5,
            "maxLength": 5
          },
          "default_reminder_time_today": {
            "type": "string",
            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "Local HH:MM default for reminder dates on today's date, interpreted in settings.timezone. If absent from older saved data, inherits default_creation_time_today (11:00 if that legacy field is absent). This setting never changes existing task timestamps or recurrence schedules. On PUT, omission preserves the currently saved value, including when all settings are omitted. An explicit value overrides it.",
            "minLength": 5,
            "maxLength": 5
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "PlannerInput": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "default": 0
          },
          "areas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AreaInput"
            },
            "maxItems": 10000,
            "default": []
          },
          "settings": {
            "$ref": "#/components/schemas/SettingsInput"
          }
        },
        "required": [],
        "additionalProperties": false,
        "description": "Full replacement input. Omitted areas become empty; omitted settings use defaults except the four separate deadline/reminder time defaults and the Inbox reference are preserved from current state (the Inbox reference clears if its Area is removed). state.revision is validated but the server assigns the next revision from expected_revision. Preserve existing IDs. At most 10,000 total areas, tasks and subtasks, with globally unique IDs."
      },
      "PlannerStart": {
        "type": "object",
        "properties": {
          "expected_revision": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Tracking revision from GET /tracking, not the planner revision. Required and nonnull when automatic is true; stale revisions return 409."
          },
          "automatic": {
            "type": "boolean",
            "default": false
          }
        },
        "additionalProperties": false,
        "allOf": [
          {
            "if": {
              "properties": {
                "automatic": {
                  "const": true
                }
              },
              "required": [
                "automatic"
              ]
            },
            "then": {
              "required": [
                "expected_revision"
              ],
              "properties": {
                "expected_revision": {
                  "type": "integer"
                }
              }
            }
          }
        ]
      }
    }
  }
}
