|====================================| | ArtiAPI Protocol Version 1.41 | | Written by: Michel van Osenbruggen | | CopyRight 2026 ArtiLED B.V. | |====================================| Hub version : 0.616 beta Latest change : 17-03-2026 ======================= | Protocol Definition | ======================= Protocol : HTTP(S) Port : 80/443 URL : http(s)://hub_ip/api DATA : POST with variables |=============| | Definitions | |=============| House : All lights are located in a House Room : Every light can be located in only one Room Zone : Every light can be located in multiple Zones Strip : Whole led strip -> All leds (Number of leds) Multi Strip : Multiple led strips with channel -> All leds Segment : Part of a led strip -> Start, End -> Start and End (0-1000) Part : Part of a led strip -> Start, End -> Start and End (0-1000) (Used for different scaling with Palette Part) Multi Segment : Multiple Parts of a led strip -> Array of n x (Start, End) -> Start and End (0-1000) Pixel : Single pixel of a led strip -> Pixel number -> Pixel numbers (0-1000) Multi Pixel : Multiple pixels of a led strip -> Array of Pixel Numbers -> Pixel numbers (0-1000) Pixel String : Multiple pixels of a led strip with a start (msb, lsb) then followed by an Array of Pixel Numbers (0-1000) Palette : Collection of Colors -> Max 16 colors |===================| | Channel Structure | |===================| 0 : 0 = All Channels 1 : 1 = Channel 1 2 : 2 = Channel 2 3 : 3 = Channel 3 4 : 4 = Channel 4 12 : 12 = Channel 1 + 2 13 : 13 = Channel 1 + 3 14 : 14 = Channel 1 + 4 23 : 23 = Channel 2 + 3 24 : 24 = Channel 2 + 4 34 : 34 = Channel 3 + 4 123 : 123 = Channel 1 + 2 + 3 124 : 124 = Channel 1 + 2 + 4 134 : 134 = Channel 1 + 3 + 4 234 : 234 = Channel 2 + 3 + 4 |===================| | Command Structure | |===================| > Command : /command + Token + Data -> example http://hub_ip/api/rooms # Privileged Command : /command + Token + Data (requires admin rights) $ Data : Depends on Command -> Send Data as json variable -> example: {"zone":1} or {"room":2} $ Token : Send as variable with each request token="Token" (Token is case sensitive) ! Future Command : Command not done yet, coming soon |=============| | Error Codes | |=============| 1 : Login Failed (invalid username or password) 2 : Token Invalid (request new token) 3 : Incomplete data (not all data supplied) 4 : Invalid data (data value incorrect) 5 : Invalid item (id does not exist) 6 : Command Invalid 7 : Command Execution Failed ====================== | Response Structure | ====================== $ response : Command Response => { "success":1/0, "error":error Number, "error_text":"Error Text", "data": { data } } $ success : 1 = Command Successful, 0 = Error (See Error) $ error : Error Number (See List) $ error_text : Error Text $ execution_time : Time in milliseconds it took to execute the Command $ data : See Data Structure ================== | Data Structure | ================== $ name : {"name":"name"} -> Node Name $ ident : {"ident":"ident"} -> Node Ident $ version : {"version":"version"} -> Node Software Version $ state : {"state":state} -> State 0=Off, 1=On $ online : {"online":online} -> Node/Light Status 0=Offline, 1=Online $ active : {"active":active} -> Active 0=Not Active, 1=Active $ channel : {"channel":channel} -> See Channel Structure $ brightness : {"brightness":brightness} -> Brightness Value (0-255) $ hue : {"hue":hue} -> Hue Value (0-255) $ saturation : {"saturation":saturation} -> Saturation Value (0-255) $ color : {"color":"rgb(red,green,blue)"} $ colors : {"colors":["rgb(red,green,blue)","rgb(red,green,blue)", ....]} $ color_rgbw : {"red":red,"green":green,"blue":blue,"white":white} -> Values (0-255) $ color_rgb : {"red":red,"green":green,"blue":blue} -> Values (0-255) $ color_hsv : {"hue":hue,"saturation":saturation,"value":value} -> Values (0-255) $ color_w : {"temperature":temperature,"intensity":intensity} -> Values (0-255) $ segment : {"start":start,"end":end} -> Values (0-1000) $ part : {"start":start,"end":end} -> Values (0-1000) $ clear : {"clear":clear,"commit":commit} -> Values (0-1) $ room : {"id":id,"name":"name","icon":"icon","status":"status","state":state,"brightness":brightness,"colors":["rgb(red,green,blue)", "rgb(red,green,blue)", ...]} $ zone : {"id":id,"name":"name","icon":"icon","status":"status","state":state,"brightness":brightness,"channel":channel,"colors":["rgb(red,green,blue)", "rgb(red,green,blue)", ...]} $ scene : {"id":id,"name":"name","image_url":"image_url","running":0/1} -> Running 0=Done, 1=Running $ mode : {"id":id,"name":"name","image_url":"image_url"} $ light : {"id":id,"name":"name","icon":"icon","disabled":disabled,"down":down,"state":state,"brightness":brightness} $ node : {"id":id,"name":"name","enabled":enabled,"down":down} $ palette : {"palette":{"palette":palette_id,"blend":blend,"scale":scale,"alternate":alternate,"start_index":start_index,"end_index":end_index}} $ custom_palette : {"custom_palette":{"start_color":{"red":red,"green":green,"blue":blue},"end_color":{"red":red,"green":green,"blue":blue},"blend":blend,"scale":scale,"alternate":alternate,"start_index":start_index,"end_index":end_index}} $ advanced_palette : {"advanced_palette":{"color_array":[[pos,red,green,blue],[pos,red,green,blue],...],"blend":blend,"scale":scale,"alternate":alternate,"start_index":start_index,"end_index":end_index}} $ effect_rgb : {"effect_rgb":{"effect":effect_id,"clear":0/1,"step":step,"start_delay":start_delay,"end_delay":end_delay,"red":red,"green":green,"blue":blue}} $ effect_rgbw : {"effect_rgbw":{"effect":effect_id,"clear":0/1,"step":step,"start_delay":start_delay,"end_delay":end_delay,"red":red,"green":green,"blue":blue,"white":white}} Effect IDs : 1=Forward Fill, 2=Reverse Fill, 3=Forward Clear, 4=Reverse Clear, 5=Outward Fill, 6=Center Fill, 7=Outward Clear, 8=Center Clear, 9=Strobe Even, 10=Strobe Vari, 11=Random Fill, 12=Fade In, 13=Fade Out, 14=Forward Gradient In, 15=Reverse Gradient In, 16=Forward Gradient Out, 17=Reverse Gradient Out, 18=Outward Gradient In, 19=Outward Gradient Out, 20=Center Gradient In, 21=Center Gradient Out, 22=Forward Pixel Run, 23=Reverse Pixel Run, 24=Outward Pixel Run, 25=Center Pixel Run, 26=Cross Pixel Run, 27=Smart Forward Fill, 28=Smart Reverse Fill, 29=Smart Alt Forward Fill, 30=Smart Alt Reverse Fill, 31=Smart Forward Clear, 32=Smart Reverse Clear, 33=Smart Alt Forward Clear, 34=Smart Alt Reverse Clear Effect Parameters : effect=Effect ID (1-34), clear=Clear strip first (0/1), step=Step/Repeat/Pixels (0-65000), start_delay=Start delay (0-255), end_delay=End delay/Segments (0-255), Colors (0-255) $ notification : {"id":id, "priority":priority,"ident":"ident","name":"name","datetime":"datetime","text":"text"} $ capabilities : {"dim":1/0,"colors":1/0,"color_profile":"w/rgb/rgbw","segments":0-16} ============ | Commands | ============ ----------------- | Alive Command | ----------------- > /Alive : No Data -> Returns Hub Name and Ident -> See Data Structure 'name' and 'ident' ----------------- | Login Command | ----------------- > /login : Data -> username and password -> Returns Token -> User Authenticates once with login screen ----------------- | Info Commands | ----------------- > /version : No Data -> Returns Hub Version -> See Data Structure 'version' ---------------- | Get Commands | ---------------- > /rooms : No Data or {"room":room_id} or {"room":"room_name"} and {"order":"id"} or {"order":"name"} or {"select":"visible/invisible/all"} -> Returns Rooms -> {"rooms":[{room1, room2, ....}]} See Data Structure 'room' > /zones : No Data or {"zone":zone_id} or {"zone":"zone_name"} or {"room":room_id} or {"room":"room_name"} or {"select":"visible/invisible/all"} and {"order":"id"} or {"order":"name"} -> Returns Zones -> {"zones":[{zone1, zone2, ....}]} See Data Structure 'zone' > /scenes : No Data or {"zone":zone_id} or {"zone":"zone_name"} or {"room":room_id} or {"room":"room_name"} or {"select":"visible/invisible/all"} and {"order":"id"} or {"order":"name"} -> Returns Scenes -> {"scenes":[{scene1, scene2, ....}]} See Data Structure 'scene' > /modes : No Data or {"zone":zone_id} or {"zone":"zone_name"} or {"room":room_id} or {"room":"room_name"} and {"order":"id"} or {"order":"name"} -> Returns Modes -> {"modes":[{mode1, mode2, ....}]} See Data Structure 'mode' > /lights : No Data or {"zone":zone_id} or {"zone":"zone_name"} or {"room":room_id} or {"room":"room_name"} or {"light":light_id} or {"light":"light_name"} -> Returns Lights -> {"lights":[{light1, light2, ....}]} See Data Structure 'light' > /notifications : No Data or {"order":id} or {"order":"date"}, {"limit":limit} -> Returns Notifications -> {"notifications":[{notification1, notification2, ....}]} See Data Structure 'notification' ! /nodes : No Data or {"zone":zone_id} or {"room":room_id} -> Returns Nodes -> {"nodes":[{node1, node2, ....}]} See Data Structure 'node' ! /strips : ! /segments : ---------------- | Set Commands | ---------------- > /house : Data {"channel":channel},{"state":state},{"brightness":brightness},{"color_w"},{"color_rgb"},{"color_rgbw"},{"color_hsv"},{"palette*"},{"effect_rgb"},{"effect_rgbw"} -> Sets House -> Returns Response See Data structure 'response' > /room : Data {"room":room_id} or {"room":"room_name"} and {"channel":channel},{"state":state},{"brightness":brightness},{"color_w"},{"color_rgb"},{"color_rgbw"},{"color_hsv"},{"palette*"},{"effect_rgb"},{"effect_rgbw"} -> Sets Room -> Returns Response See Data structure 'response' > /zone : Data {"zone":zone_id} or {"zone":"zone_name"} and {"channel":channel},{"state":state},{"brightness":brightness},{"color_w"},{"color_rgb"},{"color_rgbw"},{"color_hsv"},{"palette*"},{"effect_rgb"},{"effect_rgbw"} -> Sets Zone -> Returns Response See Data structure 'response' > /light : Data {"light":light_id} or {"light":"light_name"} and {"channel":channel},{"state":state},{"clear":clear},{"brightness":brightness},{"color_w"},{"color_rgb"},{"color_rgbw"},{"color_hsv"},{"palette*"},{"effect_rgb"},{"effect_rgbw"},{"segment"} -> Sets Light -> Returns Response See Data structure 'response' : You can add {"hue":1} if you also want to control added or associated Philips Hue Lights (Please note you cannot update them as often as ArtiLED lights). ------------------ | Scene Commands | ------------------ > /scene : Data {"scene":scene_id} or {"scene":"scene_name"} and {"room":room_id} or {"room":"room_name"} or {"zone":zone_id} or {"zone":"zone_name"} or {"light":light_id} or {"light":"light_name"} -> Runs scene in Room, Zone or Light -> Returns Response See Data structure 'response' ! /scene_stop ----------------- | Mode Commands | ----------------- > /mode : Data {"mode":mode_id} or {"mode":"mode_name"} and {"room":room_id} or {"room":"room_name"} or {"zone":zone_id} or {"zone":"zone_name"} or {"light":light_id} or {"light":"light_name"} -> Starts mode in Room, Zone or Light -> Returns Response See Data structure 'response' ----------------- | Flow Commands | ----------------- > /flow : Data {"flow":flow_id} or {"flow":"flow_name"} and {"action":"start"} or {"action":"stop"} -> Starts or stops flow -> Returns Response See Data structure 'response' > /flows : No Data -> Returns Flows -> {"flows":[{flow1, flow2, ....}]} See Data Structure 'flow' $ flow : {"id":id,"name":"name","icon":"icon","enable":0/1,"running":true/false,"last_run":"datetime"} -------------------- | Profile Commands | -------------------- > /profile : Data {"profile":profile_id} or {"profile":"profile_name"} and {"action":"activate"} or {"action":"deactivate"} and optional {"source":"trigger"} -> Activates or deactivates profile -> Returns Response See Data structure 'response' > /profiles : No Data -> Returns Profiles -> {"profiles":[{profile1, profile2, ....}]} See Data Structure 'profile' $ profile : {"id":id,"name":"name","icon":"icon","active":0/1,"protected":0/1,"role_id":role_id}