Entities - docs

Entities are the core publishable assets on the platform. An entity can be an app, a service, or a chat extension. Each entity has metadata, versions, publishers, and sharing controls.

Create entity

POST /api/entities

Parameter	Type	Required	Description
`type`	body	Yes	Entity type: `app`, `service`, or `chat_extension`
`slug`	body	Yes	Unique identifier (URL-safe)
`name`	body	Yes	Display name
`description`	body	No	Entity description
`icon_path`	body	No	Storage path for entity icon
`icon_hash`	body	No	Icon content hash for cache invalidation

Returns the created entity with storage configuration. Authentication: User authentication + entities:publish scope.

Get entity

GET /api/entities/{entityId}

Returns entity details including the active version, all versions, and storage configuration. Authentication: Entity access required (publisher, shared user, or store publication access).

Update entity

PUT /api/entities/{entityId}

Parameter	Type	Description
`name`	body	Updated display name
`description`	body	Updated description
`icon_path`	body	Updated icon storage path
`icon_hash`	body	Updated icon content hash

Authentication: Entity access + publisher role required.

Delete entity

DELETE /api/entities/{entityId}

Deletes the entity and all associated versions, shares, and publications. Version packages are removed from storage. Authentication: Entity access + publisher role required.

Get entity details

GET /api/entities/{entityId}/details

Returns comprehensive entity information including full version history and metadata. Authentication: Entity access required.

Icon upload

POST /api/entities/icon-upload-url

Parameter	Type	Required	Description
`entity_slug`	body	Yes	Entity slug
`ext`	body	Yes	File extension: `svg` or `png`

Returns a signed upload URL and the storage path to use when creating or updating the entity. Authentication: User authentication + entities:publish scope.

Entity types

Type	Description
`app`	Full-stack application built with the App Framework
`service`	External API integration built with the Services Framework
`chat_extension`	AI chat extension for the Desktop app

All entity types share the same lifecycle: create → push versions → set active → share or publish → deploy (apps only).

​Create entity

​Get entity

​Update entity

​Delete entity

​Get entity details

​Icon upload

​Entity types