{
  "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/suggestions/submit-suggestion/",
  "Title": "Submit Suggestion",
  "Purpose": "Submit a suggestion for MmmmGood. Anyone may submit without an account, signup, login, or authentication token.",
  "Method": "POST",
  "ContentType": "application/json",
  "AccessType": "Public",
  "DiscoveryRequest": "GET /aixe/suggestions/submit-suggestion/?",
  "AIXEContractVersionKey": "c3b7d613-d571-4273-ae34-1d45d6158d1e",
  "DiscoveryFreshness": {
    "Required": true,
    "Rule": "Read this discovery immediately before executing; send its current version key in the JSON body."
  },
  "RequiredFields": {
    "AIXEContractVersionKey": {
      "Type": "string",
      "Description": "Copy the current version key from this live contract immediately before execution; do not ask the person for it.",
      "Required": true,
      "SubmittedIn": "JSON body"
    },
    "SuggestionDescription": {
      "Type": "string",
      "Description": "Short suggestion title, 1-200 trimmed characters.",
      "Required": true,
      "SubmittedIn": "JSON body"
    },
    "SuggestionBody": {
      "Type": "string",
      "Description": "Full suggestion text, 1-100000 trimmed characters.",
      "Required": true,
      "SubmittedIn": "JSON body"
    }
  },
  "OptionalFields": {
    "SuggestionPhoneNumber": {
      "Type": "string or null",
      "Description": "Optional contact phone number, at most 30 trimmed characters. Omit, null, or blank to leave empty.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "SuggestionEmailAddress": {
      "Type": "string or null",
      "Description": "Optional contact email address, at most 254 trimmed characters. Omit, null, or blank to leave empty.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "SuggestionPersonKey": {
      "Type": "string or null",
      "Description": "Optional nonempty UUID identifying a person. Omit or null if unknown. Stored for a future join without checking account existence or authenticating identity; never invent a key or require login to obtain one.",
      "Required": false,
      "SubmittedIn": "JSON body"
    }
  },
  "BusinessRules": [
    "Submit every input in an application/json POST body over HTTPS. Query parameters are rejected. Public keys identify records but grant no access.",
    "Read live discovery immediately before each action. Only SuccessCode SUCCESS means completion; missing or empty responses mean failure or uncertainty.",
    "Never display or log PINs, password hashes, or authentication tokens. Unknown JSON properties are ignored; use only documented fields.",
    "Collect the person\u0027s suggestion and submit it yourself through this API. No customer account or credentials are required. AIXEContractVersionKey is public protocol metadata, not a credential. Contact details and person key are entirely optional; ask only if the person wants to supply them.",
    "Creates one Suggestion record. Optional contact details are stored as supplied after trimming; they are not verified and no email or text is sent. A supplied person key grants no account access or authenticated attribution. This endpoint does not list suggestions or expose other submissions.",
    "Only SUCCESS confirms submission. Each successful call creates a new suggestion; do not automatically retry after a timeout or uncertain response because that could create a duplicate."
  ],
  "AuthenticationSession": "None. This endpoint is public and requires no login or authentication token.",
  "InteractionGuidance": "Ask for a short title and the suggestion itself. Submit through this endpoint; no human form or login is needed. Do not require optional contact details or a person key. Keep any supplied contact details out of URLs and avoid echoing them unnecessarily.",
  "ActionResponse": {
    "RequiredResponseFields": [
      "SuccessCode"
    ],
    "SuccessCodes": [
      "SUCCESS"
    ],
    "Fields": "SuggestionSubmitted=true and SuggestionKey (public UUID). Numeric IDs and contact details are not returned.",
    "MissingOrEmptyResponse": "Treat as failed or uncertain; read current state before retrying a mutation."
  },
  "Errors": [
    {
      "SuccessCode": "VALIDATION_FAILED",
      "Meaning": "A request field is missing, has the wrong type, or is out of range.",
      "Recovery": "Read Field and Message; correct that exact field using this contract. Boolean fields accept true or false only."
    },
    {
      "SuccessCode": "DISCOVERY_REFRESH_REQUIRED",
      "Meaning": "The contract version is absent or stale.",
      "Recovery": "Read this live discovery again and rebuild the request."
    },
    {
      "SuccessCode": "NOT_FOUND",
      "Meaning": "The capability is inactive or the selected record does not exist within your authorized account/list.",
      "Recovery": "Use the manifest and your own list/search results to select a current public key."
    },
    {
      "SuccessCode": "BUSINESS_RULE_FAILED",
      "Meaning": "PhoneNumber already belongs to an account, or a duplicate/concurrent change prevented completion.",
      "Recovery": "For PhoneNumber follow the field-specific message. Otherwise read current state before retrying."
    },
    {
      "SuccessCode": "FAILED",
      "Meaning": "An unexpected failure prevented normal completion.",
      "Recovery": "Read current state before retrying; never infer success from HTTP status alone."
    }
  ]
}