{"openapi":"3.1.0","info":{"title":"InstantGUI API","version":"1.2.0","description":"Live dashboards for scripts, devices and AI agents. Auth: \"Authorization: Bearer <credential>\" where the credential is the board's write token (igw_…) or its edit key (key=… in the edit link). Agent guide: https://instant-gui.com/llms.txt"},"servers":[{"url":"https://instant-gui.com"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Write token (igw_…) or edit key"}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"string"},"details":{}},"required":["ok","error"]},"BoardSpec":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":80},"description":{"type":"string","maxLength":280},"theme":{"type":"string","enum":["midnight","graphite","ocean","aurora","daylight","paper"]},"accent":{"anyOf":[{"type":"string","pattern":"^#[0-9a-f]{6}$"},{"type":"null"}]},"visibility":{"type":"string","enum":["public","private"]},"pages":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":40},"slug":{"type":"string","maxLength":60,"pattern":"^[\\p{L}\\p{N}]+(-[\\p{L}\\p{N}]+)*$"},"hidden":{"type":"boolean"},"params":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"default":{"type":"string","maxLength":500}},"required":["name"],"additionalProperties":false}},"widgets":{"maxItems":150,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"type":{"type":"string"},"title":{"type":"string","maxLength":120},"config":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"layout":{"type":"object","properties":{"x":{"type":"integer","minimum":0,"maximum":11},"y":{"type":"integer","minimum":0,"maximum":10000},"w":{"type":"integer","minimum":1,"maximum":12},"h":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"string","const":"auto"}]}}},"when":{"anyOf":[{"anyOf":[{"type":"object","properties":{"param":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"is":{"type":"string","maxLength":500},"screen":{"type":"string","enum":["narrow","wide"]}},"additionalProperties":false},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"param":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"is":{"type":"string","maxLength":500},"screen":{"type":"string","enum":["narrow","wide"]}},"additionalProperties":false}}]},{"type":"null"}]}},"required":["key","type"]}}},"required":["title","widgets"]}},"widgets":{"maxItems":150,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"type":{"type":"string"},"title":{"type":"string","maxLength":120},"config":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"layout":{"type":"object","properties":{"x":{"type":"integer","minimum":0,"maximum":11},"y":{"type":"integer","minimum":0,"maximum":10000},"w":{"type":"integer","minimum":1,"maximum":12},"h":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"string","const":"auto"}]}}},"when":{"anyOf":[{"anyOf":[{"type":"object","properties":{"param":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"is":{"type":"string","maxLength":500},"screen":{"type":"string","enum":["narrow","wide"]}},"additionalProperties":false},{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"param":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"},"is":{"type":"string","maxLength":500},"screen":{"type":"string","enum":["narrow","wide"]}},"additionalProperties":false}}]},{"type":"null"}]}},"required":["key","type"]}},"datasets":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"key":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_.-]{0,63}$"},"fields":{"type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_.-]{0,63}$"},"additionalProperties":{"type":"object","properties":{"type":{"type":"string","enum":["text","number","bool","time","list","json"]},"label":{"type":"string","maxLength":80}},"required":["type"],"additionalProperties":false}}},"required":["name","key"],"additionalProperties":false}},"prune":{"default":false,"type":"boolean"}}},"Layout":{"type":"object","properties":{"x":{"type":"integer","minimum":0,"maximum":11},"y":{"type":"integer","minimum":0},"w":{"type":"integer","minimum":1,"maximum":12},"h":{"type":"integer","minimum":1}}},"DatasetQuery":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"where":{"maxItems":32,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_.-]{0,63}$"},"op":{"type":"string","enum":["eq","neq","in","nin","contains","gte","lte","set","unset"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},{"type":"object","properties":{"now":{"type":"string"}},"required":["now"],"additionalProperties":false},{"type":"object","properties":{"param":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"}},"required":["param"],"additionalProperties":false}]},"param":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"}},"required":["field","op"],"additionalProperties":false}},"sort":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_.-]{0,63}$"},"dir":{"type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false}},"search":{"type":"string","maxLength":200},"searchFields":{"maxItems":30,"type":"array","items":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_.-]{0,63}$"}},"offset":{"type":"integer","minimum":0,"maximum":1000000},"limit":{"type":"integer","minimum":1,"maximum":200},"facets":{"maxItems":64,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"where":{"maxItems":32,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_.-]{0,63}$"},"op":{"type":"string","enum":["eq","neq","in","nin","contains","gte","lte","set","unset"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},{"type":"object","properties":{"now":{"type":"string"}},"required":["now"],"additionalProperties":false},{"type":"object","properties":{"param":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"}},"required":["param"],"additionalProperties":false}]},"param":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,39}$"}},"required":["field","op"],"additionalProperties":false}}},"required":["id"],"additionalProperties":false}},"params":{"description":"Page params read by clauses with {param}","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","null"]}}},"additionalProperties":false},"DatasetQueryResult":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"facets":{"type":"object","additionalProperties":{"type":"integer"}},"version":{"type":"integer"},"key":{"type":"string"}},"required":["records","total","facets","version","key"]}}},"paths":{"/api/v1/boards":{"post":{"summary":"Create a board (no account needed)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"template":{"type":"string"}}}}}},"responses":{"201":{"description":"board, editLink (secret), writeToken","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"}],"get":{"summary":"The whole board: pages and widgets","responses":{"200":{"description":"board, pages, widgets","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Rename / re-theme / change visibility (edit key) / set the default embed look (embedStyle, null clears)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"theme":{"type":"string"},"visibility":{"enum":["public","private"]},"embedStyle":{"type":["object","null"],"properties":{"theme":{"type":"string","description":"auto | light | dark | <theme id>"},"bg":{"type":"string","description":"transparent | <color>"},"radius":{"type":"number","minimum":0,"maximum":32},"density":{"enum":["comfortable","compact"]},"font":{"type":"string"},"vars":{"type":"object","additionalProperties":{"type":"string"},"description":"background, foreground, card, cardForeground, border, input, primary, primaryForeground, muted, mutedForeground, success, warning, danger, info, chart2…chart6 → CSS color"}}}}}}}},"responses":{"200":{"description":"board","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/spec":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"}],"get":{"summary":"The board as a spec (?data=1 includes data)","responses":{"200":{"description":"spec","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Apply a declarative spec (idempotent)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardSpec"},"example":{"title":"Shop live","prune":true,"widgets":[{"key":"headline","type":"markdown","layout":{"x":0,"y":0,"w":12,"h":2},"data":{"text":"**Sales are up 12% today.** Ads paused at 14:05 by Dana."}},{"key":"revenue","type":"kpi","title":"Revenue today","layout":{"x":0,"y":2,"w":3,"h":3},"config":{"prefix":"$","icon":"wallet"},"data":{"value":4820}},{"key":"orders","type":"kpi","title":"Orders today","layout":{"x":3,"y":2,"w":3,"h":3},"config":{"icon":"shopping-cart"},"data":{"value":131}},{"key":"conversion","type":"gauge","title":"Conversion","layout":{"x":6,"y":2,"w":3,"h":3},"config":{"max":10,"suffix":"%","decimals":1},"data":{"value":3.4}},{"key":"ads","type":"actions","title":"Ad campaign","layout":{"x":9,"y":2,"w":3,"h":3},"config":{"buttons":[{"id":"pause","label":"Pause ads","tone":"danger"},{"id":"resume","label":"Resume ads","tone":"success"}]}},{"key":"revenue-trend","type":"line","title":"Revenue per day ($)","layout":{"x":0,"y":5,"w":8,"h":5},"data":{"series":[{"name":"revenue","points":[["2026-10-08",4100],["2026-10-09",4390],["2026-10-10",4820]]}]}},{"key":"channels","type":"pie","title":"Orders by channel","layout":{"x":8,"y":5,"w":4,"h":5},"data":{"slices":[{"name":"Organic","value":61},{"name":"Ads","value":44},{"name":"Email","value":26}]}},{"key":"health","type":"status","title":"Systems","layout":{"x":0,"y":10,"w":4,"h":4},"data":{"services":[{"name":"Checkout","status":"up"},{"name":"Payments","status":"up"}]}},{"key":"orders-log","type":"log","title":"Recent orders","layout":{"x":4,"y":10,"w":8,"h":4},"data":{"entries":[{"t":1760000000000,"text":"#1045 · $129.00 · Organic","level":"success"}]}}]}}}},"responses":{"200":{"description":"created/replaced/updated/unchanged/deleted keys, widgets, lint, hints, urls","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/lint":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"}],"get":{"summary":"Design check (warnings to fix, suggestions)","responses":{"200":{"description":"ok, score, counts, warnings, suggestions","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/token":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"}],"post":{"summary":"Write token from the edit key ({rotate:true} issues a new one)","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"rotate":{"type":"boolean"}}}}}},"responses":{"200":{"description":"writeToken","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/view-tokens":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"}],"post":{"summary":"Create a view token (read-only embed/link; works on private boards). canUseControls: embeds with it may press the board's controls (edit key only)","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"expiresInHours":{"type":"integer"},"canUseControls":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"id, viewToken, canUseControls, embedUrl, linkUrl, iframe","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List view tokens","responses":{"200":{"description":"viewTokens","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/view-tokens/{id}":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Revoke a view token","responses":{"200":{"description":"revoked","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/widgets":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"}],"get":{"summary":"List widgets (key, type, config, data, layout)","responses":{"200":{"description":"pages, widgets","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a widget","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"config":{"type":"object"},"data":{"type":"object"},"layout":{"type":"object","properties":{"x":{"type":"integer","minimum":0,"maximum":11},"y":{"type":"integer","minimum":0},"w":{"type":"integer","minimum":1,"maximum":12},"h":{"type":"integer","minimum":1}}}}}}}},"responses":{"201":{"description":"widget, hints","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/widgets/{key}":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"},{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"description":"Widget key"}],"get":{"summary":"Read a widget (e.g. a control's current value)","responses":{"200":{"description":"widget","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Push data: {\"value\":42} | {\"data\":{…}} | {\"append\":…} | {\"config\":{…}}","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"value":42}}}},"responses":{"200":{"description":"widget","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Create or update by key (idempotent) when the body has `type`; otherwise a push","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"config":{"type":"object"},"data":{"type":"object"},"layout":{"type":"object","properties":{"x":{"type":"integer","minimum":0,"maximum":11},"y":{"type":"integer","minimum":0},"w":{"type":"integer","minimum":1,"maximum":12},"h":{"type":"integer","minimum":1}}},"page":{"type":"string"}}},"example":{"type":"kpi","title":"Revenue today","layout":{"x":0,"y":0,"w":3,"h":3},"data":{"value":4820}}}}},"responses":{"200":{"description":"action, widget, hints","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Move/resize/retitle: {\"layout\":{…},\"page\",\"title\"}; any other body is a push","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"layout":{"type":"object","properties":{"x":{"type":"integer","minimum":0,"maximum":11},"y":{"type":"integer","minimum":0},"w":{"type":"integer","minimum":1,"maximum":12},"h":{"type":"integer","minimum":1}}},"page":{"type":"string"},"title":{"type":"string"}}},"example":{"layout":{"x":0,"y":0,"w":6,"h":4}}}}},"responses":{"200":{"description":"widget","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a widget (recoverable from the board's history)","responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/widgets/{key}/push":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"},{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"description":"Widget key"}],"get":{"summary":"GET-only push for devices: ?token=<write token>&value=42","responses":{"200":{"description":"widget","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/datasets":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"}],"get":{"summary":"List datasets (name, key, fields, version, records, bytes)","responses":{"200":{"description":"datasets","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/datasets/{name}":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"},{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"description":"Dataset name"}],"get":{"summary":"Dataset info; ?keys=1 adds every record key","parameters":[{"name":"keys","in":"query","required":false,"schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"dataset, keys?","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A dataset limit would be passed (5,000 records / 4 MB per dataset, 32 KB per record, 16 MB per board — 1 MB without an owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Create the dataset and replace (default) or upsert its records. Idempotent. Body ≤ 500 KB — send more with POST …/records in chunks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Record field holding the unique key (needed when new)"},"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"enum":["text","number","bool","time","list","json"]},"label":{"type":"string"}},"required":["type"]}},"records":{"type":"array","maxItems":5000,"items":{"type":"object"}},"mode":{"enum":["replace","upsert"],"default":"replace"}}},"example":{"key":"id","fields":{"finished_at":{"type":"time"}},"records":[{"id":"task-12","status":"failed","project":"alpha","finished_at":"2026-10-16T08:00:00Z"}]}}}},"responses":{"200":{"description":"ok, dataset, key, version, records, bytes, created, added, updated, unchanged, deleted, changed (false: nothing changed, version kept)","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A dataset limit would be passed (5,000 records / 4 MB per dataset, 32 KB per record, 16 MB per board — 1 MB without an owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete the dataset and its records","responses":{"200":{"description":"deleted","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A dataset limit would be passed (5,000 records / 4 MB per dataset, 32 KB per record, 16 MB per board — 1 MB without an owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/datasets/{name}/records":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"},{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"description":"Dataset name"}],"post":{"summary":"Upsert records by key and delete keys (existing dataset)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"upsert":{"type":"array","items":{"type":"object"}},"delete":{"type":"array","items":{"type":["string","number"]}}}},"example":{"upsert":[{"id":"task-13","status":"done"}],"delete":["task-1"]}}}},"responses":{"200":{"description":"ok, dataset, key, version, records, bytes, created, added, updated, unchanged, deleted, changed (false: nothing changed, version kept)","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A dataset limit would be passed (5,000 records / 4 MB per dataset, 32 KB per record, 16 MB per board — 1 MB without an owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/datasets/{name}/records/{key}":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"},{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"description":"Dataset name"},{"name":"key","in":"path","required":true,"schema":{"type":"string","maxLength":200},"description":"Record key (the value of the dataset's key field)"}],"get":{"summary":"One record","responses":{"200":{"description":"record, version, key","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A dataset limit would be passed (5,000 records / 4 MB per dataset, 32 KB per record, 16 MB per board — 1 MB without an owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete one record","responses":{"200":{"description":"ok, dataset, key, version, records, bytes, created, added, updated, unchanged, deleted, changed (false: nothing changed, version kept)","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A dataset limit would be passed (5,000 records / 4 MB per dataset, 32 KB per record, 16 MB per board — 1 MB without an owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/boards/{boardId}/datasets/{name}/query":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"},{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"description":"Dataset name"}],"post":{"summary":"Query: where, sort, search, offset, limit ≤ 200, facets, params","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetQuery"},"example":{"where":[{"field":"status","op":"eq","value":"failed"}],"sort":[{"field":"finished_at","dir":"desc"}],"limit":20}}}},"responses":{"200":{"description":"records, total, facets {id: count}, version, key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetQueryResult"}}}},"401":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A dataset limit would be passed (5,000 records / 4 MB per dataset, 32 KB per record, 16 MB per board — 1 MB without an owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/boards/{boardId}/datasets/{name}/query":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"},{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"description":"Dataset name"},{"name":"t","in":"query","required":false,"schema":{"type":"string"},"description":"View token (private boards, embeds)"}],"post":{"summary":"Viewer query (what tables use): public boards, the board's viewers, or a view token (?t=). Read-only","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetQuery"}}}},"responses":{"200":{"description":"records, total, facets {id: count}, version, key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetQueryResult"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/boards/{boardId}/datasets/{name}/records/{key}":{"parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z]{10}$"},"description":"Board id (the part after /b/ in the board URL)"},{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"description":"Dataset name"},{"name":"key","in":"path","required":true,"schema":{"type":"string","maxLength":200},"description":"Record key (the value of the dataset's key field)"},{"name":"t","in":"query","required":false,"schema":{"type":"string"},"description":"View token (private boards, embeds)"}],"get":{"summary":"Viewer: one record by key (same access as the viewer query)","security":[],"responses":{"200":{"description":"record, version, key","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error: {\"ok\":false,\"error\":\"<what went wrong and what to do next>\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/widgets":{"get":{"summary":"Widget catalogue with JSON Schemas","security":[],"responses":{"200":{"description":"widgets","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}