---
title: "Update asset entity"
method: PATCH
path: "/assets/entities/{entity_id}"
tags: ["Assets"]
---

# Update asset entity

`PATCH /assets/entities/{entity_id}`

## Request

- Base URL: `https://api.fal.ai/v1`
- URL: `https://api.fal.ai/v1/assets/entities/{entity_id}`
- Auth: API key in header `Authorization`

Update a saved entity without recreating it. Omitted fields stay unchanged; reference_images replaces the defining reference set. Entity types cannot be changed. Character handles cannot be changed and character descriptions cannot be cleared. Other entity handles must remain unique within the account.

**Required permissions:** `assets:write`. Key presets that include them: `API`, `SERVERLESS`, `FULL`. See [key permissions](https://fal.ai/docs/documentation/model-apis/authentication/key-based#permissions).

## Path parameters

- `entity_id` string, required: Smart entity ID

## Headers

- `Idempotency-Key` string: Optional idempotency key for safe request retries

## Request body

- object
  - `name` string: Entity display name
  - `handle` string: Replacement @mention handle. Character handles cannot be changed.
  - `description` string, nullable: Replacement visual description; null clears it for non-character entities.
  - `reference_images` string[]: Replace the defining references with these saved asset IDs, request IDs, vector IDs, or fal-hosted image URLs.
  - `cover_image_url` string, uri, nullable: Replacement cover image URL from the entity's reference images; null clears the explicit cover.

## Response `200`

Entity updated

- object
  - `entity` object, required: Saved smart entity
    - `id` string, required: Smart entity ID
    - `type` 'character' | 'prop' | 'environment' | 'style' | 'scene', required: Smart entity type
    - `name` string, required: Entity display name
    - `handle` string, required: Resolved @mention handle, without the leading @
    - `description` string, nullable, required: Entity visual description
    - `cover_image_url` string, nullable, required: Entity cover image URL
    - `reference_images` string[], required: Defining reference image URLs
    - `is_favorited` boolean, required: Whether the entity is favorited
    - `created_at` string, date-time, required: Creation time in UTC
    - `updated_at` string, date-time, required: Last update time in UTC

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication required
- `403`: Access denied
- `404`: Resource not found
- `409`: Invalid request parameters
- `422`: Invalid request parameters
- `429`: Rate limit exceeded
- `500`: Internal server error
- `502`: Upstream asset service error

## Changes

- **2026-09-13** `51d8e07444e1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fal/apis/platform-apis/changes/assets/entities/:entity_id/patch.md)

---

[API](https://skmtc.dev/fal/apis/platform-apis.md) - [All operations](https://skmtc.dev/fal/apis/platform-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/fal/apis/platform-apis/revisions/3b3b61bedf06?raw)