{
  "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/share-list/",
  "Title": "Share A List",
  "Purpose": "Give another existing MmmmGood account immediate Contributor access to a list you own. Supply their registered email address. No acceptance, invitation, or email sending is involved.",
  "Method": "POST",
  "ContentType": "application/json",
  "AccessType": "Authenticated",
  "DiscoveryRequest": "GET /aixe/lists/share-list/?",
  "AIXEContractVersionKey": "e940cd77-aed3-458b-9dd5-0b68c2f41780",
  "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"
    },
    "ListKey": {
      "Type": "UUID string",
      "Description": "The public key returned by create-list or list-lists. Select the intended list by this key, never by an internal numeric identifier.",
      "Required": true,
      "SubmittedIn": "JSON body"
    },
    "Email": {
      "Type": "string",
      "Description": "The recipient\u0027s registered email address; valid syntax, up to 254 characters. Whitespace is trimmed and matching ignores case. Must resolve to an active MmmmGood account.",
      "Required": true,
      "SubmittedIn": "JSON body"
    }
  },
  "OptionalFields": {},
  "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.",
    "Only the list owner with Admin access can share it. A Contributor cannot share it onward.",
    "Recipients receive Contributor access only. The caller cannot choose a role or grant Admin access.",
    "Sharing with an existing Contributor is a successful no-op with AlreadyShared = true; no duplicate membership is created.",
    "Sharing with the owner returns BUSINESS_RULE_FAILED and preserves their Admin access.",
    "An unknown or inactive email returns NOT_FOUND without creating an account, pending invitation, or membership."
  ],
  "ActionResponse": {
    "RequiredResponseFields": [
      "SuccessCode"
    ],
    "SuccessCodes": [
      "SUCCESS"
    ],
    "Fields": {
      "ListShared": "True when Contributor access exists.",
      "AlreadyShared": "True if access already existed; false if it was just added.",
      "ListKey": "Shared list public key.",
      "SharedWithPersonKey": "Recipient public key.",
      "Email": "Recipient\u0027s registered email.",
      "AccessRole": "Always Contributor."
    },
    "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."
    }
  ]
}