> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# List entities

GET https://api.videogen.io/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.

Reference: https://docs.videogen.io/rest-api-reference/entities/list-entities

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Query parameters

- `entityType` (enum, optional) — When provided, returns only entities of this type. Omit to return all entities.
  - Allowed values: `ACTOR`, `PRODUCT`, `VISUAL_STYLE`, `SLIDESHOW_THEME`
- `limit` (integer, optional, default: 50) — Maximum number of items to return in the page. Defaults to 50; capped at 200. See [Pagination](/pagination).
- `cursor` (string, optional) — Opaque pagination cursor returned as `nextCursor` by the previous page. Omit on the first request. Cursors are tied to the endpoint that produced them and must be passed unmodified. See [Pagination](/pagination).

## Response

### 200

Entity list

- `entities` (list of Entity, required)
- `hasMore` (boolean, required) — When true, there are more entities available. Pass `nextCursor` as the `cursor` query param to fetch the next page.
- `nextCursor` (string, required, nullable) — Opaque cursor to fetch the next page. `null` when `hasMore` is false.

## Types

### Entity

A reusable actor, product, visual style, or slideshow theme. Attach its reference images to workflows for consistent characters, looks, and slide designs.

- `entityId` (string, required) — The entity id (e.g. `vg_enti_...`).
- `entityType` (enum, 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.
  - Allowed values: `ACTOR`, `PRODUCT`, `VISUAL_STYLE`, `SLIDESHOW_THEME`
- `name` (string, required) — Display name.
- `description` (string, required) — Optional description. Empty string when not set.
- `references` (list of EntityReference, required) — Reference images attached to the entity.
- `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.
- `actorConfig` (EntityActorConfig, optional, nullable) — Voice and presenter summary for ACTOR entities. Null for non-ACTOR entities.
- `isBuiltIn` (boolean, optional) — When true, this is a VideoGen catalog entity. Built-in entities cannot be updated, archived, or have references added or removed.

### EntityReference

A file attached to an entity as a reference image.

- `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).

### EntityActorConfig

Read-only voice and avatar summary for an ACTOR entity. Always null for non-ACTOR entities.

- `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.
- `voiceDisplayName` (string, optional, nullable) — Display name of the actor's voice when one is configured. Null otherwise.

## Examples

**Response**

```json
{
  "entities": [
    {
      "entityId": "vg_enti_a1b2c3d4e5f6",
      "entityType": "ACTOR",
      "name": "Maya the host",
      "description": "Friendly on-camera host for product explainers.",
      "references": [
        {
          "fileId": "vg_file_obLD1OX2eJCrEs0071Z4kA",
          "description": "Front-facing headshot, neutral background.",
          "isDefault": true
        }
      ],
      "createdAt": 1779537600,
      "updatedAt": 1779537870,
      "actorConfig": {
        "hasVoice": true,
        "hasAvatarPresenter": true,
        "voiceDisplayName": "Matilda"
      },
      "isBuiltIn": false
    },
    {
      "entityId": "vg_enti_f6e5d4c3b2a1",
      "entityType": "VISUAL_STYLE",
      "name": "Pastel watercolor",
      "description": "Soft pastel watercolor look for lifestyle clips.",
      "references": [
        {
          "fileId": "vg_file_jzosm31OGi-bPE1eb3qLnA",
          "description": "",
          "isDefault": true
        }
      ],
      "createdAt": 1779268500,
      "updatedAt": 1779268500,
      "actorConfig": null,
      "isBuiltIn": false
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

**SDK Code**

```python
import requests

url = "https://api.videogen.io/v1/entities"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```