Elements

Manage reusable, immutable-version visual references and their user-defined collections.

Base URL: https://app.gavana.ai/api/canvas-agent/v1 · Authentication: HTTP bearer, token format cba_<token-id>.<secret>

Operations

Operation	Purpose	Scopes
`GET /elements`	List or search Elements	element:read
`POST /elements`	Create an Element	element:write
`GET /elements/{elementId}`	Read an Element or exact immutable version	element:read
`PATCH /elements/{elementId}`	Update, organize, archive, or restore an Element	element:write
`GET /elements/{elementId}/versions`	List immutable Element versions	element:read
`GET /element-collections`	List user-defined Element collections	element:read
`POST /element-collections`	Create an Element collection	element:write
`PATCH /element-collections/{collectionId}`	Rename an Element collection	element:write
`DELETE /element-collections/{collectionId}`	Delete an Element collection after confirmation	element:write

`GET /elements`

List or search Elements

Returns owner-scoped active or archived Elements with mutable and current version-pinned handles.

Operation id: listElements
Scopes: Requires element:read.
CLI equivalent: gavana element list

Parameters

Parameter	In	Type	Required	Notes
`state`	query	string	No	One of `active`, `archived`. Default `"active"`.
`search`	query	string	No	max length 160.
`limit`	query	integer	No	Maximum number of items in this page. min 1, max 100.
`cursor`	query	string	No	Opaque continuation cursor from page.nextCursor. Reuse it with the same list filters. max length 8192.

Responses

Status	Payload	Meaning
`200`	ElementListResponse	A bounded page of Elements.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

200 response body

Field	Type	Required	Notes
`elements`	array of Element	Yes	—
`elements[].id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`elements[].handle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}$`.
`elements[].versionHandle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}@v[1-9][0-9]*$`.
`elements[].name`	string	Yes	min length 1, max length 160.
`elements[].type`	string	Yes	One of `character`, `product/object`, `environment`, `style`, `material/texture`, `lighting`.
`elements[].sourceAssetIds`	array of StableId	Yes	max items 8.
`elements[].collectionIds`	array of StableId	Yes	max items 24.
`elements[].guidelines`	string	No	max length 2000.
`elements[].ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`elements[].version`	integer	Yes	min 1.
`elements[].lifecycle`	string	Yes	One of `active`, `archived`.
`elements[].createdAt`	string (date-time)	Yes	—
`elements[].updatedAt`	string (date-time)	Yes	—
`elements[].archivedAt`	string (date-time)	No	—
`elements[].sourceHealth`	ElementSourceHealth	Yes	—
`elements[].sourceHealth.status`	string	Yes	One of `available`, `unavailable`, `unknown`.
`elements[].sourceHealth.unavailableSourceAssetIds`	array of StableId	Yes	max items 8.
`page`	CursorPage	Yes	—
`page.limit`	integer	Yes	min 1, max 200.
`page.hasMore`	boolean	Yes	—
`page.nextCursor`	string \| null	Yes	max length 8192.

Example


curl "https://app.gavana.ai/api/canvas-agent/v1/elements" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN"

`POST /elements`

Create an Element

Creates version 1 from prompt instructions, one to eight owned image Assets, or both.

Operation id: createElement
Scopes: Requires element:write.
CLI equivalent: gavana element create

Request body (application/json, required)

Field	Type	Required	Notes
`name`	string	Yes	min length 1, max length 160.
`type`	string	Yes	One of `character`, `product/object`, `environment`, `style`, `material/texture`, `lighting`.
`sourceAssetIds`	array of StableId	Yes	max items 8.
`guidelines`	string	No	max length 2000.
`collectionIds`	array of StableId	No	max items 24.

Responses

Status	Payload	Meaning
`201`	ElementCurrentResponse	The created Element.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

201 response body

Field	Type	Required	Notes
`element`	Element	Yes	—
`element.id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`element.handle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}$`.
`element.versionHandle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}@v[1-9][0-9]*$`.
`element.name`	string	Yes	min length 1, max length 160.
`element.type`	string	Yes	One of `character`, `product/object`, `environment`, `style`, `material/texture`, `lighting`.
`element.sourceAssetIds`	array of StableId	Yes	max items 8.
`element.collectionIds`	array of StableId	Yes	max items 24.
`element.guidelines`	string	No	max length 2000.
`element.ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`element.version`	integer	Yes	min 1.
`element.lifecycle`	string	Yes	One of `active`, `archived`.
`element.createdAt`	string (date-time)	Yes	—
`element.updatedAt`	string (date-time)	Yes	—
`element.archivedAt`	string (date-time)	No	—
`element.sourceHealth`	ElementSourceHealth	Yes	—
`element.sourceHealth.status`	string	Yes	One of `available`, `unavailable`, `unknown`.
`element.sourceHealth.unavailableSourceAssetIds`	array of StableId	Yes	max items 8.

