Skip to content

Save a dashboard definition (compare-and-swap)

PUT /dashboard/{id}/definition

Requires edit access. A direct save of the PUBLISHED definition, not the draft (see `PUT /dashboard/{id}/draft`); it does not touch a pending draft, and publishing that draft afterwards is refused (409 `live_changed_since_draft`) until its author has reviewed it against this save. 409 `dashboard_revision_conflict` on a stale `revision`.

Path Parameters

idstring
required·

Resource id

Request Body

definition
revisioninteger

Response Body

access_summary
access_viastring
agent_edit_blocked_bystring,null
Possible values:
assistant_disabledllm_not_configurednot_permittednull
can_agent_editboolean,null
can_discard_draftboolean

can_manage, there is a draft, and the dashboard has been published (a never-published dashboard has no live version to go back to).

can_manageboolean
can_publishboolean

can_manage and there is a draft to publish.

can_revoke_shareboolean
can_see_sharesboolean
can_shareboolean
can_transferboolean
created_atstring
definition
descriptionstring
draftobject,null

The pending draft, present only for a caller with can_manage; everyone else sees the published definition.

definition
descriptionstring
draft_revisioninteger
namestring
updated_atstring
updated_by_namestring,null
updated_clientstring,null

The AI client's display name, as on the dashboard itself.

updated_viastring,null
draft_changesobject
countinteger
ever_publishedboolean
itemsarray
moreinteger
draft_revisioninteger

The guard on PUT /dashboard/{id}/draft. Moves on every draft save, publish and discard.

ever_publishedboolean
has_draftboolean

A pending draft exists. Only a caller with can_manage is ever shown the draft itself.

idstring
labelsobject
widgets
live_changed_since_draftboolean

The live dashboard was saved after the pending draft began, so publishing would replace that save. Only ever true for a caller with can_manage; the Elaichi app warns in words and sends live_revision on publish only after the person confirms.

namestring
owner_avatar_urlstring,null

The person's picture: their stored profile picture, else a Gravatar URL (d=404, 96px) derived from their email (the address itself is not sent), else null. Draw initials when it is null or the image fails to load.

owner_display_namestring,null
owner_user_idstring
page_countinteger
provenance
public_links
publish_blocked_reasonstring,null

Why publishing would fail right now (a widget that does not validate), else null. A source the publisher cannot read is checked by the publish itself.

revisioninteger
source_previewobject[]

At most three sources the caller can read. The total is source_summary; the full set is sources on the detail.

logostring,null
namestring
resource_typestring
Possible values:
collectiontoolboxautomation
slugstring,null

The connector slug when the source has exactly one; null otherwise, never guessed.

source_summaryobject
collection_idsstring[]
toolbox_idsstring[]
sourcesobject[]
caller_can_readboolean
namestring,null
resource_idstring
resource_typestring
widget_countinteger
statusstring

draft_only: never published, so only editors can open it. published_with_changes: live, with a pending draft.

Possible values:
publisheddraft_onlypublished_with_changes
updated_atstring
updated_bystring,null
updated_by_namestring,null
updated_clientstring,null

The connected AI client's display name ("Claude") when updated_via is mcp; null when that client is unknown. Never an internal id.

updated_viastring,null

How the last edit was made; null for edits that predate the draft layer.

Possible values:
consoleagentmcpapinull
widget_countinteger
curl -X PUT 'https://api.elaichi.ai/dashboard/<id>/definition' \
  -H 'Authorization: Bearer $ELAICHI_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"revision":0}'
const body = {
  "revision": 0
};

const response = await fetch('https://api.elaichi.ai/dashboard/<id>/definition', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer ' + process.env.ELAICHI_API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
});

const data = await response.json();
console.log(data);
import os
import requests

url = "https://api.elaichi.ai/dashboard/<id>/definition"
headers = {
    "Authorization": f"Bearer {os.environ['ELAICHI_API_TOKEN']}",
    "Content-Type": "application/json",
}
payload = {
    "revision": 0
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())