RouteRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/dotsy-ai/json-schema/dotsy-ai-route-request-schema.json",
  "title": "RouteRequest",
  "description": "Route fields. Everything is optional. Send `null` on a nullable field to clear it back to its default.",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/dotsy-ai-openapi.yml#/components/schemas/RouteRequest",
  "type": "object",
  "properties": {
    "contentKey": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "description": "Explicit content key (defaults to a path-derived key when omitted). null clears an explicit key back to that path default — same as omitting it, but usable on a PATCH to undo a prior set."
    },
    "layout": {
      "type": [
        "string",
        "null"
      ],
      "description": "Layout NAME, bare: \"default\" for layouts/default.html — not the file key. It must already exist as layouts/<name>.html (400 layout_not_found otherwise). null removes the layout."
    },
    "title": {
      "type": [
        "string",
        "null"
      ]
    },
    "vars": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": {
        "type": "string"
      }
    },
    "purpose": {
      "type": [
        "string",
        "null"
      ]
    },
    "redirectTo": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "description": "Redirect target, a root-relative path (/…). Required when purpose is \"redirect\". null clears it — only valid once purpose stops being \"redirect\" (a redirect route always needs a target)."
    },
    "redirectStatus": {
      "anyOf": [
        {
          "type": "number",
          "enum": [
            301
          ]
        },
        {
          "type": "number",
          "enum": [
            302
          ]
        },
        {
          "type": "number",
          "enum": [
            308
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "301 permanent / 302 or 308 temporary (default 301 on a redirect). null clears an explicit override."
    },
    "preserveQuery": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Append the visitor's original query string to the redirect target (default true on a redirect). null clears an explicit override."
    },
    "navLabel": {
      "type": [
        "string",
        "null"
      ],
      "description": "DEPRECATED — use put_menu_item / menu API. Menu link text for <dotsy-nav> (separate from title). Still accepted during transition and synced to menu items."
    },
    "nav": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "menu": {
            "type": "string",
            "minLength": 1,
            "description": "Menu this page joins — matches a <dotsy-nav menu=\"…\"> in the layout/fragment (e.g. \"primary\", \"footer\")."
          },
          "order": {
            "type": "integer",
            "description": "Sort position among siblings in this menu, ascending. Use gaps (10, 20, 30) to leave room for inserts."
          },
          "parent": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent route path within this menu for a nested/dropdown item (e.g. \"/services\"). Omit for top level."
          }
        },
        "required": [
          "menu"
        ]
      },
      "description": "DEPRECATED — use put_menu_item / menu API. Menu memberships on the route row. Still accepted during transition and synced to menu items. See get_skill('nav')."
    },
    "experiment": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9-]+$",
          "description": "Stable experiment slug — cookie namespace; unique per site forever."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "hypothesis": {
          "type": "string",
          "maxLength": 200
        },
        "status": {
          "type": "string",
          "enum": [
            "draft",
            "running",
            "ended"
          ]
        },
        "variants": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9-]+$",
                "description": "Variant arm id — default \"a\" / \"b\" on create."
              },
              "label": {
                "type": "string",
                "maxLength": 80
              },
              "weight": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "contentKey": {
                "type": "string",
                "minLength": 1,
                "description": "Published body key (may be routeless)."
              }
            },
            "required": [
              "id",
              "weight",
              "contentKey"
            ]
          },
          "minItems": 2,
          "maxItems": 3
        },
        "goalId": {
          "type": "string",
          "minLength": 1,
          "description": "Optional dotsy conversion goal; omit when tracking in external analytics."
        },
        "changeNote": {
          "type": "string",
          "maxLength": 120,
          "description": "One line on what the variant changes (0.56e M2). Kept here so route PATCH round-trips (weights/settings updates) don't strip it."
        },
        "handsOff": {
          "type": "boolean",
          "description": "Hands-off mode (0.56e M4): the daily sweep may auto-promote a ≥95% winner or auto-end keep-A after 30 days. Prefer setting this via start_test; kept here so route PATCH round-trips (weights/settings updates) don't strip the flag."
        },
        "startedAt": {
          "type": "string"
        },
        "endedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "status",
        "variants"
      ]
    },
    "noindex": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Exclude from sitemap/RSS; inject noindex meta (0.69)."
    }
  }
}