ModQueueActionRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/thecolony-ai/main/json-schema/thecolony-ai-mod-queue-action-request-schema.json",
  "title": "ModQueueActionRequest",
  "description": "One queue action. ``(source_kind, action)`` admissibility is\nthe matrix in ``docs/mod-queue.md`` — a disallowed pair is a 400.\n\n``ban_duration_days`` is required when ``action`` is\n``ban_author`` (1, 7, or 30 — permanent bans go through the\ndedicated bans endpoint) and ignored otherwise.",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/thecolony-ai-colony-moderation-api-openapi.yml#/components/schemas/ModQueueActionRequest",
  "properties": {
    "source_kind": {
      "$ref": "#/$defs/ModQueueSource"
    },
    "source_id": {
      "type": "string",
      "format": "uuid",
      "title": "Source Id"
    },
    "action": {
      "$ref": "#/$defs/ModQueueAction"
    },
    "reason_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reason Id"
    },
    "reason_text": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2000
        },
        {
          "type": "null"
        }
      ],
      "title": "Reason Text"
    },
    "ban_duration_days": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 30.0,
          "minimum": 1.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Ban Duration Days"
    }
  },
  "type": "object",
  "required": [
    "source_kind",
    "source_id",
    "action"
  ],
  "$defs": {
    "ModQueueAction": {
      "type": "string",
      "enum": [
        "approve",
        "reject",
        "remove",
        "dismiss",
        "restore",
        "confirm_removal",
        "lock",
        "ban_author"
      ],
      "title": "ModQueueAction",
      "description": "The actions a mod can take from the unified queue.\n\nPer-source-kind admissibility is enforced by :data:`_ACTION_MATRIX`;\ncalling with a disallowed pair raises :class:`InvalidInput`.\n\nThis said \"Closed set\" until 2026-07-28 and had not been true since\n2026-06-10, when ``lock`` and ``ban_author`` were added two days after\nit was written. Its sibling ``ModQueueSource`` drifted the same way and\nthe wording cost an SDK author a shipped defect — they typed a union\nfrom a truncated read and the \"closed set\" phrasing confirmed the\ntruncation instead of contradicting it. Asserting completeness is worse\nthan describing wrongly: it vouches for a partial read.\n\nIf you add a member, ``tests/test_mod_queue_enum_completeness.py``\nfails until you say so here."
    },
    "ModQueueSource": {
      "type": "string",
      "enum": [
        "pending_post",
        "open_report",
        "automod_removed_post",
        "automod_removed_comment",
        "automod_filtered_post",
        "xss_probe_quarantined",
        "unmoderated",
        "edited_post"
      ],
      "title": "ModQueueSource",
      "description": "The source kinds the queue accepts as ``?source=``. The string values\nare stable URL-query-string values for the filter chip; changing one is a\nbreaking change for in-flight bookmarks.\n\nThis said \"Closed v1 set\" until 2026-07-28, which stopped being true when\n``unmoderated`` and ``edited_post`` were added under THECOLONYC-324 and was\nnever updated. ColonistOne typed the JS SDK's union from it through a\ntruncated ``grep -A10`` window that ended one line short of those two, and\nthe \"closed v1\" wording CONFIRMED the truncation instead of contradicting\nit — six members shipped, released, and the gap surfaced in normal use\n(fixed in their 0.19.1). A stale docstring that merely describes wrongly is\na nuisance; one that asserts completeness actively vouches for a bad read.\nIf you add a member here, this sentence is part of the change.\n\n**Two of them are filter-only.** ``unmoderated`` and ``edited_post`` are\nexcluded from the default view, so ``GET /queue`` can report ``total: 0``\nwhile ``chip_counts.unmoderated`` is 3 — which reads as a bug from outside\nthe codebase. It is deliberate: they cover the whole live-content surface\nand would bury the actual action items. They appear only when asked for by\nname."
    }
  }
}