@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api KumpeApps API
@base https://restapi.kumpeapps.com/v5
@version 5.0.0
@auth ApiKey X-Auth in header | ApiKey X-Auth in header
@endpoints 33
@hint download_for_search
@toc appkey(3), authkey(4), authentication(8), kkid(18)

@group appkey
@endpoint PUT /appkey
@desc Deactivate app key
@required {app_key: str # app key to deactivate}
@returns(202) {success: bool} # App key deactivated

@endpoint POST /appkey
@desc Request app key
@required {username: str # Username assigned to your app, password: str(password) # Password assigned to your app, supportsYubikey: bool # App supports YubiKey OTP}
@returns(201) {success: bool, app_key: str} # app key created

@endpoint PATCH /appkey
@desc Compromise app key
@required {app_key: str # compromised app key}
@optional {comments: str # Comments (like how was this compromised)}
@returns(202) {success: bool} # App key deactivated

@endgroup

@group authkey
@endpoint GET /authkey
@desc Request auth key for user (login user)
@required {username: str # Authenticated username, password: str(password) # Authenticated password}
@optional {otp: str(password) # YubiKey OTP (if configured for user)}
@returns(200) {success: bool, auth_key: str} # User Authenticated Sucessfully
@errors {401: Invalid/Locked/Blocked/Compromised AppKey, 403: Access Denied, 449: OTP required but not supplied. Please resubmit request with OTP}

@endpoint PUT /authkey
@desc Deactivate auth key (logout)
@required {auth_key: str(password) # auth key to logout}
@returns(202) {success: bool} # Success
@errors {401: Invalid/Locked/Blocked/Compromised AppKey}

@endpoint POST /authkey
@desc Request auth key for user (login user)
@required {username: str # Authenticated username, password: str(password) # Authenticated password}
@optional {otp: str(password) # YubiKey OTP (if configured for user)}
@returns(200) {success: bool, auth_key: str} # User Authenticated Sucessfully
@errors {401: Invalid/Locked/Blocked/Compromised AppKey, 403: Access Denied, 449: OTP required but not supplied. Please resubmit request with OTP}

@endpoint PATCH /authkey
@desc Compromise auth key
@required {auth_key: str(password) # auth key to mark as compromised}
@optional {comments: str # Comments (like how was this compromised)}
@returns(202) {success: bool} # Auth key marked as compromised and locked
@errors {401: Invalid/Locked/Blocked/Compromised AppKey}

@endgroup

@group authentication
@endpoint PUT /authentication/appkey
@desc Deactivate app key
@required {app_key: str # app key to deactivate}
@returns(202) {success: bool} # App key deactivated

@endpoint POST /authentication/appkey
@desc Request app key
@required {username: str # Username assigned to your app, password: str(password) # Password assigned to your app, supportsYubikey: bool # App supports YubiKey OTP}
@returns(201) {success: bool, app_key: str} # app key created

@endpoint PATCH /authentication/appkey
@desc Compromise app key
@required {app_key: str # compromised app key}
@optional {comments: str # Comments (like how was this compromised)}
@returns(202) {success: bool} # App key deactivated

@endpoint GET /authentication/verifyotp
@desc Verifies YubiKey OTP for authenticated user
@required {otp: str # YubiKey OTP code}
@returns(200) User Authenticated Sucessfully
@errors {401: Invalid/Locked/Blocked/Compromised AppKey/AuthKey, 403: Access Denied}

@endpoint GET /authentication/authkey
@desc Request auth key for user (login user)
@required {username: str # Authenticated username, password: str(password) # Authenticated password}
@optional {otp: str(password) # YubiKey OTP (if configured for user), deviceName: str # User's device name, identifierForVendor: str # identifierForVendor for User's Device (if app is iOS)}
@returns(200) {success: bool, auth_key: str} # User Authenticated Sucessfully
@errors {401: Invalid/Locked/Blocked/Compromised AppKey, 403: Access Denied, 449: OTP required but not supplied. Please resubmit request with OTP}

@endpoint PUT /authentication/authkey
@desc Deactivate auth key (logout)
@required {auth_key: str(password) # auth key to logout}
@returns(202) {success: bool} # Success
@errors {401: Invalid/Locked/Blocked/Compromised AppKey}

@endpoint POST /authentication/authkey
@desc Request auth key for user (login user)
@required {username: str # Authenticated username, password: str(password) # Authenticated password}
@optional {otp: str(password) # YubiKey OTP (if configured for user)}
@returns(200) {success: bool, auth_key: str} # User Authenticated Sucessfully
@errors {401: Invalid/Locked/Blocked/Compromised AppKey, 403: Access Denied, 449: OTP required but not supplied. Please resubmit request with OTP}

@endpoint PATCH /authentication/authkey
@desc Compromise auth key
@required {auth_key: str(password) # auth key to mark as compromised}
@optional {comments: str # Comments (like how was this compromised)}
@returns(202) {success: bool} # Auth key marked as compromised and locked
@errors {401: Invalid/Locked/Blocked/Compromised AppKey}

@endgroup

@group kkid
@endpoint POST /kkid/masteruser
@desc adds new master user account
@required {username: str # username of user to create, password: str(password) # password of user to create, email: str # email address of user to create, firstName: str # First Name of user to create, lastName: str # Last Name of user to create}
@returns(200) {user_id: int, login: str, pass: str, remember_key: str, pass_dattm: str, email: str, name_f: str, name_l: str, street: str, street2: str, city: str, state: str, zip: str, country: str, phone: str, added: str, remote_addr: str, user_agent: str, saved_form_id: str, status: str, unsubscribed: str, lang: str, i_agree: str, is_locked: str, disable_lock_until: str, reseller_id: str, comment: str, tax_id: str, last_login: str, aff_id: str, aff_added: str, is_affiliate: str, aff_payout_type: str, plain_password: str, pin: str, require_consent: str, subusers_parent_id: str, avatar: str} # User Added
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@errors {405: Method Not Allowed- API user does not have access to use this method, 409: Create user unsuccessful! This is normally because the username or password already exists in the KumpeApps system.}

@endpoint GET /kkid/user
@desc Gets user info
@optional {enableBool: bool # Use bool values instead of Int 0/1}
@returns(200) {success: bool, user: [map]} # search results matching criteria

@endpoint GET /kkid/userlist
@desc returns list of users
@optional {isChild: bool # Filter Search by isChild flag, isActive: bool # Filter Search by isActive flag, isAdmin: bool # Filter Search by isAdmin flag, enableAllowance: bool # Filter Search by enableAllowance flag, enableChores: bool # Filter Search by enableChores flag, userID: int # userID of user to search, username: str # Username of user to search, email: str # Email address of user to search}
@returns(200) {success: bool, user: [map]} # search results matching criteria
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@returns(204) {status: int, error: str} # No Data Returned
@errors {400: bad input parameter, 401: Unauthorized- API credentials not supplied. Ensure you have passed proper Username and Password parameters, 403: Forbidden- User access is denied. API user either does not have access or has been banned/locked., 405: Method Not Allowed- API user does not have access to use this method, 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint PUT /kkid/userlist
@desc updates user
@required {userID: int # userID of the user you wish to update, username: str # username of user to create, email: str # email address of user to create, firstName: str # First Name of user to create, lastName: str # Last Name of user to create}
@optional {emoji: str # emoji character for user, tmdbKey: str # User's TMdB Session Key, enableWishList: bool # set status of Wish List module enabled, enableChores: bool # set status of chores module enabled, enableAllowance: bool # set status of allowance module enabled, enableAdmin: bool # set status of isAdmin, enableTmdb: bool # set status of enableTmdb (movie and tv search), enableObjectDetection: bool # set status of enableObjectDetection}
@returns(200) {user_id: int, login: str, pass: str, remember_key: str, pass_dattm: str, email: str, name_f: str, name_l: str, street: str, street2: str, city: str, state: str, zip: str, country: str, phone: str, added: str, remote_addr: str, user_agent: str, saved_form_id: str, status: str, unsubscribed: str, lang: str, i_agree: str, is_locked: str, disable_lock_until: str, reseller_id: str, comment: str, tax_id: str, last_login: str, aff_id: str, aff_added: str, is_affiliate: str, aff_payout_type: str, plain_password: str, pin: str, require_consent: str, subusers_parent_id: str, avatar: str} # User Updated
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@errors {405: Method Not Allowed- API user does not have access to use this method, 409: Update user unsuccessful. This could be due to invalid userID, new username already exists, new email already exists, or an unknown error., 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint POST /kkid/userlist
@desc adds new child user
@required {username: str # username of user to create, password: str(password) # password of user to create, email: str # email address of user to create, firstName: str # First Name of user to create, lastName: str # Last Name of user to create}
@returns(200) {user_id: int, login: str, pass: str, remember_key: str, pass_dattm: str, email: str, name_f: str, name_l: str, street: str, street2: str, city: str, state: str, zip: str, country: str, phone: str, added: str, remote_addr: str, user_agent: str, saved_form_id: str, status: str, unsubscribed: str, lang: str, i_agree: str, is_locked: str, disable_lock_until: str, reseller_id: str, comment: str, tax_id: str, last_login: str, aff_id: str, aff_added: str, is_affiliate: str, aff_payout_type: str, plain_password: str, pin: str, require_consent: str, subusers_parent_id: str, avatar: str} # User Added
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@errors {405: Method Not Allowed- API user does not have access to use this method, 409: Create user unsuccessful! This is normally because the username or password already exists in the KumpeApps system., 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint DELETE /kkid/userlist
@desc deletes user
@required {userID: int # userID of the user you wish to delete}
@returns(200) User Deleted
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@errors {405: Method Not Allowed- API user does not have access to use this method, 409: Create user unsuccessful! This is normally because the username or password already exists in the KumpeApps system., 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint GET /kkid/chorelist
@desc returns list of chores for given user
@optional {kidUsername: str # Username of kid you wish to search, day: str(Sunday/Monday/Tuesday/Wednesday/Thursday/Friday/Saturday/Weekly) # Day of week for chores (Weekly for weekly chores), status: str # Status of Chore to search, blockDash: bool # Filter results by blockDash parameter, optional: bool # Filter results by optional parameter, canSteal: bool # Filter results by canSteal parameter, includeCalendar: bool # include calendar notations (default is false)}
@returns(200) {success: int, chore: [map]} # search results matching criteria
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@returns(206) {status: int, error: str} # No Data Found.
@errors {400: bad input parameter, 401: Unauthorized- API credentials not supplied. Ensure you have passed proper Username and Password parameters, 403: Forbidden- User access is denied. API user either does not have access or has been banned/locked., 405: Method Not Allowed- API user does not have access to use this method, 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint PUT /kkid/chorelist
@desc updates chore for given chore id
@required {idChoreList: int # id number of chore you wish to update}
@optional {status: str # new status of chore, stolen: bool # mark chore as stolen by sibling, stolenBy: str # username of sibling that stole the chore (required if stolen is true), nfcTag: str # text field of NFC tag that is required to be scanned to check off this chore (normally null), notes: str # notes field for chore, latitude: int # GPS latitude of where the chore was marked, longitude: int # GPS longitude of where the chore was marked, altitude: int # GPS altitude of where the chore was marked, updatedByAutomation: bool # true if updated via API by automation system, whereDay: str(Sunday/Monday/Tuesday/Wednesday/Thursday/Friday/Saturday/Weekly/Today) # Where day equals..., whereStatus: str # Where status equals..., whereName: str # Where chore name equals...}
@returns(200) {success: bool, message: str} # search results matching criteria
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@returns(206) {status: int, error: str} # No Data Found.
@errors {400: bad input parameter, 401: Unauthorized- API credentials not supplied. Ensure you have passed proper Username and Password parameters, 403: Forbidden- User access is denied. API user either does not have access or has been banned/locked., 405: Method Not Allowed- API user does not have access to use this method, 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint POST /kkid/chorelist
@desc adds chore for given user
@required {kidUsername: str # username of kid to assign the chore to., choreName: str # name of chore}
@optional {day: str(Sunday/Monday/Tuesday/Wednesday/Thursday/Friday/Saturday/Weekly/Today) # day of week (Monday, Tuesday....) for the chore. For weekly chores put Weekly or leave blank, nfcTag: str # text field of nfc tag required to check off chore, status: str # status of chore (default is todo), choreDescription: str # optional chore description, choreNumber: int # number priority of chore (default is 5), blockDash: bool # block dash option on this chore, oneTime: bool # mark as one time chore (does not repeat each week), extraAllowance: int # ammount of allowance added at end of week for completing this chore, optional: bool # mark as optional chore, reassignable: bool # mark as reassignable (default is true), canSteal: bool # mark as sibling can steal chore, startDate: str # date (yyyy-mm-dd) that you wish the chore to start showing up. (default is today), notes: str # notes added to chore (visable only on reports, kids do not see this note, this is mostly just for the developer), requireObjectDetection: bool # require use of camera to detect object detection tag order to check off chore, objectDetectionTag: str # tag for object detection to search for (required if requireObjectDetection is true), updatedByAutomation: bool # true if chore updated via API from an Automation System, aiIcon: str # Notes if AI Icons should be used (n for no, y for yes, e for yes- error), isCalendar: bool # True if this is a calendar note instead of a chore.}
@returns(200) {success: bool, message: str} # search results matching criteria
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@returns(206) {status: int, error: str} # No Data Found.
@errors {400: bad input parameter, 401: Unauthorized- API credentials not supplied. Ensure you have passed proper Username and Password parameters, 403: Forbidden- User access is denied. API user either does not have access or has been banned/locked., 405: Method Not Allowed- API user does not have access to use this method, 409: Conflict- idChoreList parameter was not supplied or is blank, 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint DELETE /kkid/chorelist
@desc deletes chore for given chore id
@required {idChoreList: int # id of the chore you wish to delete}
@returns(200) {success: bool, message: str} # deletion successful
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@returns(206) {status: int, error: str} # No Data Found.
@errors {400: bad input parameter, 401: Unauthorized- API credentials not supplied. Ensure you have passed proper Username and Password parameters, 403: Forbidden- User access is denied. API user either does not have access or has been banned/locked., 405: Method Not Allowed- API user does not have access to use this method, 409: Conflict- idChoreList parameter was not supplied or is blank, 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint GET /kkid/allowance
@desc returns allowance balance and allowance transactions
@required {kidUserId: int # userID of the kid}
@optional {transactionDays: int # number of days you wish to search allowance transactions (default is 90 days)}
@returns(200) {success: int, id: int, balance: int, lastUpdated: str, allowanceTransaction: [map]} # search results matching criteria
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@returns(206) {status: int, error: str} # No Data Returned
@errors {400: bad input parameter, 401: Unauthorized- API credentials not supplied. Ensure you have passed proper Username and Password parameters, 403: Forbidden- User access is denied. API user either does not have access or has been banned/locked., 405: Method Not Allowed- API user does not have access to use this method, 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint POST /kkid/allowance
@desc adds new allowance transaction to kidUserID
@required {kidUserId: int # userID of the kid, amount: num # amount you wish to Add/Subtract (subtract value should be a negative value), description: str # Description (reason) of allowance transaction, transactionType: str(Add/Subtract) # Transaction Type (Add/Subtract)}
@returns(200) {success: bool, message: str} # search results matching criteria
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@returns(206) {status: int, error: str} # No Data Returned
@errors {400: bad input parameter, 401: Unauthorized- API credentials not supplied. Ensure you have passed proper Username and Password parameters, 403: Forbidden- User access is denied. API user either does not have access or has been banned/locked., 405: Method Not Allowed- API user does not have access to use this method, 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint POST /kkid/apns
@desc subscribes/unsubscribes/registers for apns push notifications
@required {kidUserId: int # userID of the kid, tool: str(register/subscribe/unsubscribe/send) # tool you wish to talk to}
@optional {token: str # device APNS token (required for register), devicename: str # Name of device to associate to token (required for register), title: str # title of APNS message (required for send), message: str # APNS message body (required for send), badge: int # Number for badge icon (optional for send), sound: str # Name of sound file to play for send notification (optional for send), section: str(Chores/Chores-New/Chores-Reminders/Allowance/Allowance-New/WishList) # Notification section name (required for send/subscribe/unsubscribe), priority: str(passive/active/time-sensitive/critical) # Notification section name (optional for send, default is active)}
@returns(200) {success: bool, message: str} # search results matching criteria
@returns(202) Accepted- Access Granted but data flow did not complete due to an unknown error.
@returns(206) {status: int, error: str} # No Data Returned
@errors {400: bad input parameter, 401: Unauthorized- API credentials not supplied. Ensure you have passed proper Username and Password parameters, 403: Forbidden- User access is denied. API user either does not have access or has been banned/locked., 405: Method Not Allowed- API user does not have access to use this method, 412: API Access Denied! Your API key is invalid, expired, or not supplied!}

@endpoint GET /kkid/wishlist
@desc Get list of wishlist items
@optional {kidUserId: int # userID of the kid}
@returns(200) {success: bool, wish: [map]} # search results matching criteria

@endpoint PUT /kkid/wishlist
@desc Update item on kid's wishlist
@required {wishId: int # Wish list item ID to update}
@optional {title: str # Item title, description: str # Item Description, priority: int # Item Priority, link: str # URL Link to item}
@returns(201) {success: bool, message: str} # search results matching criteria

@endpoint POST /kkid/wishlist
@desc Add item to kid's wishlist
@required {kidUserId: int # userID of the kid, title: str # Item title}
@optional {description: str # Item Description, priority: int # Item Priority, link: str # URL Link to item}
@returns(201) {success: bool, message: str} # search results matching criteria

@endpoint DELETE /kkid/wishlist
@desc Delete item from wishlist
@required {wishId: int # ID of wishlist item to delete}
@returns(200) {success: bool, message: str} # search results matching criteria

@endpoint GET /kkid/share
@desc Create Share Link
@required {linkUserId: str # User ID that the link should be authenticated to, link: str(https://khome.kumpeapps.com/portal/wish-list.php/https://khome.kumpeapps.com/portal/chores-today.php) # Link to share, scope: str(WishList/WishListAdmin/Chores/ChoresAdmin) # Authentication scope for link}
@optional {scope2: str(WishList/WishListAdmin/Chores/ChoresAdmin) # Authentication scope for link, scope3: str(WishList/WishListAdmin/Chores/ChoresAdmin) # Authentication scope for link, scope4: str(WishList/WishListAdmin/Chores/ChoresAdmin) # Authentication scope for link}
@returns(201) {success: bool, auth_link: str} # authenticated link created

@endgroup

@end