---
title: "List entities"
method: GET
path: "/v1/entities"
tags: ["Entities"]
---

# List entities

`GET /v1/entities`

List built-in actors, products, visual styles, and slideshow themes, followed by the entities available to your team. Built-in entities have `isBuiltIn: true` and cannot be updated or archived. Cursor-paginated; see the [Pagination](/pagination) guide.

## Query parameters

- `entityType` 'ACTOR' | 'PRODUCT' | 'VISUAL_STYLE' | 'SLIDESHOW_THEME'
- `limit` integer
- `cursor` string

## Response `200`

Entity list

- ListEntitiesResponse
  - `entities` Entity[], required
    - `entityId` string, required — The entity id (e.g. `vg_enti_...`).
    - `entityType` 'ACTOR' | 'PRODUCT' | 'VISUAL_STYLE' | 'SLIDESHOW_THEME', required — ACTOR features a consistent character; PRODUCT features a consistent product or object; VISUAL_STYLE guides the look of generated images; SLIDESHOW_THEME is a shared slide design system (fonts, colors, layout) applied to every slide of a slideshow-to-video deck.
    - `name` string, required — Display name.
    - `description` string, required — Optional description. Empty string when not set.
    - `actorConfig` EntityActorConfig — Read-only voice and avatar summary for an ACTOR entity. Always null for non-ACTOR entities.
      - `voiceDisplayName` string, nullable — Display name of the actor's voice when one is configured. Null otherwise.
      - `hasVoice` boolean, required — True when the actor has a configured voice.
      - `hasAvatarPresenter` boolean, required — True when the actor has a built-in presenter or image reference that can be used with `actorEntityId` for avatar generation.
    - `references` EntityReference[], required — Reference images attached to the entity.
      - `fileId` string, required — The reference image file id (e.g. `vg_file_...`). Hydrate it via `GET /v1/files/{fileId}` to fetch a viewable URL.
      - `description` string, required — Optional description of the reference. Empty string when not set.
      - `isDefault` boolean, required — When true, this is the entity's primary reference (used for its thumbnail).
    - `createdAt` integer, required — Seconds since epoch (Unix timestamp) when the entity was created.
    - `updatedAt` integer, required — Seconds since epoch (Unix timestamp) when the entity was last updated.
    - `isBuiltIn` boolean — When true, this is a VideoGen catalog entity. Built-in entities cannot be updated, archived, or have references added or removed.
  - `hasMore` boolean, required — When true, there are more entities available. Pass `nextCursor` as the `cursor` query param to fetch the next page.
  - `nextCursor` string, nullable, required — Opaque cursor to fetch the next page. `null` when `hasMore` is false.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/videogen/apis/videogen-api.md) · [All operations](https://skmtc.dev/videogen/apis/videogen-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/videogen/videogen-api/revisions/33dda0455d67/schema)