> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Entities

> Manage apps, services, and chat extensions as publishable platform assets

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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
GET /api/entities/{entityId}/details
```

Returns comprehensive entity information including full version history and metadata.

**Authentication:** Entity access required.

## Icon upload

```bash theme={null}
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).