Example


curl -X POST "https://app.gavana.ai/api/canvas-agent/v1/elements" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '"<value>"'

`GET /elements/{elementId}`

Read an Element or exact immutable version

Without version, returns the current Element. With version, returns only that exact immutable revision and never upgrades silently.

Operation id: getElement
Scopes: Requires element:read.
CLI equivalent: gavana element get

Parameters

Parameter	In	Type	Required	Notes
`elementId`	path	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`version`	query	integer	No	min 1.

Responses

Status	Payload	Meaning
`200`	ElementCurrentResponse \| ElementVersionResponse	The current Element or requested immutable version.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

200 response body

Field	Type	Required	Notes
`(ElementCurrentResponse).element`	Element	Yes	—
`(ElementCurrentResponse).element.id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(ElementCurrentResponse).element.handle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}$`.
`(ElementCurrentResponse).element.versionHandle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}@v[1-9][0-9]*$`.
`(ElementCurrentResponse).element.name`	string	Yes	min length 1, max length 160.
`(ElementCurrentResponse).element.type`	string	Yes	One of `character`, `product/object`, `environment`, `style`, `material/texture`, `lighting`.
`(ElementCurrentResponse).element.sourceAssetIds`	array of StableId	Yes	max items 8.
`(ElementCurrentResponse).element.collectionIds`	array of StableId	Yes	max items 24.
`(ElementCurrentResponse).element.guidelines`	string	No	max length 2000.
`(ElementCurrentResponse).element.ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(ElementCurrentResponse).element.version`	integer	Yes	min 1.
`(ElementCurrentResponse).element.lifecycle`	string	Yes	One of `active`, `archived`.
`(ElementCurrentResponse).element.createdAt`	string (date-time)	Yes	—
`(ElementCurrentResponse).element.updatedAt`	string (date-time)	Yes	—
`(ElementCurrentResponse).element.archivedAt`	string (date-time)	No	—
`(ElementCurrentResponse).element.schemaVersion`	1	Yes	—
`(ElementCurrentResponse).element.sourceHealth`	ElementSourceHealth	Yes	—
`(ElementCurrentResponse).element.sourceHealth.status`	string	Yes	One of `available`, `unavailable`, `unknown`.
`(ElementCurrentResponse).element.sourceHealth.unavailableSourceAssetIds`	array of StableId	Yes	max items 8.
`(ElementVersionResponse).version`	ElementVersion	Yes	—
`(ElementVersionResponse).version.id`	string	Yes	Pattern `^v[1-9][0-9]*$`.
`(ElementVersionResponse).version.elementId`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(ElementVersionResponse).version.handle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}$`.
`(ElementVersionResponse).version.versionHandle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}@v[1-9][0-9]*$`.
`(ElementVersionResponse).version.elementName`	string	Yes	min length 1, max length 160.
`(ElementVersionResponse).version.elementType`	string	Yes	One of `character`, `product/object`, `environment`, `style`, `material/texture`, `lighting`.
`(ElementVersionResponse).version.sourceAssetIds`	array of StableId	Yes	max items 8.
`(ElementVersionResponse).version.guidelines`	string	No	max length 2000.
`(ElementVersionResponse).version.ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(ElementVersionResponse).version.version`	integer	Yes	min 1.
`(ElementVersionResponse).version.createdAt`	string (date-time)	Yes	—
`(ElementVersionResponse).version.schemaVersion`	1	Yes	—
`(ElementVersionResponse).version.sourceHealth`	ElementSourceHealth	Yes	—
`(ElementVersionResponse).version.sourceHealth.status`	string	Yes	One of `available`, `unavailable`, `unknown`.
`(ElementVersionResponse).version.sourceHealth.unavailableSourceAssetIds`	array of StableId	Yes	max items 8.

Example


curl "https://app.gavana.ai/api/canvas-agent/v1/elements/%3CelementId%3E" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN"

`PATCH /elements/{elementId}`

Update, organize, archive, or restore an Element

Content updates and restores append immutable versions. Archival requires confirm=true and never hard-deletes the Element.

Operation id: mutateElement
Scopes: Requires element:write.
CLI equivalent: gavana element update

Parameters

Parameter	In	Type	Required	Notes
`elementId`	path	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.

Request body (application/json, required)

Field	Type	Required	Notes
`(variant 1).operation`	“update”	Yes	—
`(variant 1).element`	any \| object	Yes	—
`(variant 1).element.name`	string	Yes	min length 1, max length 160.
`(variant 1).element.type`	string	Yes	One of `character`, `product/object`, `environment`, `style`, `material/texture`, `lighting`.
`(variant 1).element.sourceAssetIds`	array of StableId	Yes	max items 8.
`(variant 1).element.guidelines`	string	No	max length 2000.
`(variant 2).operation`	“collections”	Yes	—
`(variant 2).collectionIds`	array of StableId	Yes	max items 24.
`(variant 3).operation`	“archive”	Yes	—
`(variant 3).confirm`	true	Yes	Set only after explicit user confirmation.
`(variant 4).operation`	“restore”	Yes	—

Responses

Status	Payload	Meaning
`200`	ElementCurrentResponse	The resulting current Element.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

200 response body

Field	Type	Required	Notes
`element`	Element	Yes	—
`element.id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`element.handle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}$`.
`element.versionHandle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}@v[1-9][0-9]*$`.
`element.name`	string	Yes	min length 1, max length 160.
`element.type`	string	Yes	One of `character`, `product/object`, `environment`, `style`, `material/texture`, `lighting`.
`element.sourceAssetIds`	array of StableId	Yes	max items 8.
`element.collectionIds`	array of StableId	Yes	max items 24.
`element.guidelines`	string	No	max length 2000.
`element.ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`element.version`	integer	Yes	min 1.
`element.lifecycle`	string	Yes	One of `active`, `archived`.
`element.createdAt`	string (date-time)	Yes	—
`element.updatedAt`	string (date-time)	Yes	—
`element.archivedAt`	string (date-time)	No	—
`element.sourceHealth`	ElementSourceHealth	Yes	—
`element.sourceHealth.status`	string	Yes	One of `available`, `unavailable`, `unknown`.
`element.sourceHealth.unavailableSourceAssetIds`	array of StableId	Yes	max items 8.

Example


curl -X PATCH "https://app.gavana.ai/api/canvas-agent/v1/elements/%3CelementId%3E" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "update",
    "element": "<element>"
  }'

`GET /elements/{elementId}/versions`

List immutable Element versions

Operation id: listElementVersions
Scopes: Requires element:read.
CLI equivalent: gavana element history

Parameters

Parameter	In	Type	Required	Notes
`elementId`	path	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`limit`	query	integer	No	Maximum number of items in this page. min 1, max 100.
`cursor`	query	string	No	Opaque continuation cursor from page.nextCursor. Reuse it with the same list filters. max length 8192.

Responses

Status	Payload	Meaning
`200`	ElementHistoryResponse	A bounded newest-first page of immutable versions.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

200 response body

Field	Type	Required	Notes
`versions`	array of ElementVersion	Yes	—
`versions[].id`	string	Yes	Pattern `^v[1-9][0-9]*$`.
`versions[].elementId`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`versions[].handle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}$`.
`versions[].versionHandle`	string	Yes	Pattern `^element:[A-Za-z0-9_-]{1,160}@v[1-9][0-9]*$`.
`versions[].elementName`	string	Yes	min length 1, max length 160.
`versions[].elementType`	string	Yes	One of `character`, `product/object`, `environment`, `style`, `material/texture`, `lighting`.
`versions[].sourceAssetIds`	array of StableId	Yes	max items 8.
`versions[].guidelines`	string	No	max length 2000.
`versions[].ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`versions[].version`	integer	Yes	min 1.
`versions[].createdAt`	string (date-time)	Yes	—
`versions[].sourceHealth`	ElementSourceHealth	Yes	—
`versions[].sourceHealth.status`	string	Yes	One of `available`, `unavailable`, `unknown`.
`versions[].sourceHealth.unavailableSourceAssetIds`	array of StableId	Yes	max items 8.
`page`	CursorPage	Yes	—
`page.limit`	integer	Yes	min 1, max 200.
`page.hasMore`	boolean	Yes	—
`page.nextCursor`	string \| null	Yes	max length 8192.

