{
  "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/lists/create-list/",
  "Title": "Create A List",
  "Purpose": "Create a personal list, such as Shopping List, HEB, or Costco. The authenticated creator becomes its sole Admin and can manage settings, share access, or delete it.",
  "Method": "POST",
  "ContentType": "application/json",
  "AccessType": "Authenticated",
  "DiscoveryRequest": "GET /aixe/lists/create-list/?",
  "AIXEContractVersionKey": "dd605ae7-acaa-42cf-9b25-6bba725f68b2",
  "DiscoveryFreshness": {
    "Required": true,
    "Rule": "Reload this contract before every action and rebuild the request from its current fields and rules."
  },
  "RequiredFields": {
    "AIXEContractVersionKey": {
      "Type": "string",
      "Description": "Copy the version key from this freshly loaded contract. It is supplied by discovery, never requested from the human.",
      "Required": true,
      "SubmittedIn": "JSON body"
    },
    "PersonAuthenticationToken": {
      "Type": "string",
      "Description": "The 64-character temporary secret returned by /aixe/account/login/. Must belong to an active account and be unexpired. Submit over HTTPS; never put it in URLs, chat output, or logs.",
      "Required": true,
      "SubmittedIn": "JSON body"
    },
    "ListName": {
      "Type": "string",
      "Description": "Human-chosen list name, 1\u2013200 characters after trimming. Names need not be unique; use the returned ListKey to identify the list.",
      "Required": true,
      "SubmittedIn": "JSON body"
    }
  },
  "OptionalFields": {
    "ListDescription": {
      "Type": "string",
      "Description": "Optional purpose or notes, up to 2000 characters after trimming. Blank becomes empty.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "ListIsCheckable": {
      "Type": "boolean",
      "Description": "Whether this list supports checking items off. Defaults to true.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "ListSortOrder": {
      "Type": "integer",
      "Description": "Nonnegative display position among lists; lower values appear first. Defaults to 0.",
      "Required": false,
      "SubmittedIn": "JSON body"
    }
  },
  "BusinessRules": [
    "Act for the authenticated person. A public PersonKey or ListKey alone grants no access.",
    "Every list has one owner with Admin rights. Contributors can read shared lists but cannot rename them, change list settings, delete them, or share them onward.",
    "Sharing takes effect immediately, with no invitation or acceptance step and no email notification.",
    "Admins and Contributors manage list contents through /aixe/list-items/ capabilities discovered in /aixe.ai. get-list returns settings; use list-items to read contents.",
    "Reload discovery immediately before use. Submit the current AIXEContractVersionKey and all business values in the POST JSON body.",
    "Creation saves the list and its owner access together. The caller cannot nominate another owner or supply a role."
  ],
  "ActionResponse": {
    "RequiredResponseFields": [
      "SuccessCode"
    ],
    "SuccessCodes": [
      "SUCCESS"
    ],
    "Fields": {
      "ListCreated": "True when creation committed.",
      "List": "ListKey, ListName, ListDescription, ListIsCheckable, ListSortOrder, CreationDate (UTC), and AccessRole = Admin. Store the public ListKey for subsequent actions."
    },
    "OutcomeRule": "Only SuccessCode = SUCCESS means completion. HTTP 200 alone is not success. Missing or empty responses are failed or uncertain."
  },
  "Errors": [
    {
      "SuccessCode": "VALIDATION_FAILED",
      "Meaning": "An input is missing, malformed, or outside the declared limits.",
      "Recovery": "Correct the input using this contract and the returned Message and Field."
    },
    {
      "SuccessCode": "DISCOVERY_REFRESH_REQUIRED",
      "Meaning": "Missing or stale contract version.",
      "Recovery": "Reload discovery and rebuild the request; the failure does not supply the new key."
    },
    {
      "SuccessCode": "UNAUTHORIZED",
      "Meaning": "Missing, invalid, or expired authentication, or inactive account.",
      "Recovery": "Log in and use the new PersonAuthenticationToken."
    },
    {
      "SuccessCode": "FORBIDDEN",
      "Meaning": "You can see this list but lack its Admin role for the requested action.",
      "Recovery": "Have the list owner perform the action. Do not submit another person\u0027s key or invent a role."
    },
    {
      "SuccessCode": "NOT_FOUND",
      "Meaning": "The list is absent or inaccessible; for sharing, the recipient may have no active account. A capability may also be inactive.",
      "Recovery": "Follow Message: select a list from list-lists, check the registered recipient email, or reload /aixe.ai."
    },
    {
      "SuccessCode": "BUSINESS_RULE_FAILED",
      "Meaning": "Sharing with the owner, or a concurrent change prevented the action.",
      "Recovery": "The owner already has Admin access. For concurrency, read current state and retry if the action is still needed."
    },
    {
      "SuccessCode": "FAILED",
      "Meaning": "Unexpected failure; do not infer completion.",
      "Recovery": "Read current state before retrying a mutation, particularly creation."
    }
  ]
}