{
  "Protocol": "AIXE",
  "Version": "3.03",
  "ProtocolReference": {
    "ProtocolHome": "http://aixeprotocol.com/",
    "CanonicalUsageContract": "http://aixeprotocol.com/usage/?",
    "Whitepaper": "http://aixeprotocol.com/whitepaper/full-spec.html",
    "Inventor": "Gregory Oglethorpe"
  },
  "Endpoint": "/aixe/list-items/create-item/",
  "Title": "Add A List Item",
  "Purpose": "Add an item to an owned or shared list, optionally including quantity, unit, notes, and display order.",
  "Method": "POST",
  "ContentType": "application/json",
  "AccessType": "Authenticated",
  "DiscoveryRequest": "GET /aixe/list-items/create-item/?",
  "AIXEContractVersionKey": "92c7d614-74df-4b05-8960-a5ffeeca31d8",
  "DiscoveryFreshness": {
    "Required": true,
    "Rule": "Reload discovery immediately before execution and rebuild the request from its current fields and rules."
  },
  "RequiredFields": {
    "AIXEContractVersionKey": {
      "Type": "string",
      "Description": "Copy this contract\u0027s current version key after fresh discovery; never ask the human for it.",
      "SubmittedIn": "JSON body"
    },
    "PersonAuthenticationToken": {
      "Type": "string",
      "Description": "The active, unexpired 64-character token from /aixe/account/login/. Use HTTPS and keep tokens out of URLs, displayed output, and logs.",
      "SubmittedIn": "JSON body"
    },
    "ListKey": {
      "Type": "UUID string",
      "Description": "Public key of an owned or shared list, obtained from /aixe/lists/list-lists/. For move-item this is the source list.",
      "SubmittedIn": "JSON body"
    },
    "ListItemName": {
      "Type": "string",
      "Description": "Item name, 1\u2013200 characters after trimming. Duplicate names are allowed; use the returned public key to distinguish items.",
      "SubmittedIn": "JSON body"
    }
  },
  "OptionalFields": {
    "ListItemNotes": {
      "Type": "string",
      "Description": "Optional notes, up to 2000 trimmed characters. Empty string clears notes; omit or null preserves existing notes on update.",
      "SubmittedIn": "JSON body"
    },
    "ListItemQuantity": {
      "Type": "number or null",
      "Description": "Optional positive decimal, maximum 99999999999999.9999, at most four decimal places. Explicit null clears quantity; omission preserves it on update. No automatic measurement conversion is performed.",
      "SubmittedIn": "JSON body"
    },
    "ListItemUnit": {
      "Type": "string",
      "Description": "Optional free-form unit such as lb, cans, or each; up to 50 trimmed characters. Empty string clears it; omit or null preserves it on update.",
      "SubmittedIn": "JSON body"
    },
    "ListItemIsChecked": {
      "Type": "boolean",
      "Description": "Explicit checked state. Defaults to false; true requires a checkable list.",
      "SubmittedIn": "JSON body"
    },
    "ListItemSortOrder": {
      "Type": "integer",
      "Description": "Nonnegative display position; lower values first. Defaults to 0.",
      "SubmittedIn": "JSON body"
    }
  },
  "BusinessRules": [
    "Both Admin and Contributor members can create, read, edit, check, move, and remove items. Only the Admin can change list settings, share the list, or delete the whole list.",
    "Public keys identify records; they grant no access. Never supply internal numeric IDs or nominate a role or acting person.",
    "ListIsCheckable belongs to the list. When false, show all items without checkboxes or checked grouping. Stored item check states remain intact and become usable if the owner enables the flag again.",
    "Checkmark updates, checked-state filtering, clearing checked items, and resetting checkmarks require ListIsCheckable = true. Creating an unchecked item remains allowed in ordinary lists.",
    "Load discovery before every action. Submit all inputs in the application/json POST body, never as query parameters.",
    "The new item and its List-to-ListItem Linker with role Item are saved together. Check state defaults to false and sort order to 0. A true initial check state records the current UTC time."
  ],
  "ActionResponse": {
    "RequiredResponseFields": [
      "SuccessCode"
    ],
    "SuccessCodes": [
      "SUCCESS"
    ],
    "Fields": {
      "ItemCreated": "True after creation committed.",
      "ListKey": "Containing list.",
      "Item": "ListItemKey, ListItemName, nullable ListItemNotes, nullable ListItemQuantity, nullable ListItemUnit, ListItemIsChecked, nullable ListItemCheckedDate (UTC), ListItemSortOrder, and CreationDate (UTC). Internal numeric IDs are never returned."
    },
    "OutcomeRule": "Only SuccessCode = SUCCESS means completion. HTTP 200 alone, an empty response, or a missing SuccessCode is not success."
  },
  "Errors": [
    {
      "SuccessCode": "VALIDATION_FAILED",
      "Meaning": "Missing, malformed, or out-of-range input.",
      "Recovery": "Correct the fields according to discovery and Message."
    },
    {
      "SuccessCode": "DISCOVERY_REFRESH_REQUIRED",
      "Meaning": "Missing or stale contract version.",
      "Recovery": "Reload discovery and rebuild the request."
    },
    {
      "SuccessCode": "UNAUTHORIZED",
      "Meaning": "Invalid/expired authentication or inactive account.",
      "Recovery": "Log in again and use the new token."
    },
    {
      "SuccessCode": "NOT_FOUND",
      "Meaning": "Absent/inaccessible list, item not in the supplied list, inaccessible destination, or inactive capability.",
      "Recovery": "Reload available lists/items or the manifest and select the correct public keys."
    },
    {
      "SuccessCode": "BUSINESS_RULE_FAILED",
      "Meaning": "Checkmarks disabled or a concurrent change prevented completion.",
      "Recovery": "For checkmarks, ask the owner to enable ListIsCheckable if desired. For concurrency, read current state before retrying."
    },
    {
      "SuccessCode": "FAILED",
      "Meaning": "Unexpected failure; completion is uncertain.",
      "Recovery": "Read current state before retrying, especially after creation or movement."
    }
  ]
}