Example


curl "https://app.gavana.ai/api/canvas-agent/v1/elements/%3CelementId%3E/versions" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN"

`GET /element-collections`

List user-defined Element collections

Operation id: listElementCollections
Scopes: Requires element:read.
CLI equivalent: gavana element collection-list

Parameters

Parameter	In	Type	Required	Notes
`limit`	query	integer	No	Maximum number of items in this page. min 1, max 100.
`cursor`	query	string	No	Opaque continuation cursor from page.nextCursor. Reuse it with the same list filters. max length 8192.

Responses

Status	Payload	Meaning
`200`	ElementCollectionListResponse	A bounded page of collections.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

200 response body

Field	Type	Required	Notes
`collections`	array of ElementCollection	Yes	—
`collections[].id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`collections[].handle`	string	Yes	Pattern `^element-collection:[A-Za-z0-9_-]{1,160}$`.
`collections[].name`	string	Yes	min length 1, max length 120.
`collections[].ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`collections[].createdAt`	string (date-time)	Yes	—
`collections[].updatedAt`	string (date-time)	Yes	—
`page`	CursorPage	Yes	—
`page.limit`	integer	Yes	min 1, max 200.
`page.hasMore`	boolean	Yes	—
`page.nextCursor`	string \| null	Yes	max length 8192.

Example


curl "https://app.gavana.ai/api/canvas-agent/v1/element-collections" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN"

`POST /element-collections`

Create an Element collection

Operation id: createElementCollection
Scopes: Requires element:write.
CLI equivalent: gavana element collection-create

Request body (application/json, required)

Field	Type	Required	Notes
`name`	string	Yes	min length 1, max length 120.

Responses

Status	Payload	Meaning
`201`	ElementCollectionMutationResponse	The created collection.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

201 response body

Field	Type	Required	Notes
`(variant 1).collection`	ElementCollection	Yes	—
`(variant 1).collection.id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(variant 1).collection.handle`	string	Yes	Pattern `^element-collection:[A-Za-z0-9_-]{1,160}$`.
`(variant 1).collection.name`	string	Yes	min length 1, max length 120.
`(variant 1).collection.ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(variant 1).collection.createdAt`	string (date-time)	Yes	—
`(variant 1).collection.updatedAt`	string (date-time)	Yes	—
`(variant 1).collection.schemaVersion`	1	Yes	—
`(variant 2).id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(variant 2).handle`	string	Yes	Pattern `^element-collection:[A-Za-z0-9_-]{1,160}$`.

Example


curl -X POST "https://app.gavana.ai/api/canvas-agent/v1/element-collections" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<name>"
  }'

`PATCH /element-collections/{collectionId}`

Rename an Element collection

Operation id: renameElementCollection
Scopes: Requires element:write.
CLI equivalent: gavana element collection-rename

Parameters

Parameter	In	Type	Required	Notes
`collectionId`	path	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.

Request body (application/json, required)

Field	Type	Required	Notes
`name`	string	Yes	min length 1, max length 120.

Responses

Status	Payload	Meaning
`200`	ElementCollectionMutationResponse	The renamed collection.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

200 response body

Field	Type	Required	Notes
`(variant 1).collection`	ElementCollection	Yes	—
`(variant 1).collection.id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(variant 1).collection.handle`	string	Yes	Pattern `^element-collection:[A-Za-z0-9_-]{1,160}$`.
`(variant 1).collection.name`	string	Yes	min length 1, max length 120.
`(variant 1).collection.ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(variant 1).collection.createdAt`	string (date-time)	Yes	—
`(variant 1).collection.updatedAt`	string (date-time)	Yes	—
`(variant 1).collection.schemaVersion`	1	Yes	—
`(variant 2).id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(variant 2).handle`	string	Yes	Pattern `^element-collection:[A-Za-z0-9_-]{1,160}$`.

Example


curl -X PATCH "https://app.gavana.ai/api/canvas-agent/v1/element-collections/%3CcollectionId%3E" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<name>"
  }'

`DELETE /element-collections/{collectionId}`

Delete an Element collection after confirmation

Deletes only the organizational collection. Its Assets and Elements remain. The caller must obtain explicit user confirmation first.

Operation id: deleteElementCollection
Scopes: Requires element:write.
CLI equivalent: gavana element collection-delete

Parameters

Parameter	In	Type	Required	Notes
`collectionId`	path	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.

Request body (application/json, required)

Responses

Status	Payload	Meaning
`200`	ElementCollectionMutationResponse	The deleted collection id and handle.
`default`	ErrorResponse	A stable machine-readable error. The response always includes X-Request-ID.

200 response body

Field	Type	Required	Notes
`(variant 1).collection`	ElementCollection	Yes	—
`(variant 1).collection.id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(variant 1).collection.handle`	string	Yes	Pattern `^element-collection:[A-Za-z0-9_-]{1,160}$`.
`(variant 1).collection.name`	string	Yes	min length 1, max length 120.
`(variant 1).collection.ownerUid`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(variant 1).collection.createdAt`	string (date-time)	Yes	—
`(variant 1).collection.updatedAt`	string (date-time)	Yes	—
`(variant 1).collection.schemaVersion`	1	Yes	—
`(variant 2).id`	string	Yes	Pattern `^[A-Za-z0-9_-]{1,180}$`.
`(variant 2).handle`	string	Yes	Pattern `^element-collection:[A-Za-z0-9_-]{1,160}$`.

Example


curl -X DELETE "https://app.gavana.ai/api/canvas-agent/v1/element-collections/%3CcollectionId%3E" \
  -H "Authorization: Bearer $GAVANA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": true
  }'

Errors

Every failure uses the shared error envelope described in Errors and X-Request-ID. The response always carries X-Request-ID; share that value with support instead of the request payload.