---
title: "List characters, props and places"
method: GET
path: "/v1/entities"
tags: ["Entities"]
---

# List characters, props and places

`GET /v1/entities`

## Request

- Base URL: `https://nanostudiopro.com/api`
- URL: `https://nanostudiopro.com/api/v1/entities`
- Auth: HTTP bearer

Every entity you own, ordered by kind then name, each with its reference set and how many photos it is tagged on.

**No `kind` means every kind.** (The app's own screen defaults to characters; the API does not, because an agent asking for entities is asking for all of them.) Looks come back with every kind, each with its `parent_id`; one character's looks are `?kind=look&parent=<id>`.

Light on purpose: sheets, looks and links are on `GET /v1/entities/{id}` only.

## Query parameters

- `kind` 'character' | 'prop' | 'location' | 'look' | 'skin'
- `parent` string

## Response `200`

Every matching entity — the whole set, not a page.

- object
  - `items` Entity[]
    - `id` string
    - `name` string
    - `slug` string
    - `kind` 'character' | 'prop' | 'location' | 'look' | 'skin'
    - `parent_id` string, nullable: A look's character; `null` for every other kind.
    - `photo_count` integer: Distinct scans this entity is tagged on — what the app calls photos. OPTIONAL because it is a list-only field: `GET /v1/entities/{id}` leaves the key out rather than returning a zero, since there `facets[].count` is the number that matters and recounting would cost the detail view a query it never asked for.
    - `refs` object[]: The entity's own views in hand-off order (at most 12): roled views first, in the kind's role order, then the rest as their owner arranged them. A look's are the look's own; its character's are one `parent_id` away.
      - `kind` 'generation' | 'asset'
      - `id` string
      - `role` 'face' | 'front' | 'three_quarter' | 'side' | 'back' | 'wide' | 'angle' | 'detail' | 'null', nullable: Which view this is. `null` for a view with no role.
      - `note` string, nullable: What a detail view shows, in a few words (at most 80 chars).
      - `url` string, uri, nullable: Signed URL to the picture, on the same ~6-hour signing window as every other image URL here. `null` when the picture has since been deleted — the ref keeps its id, so the hole is visible instead of silently closing.
    - `voice` object, nullable: The voice this entity speaks with, when one has been chosen; `null` otherwise.
      - `voice_id` string
      - `voice_name` string: Snapshotted beside the id: the catalogue can be relabelled, a recording cannot.
      - `settings` object
        - `stability` number
        - `similarity_boost` number
        - `style` number
        - `use_speaker_boost` boolean
    - `bio` object, nullable: Free and structured facts; every field optional. Characters use them all; props, places and looks use `description` and `notes`. `null` when none were written.
      - `description` string
      - `logline` string
      - `backstory` string
      - `personality` string
      - `speech` string
      - `role` string
      - `pronouns` string
      - `aliases` string[]
      - `born` string: `YYYY`, `YYYY-MM` or `YYYY-MM-DD`.
      - `nationality` string
      - `occupation` string
      - `height` string
      - `weight` string
      - `world` string: The world they belong to (technology, condition, materials, mood). Canon for anything suggested for them: a mount, an item, a place. A look uses its character's.
      - `notes` string
    - `specs` object, nullable: A prop's or a place's facts, for records and automations (never sent to an image model). `type` is what a prop is; each field's `key` is stable snake_case (`top_speed`, `crew`, `load`, `climate`…), its `value` free text with its unit. `null` when none were written.
      - `type` 'vehicle' | 'creature' | 'object'
      - `fields` object[]
        - `key` string
        - `label` string
        - `value` string
    - `created_at` string, date-time
  - `total` integer

## Other responses

- `400`: `kind` must be character, prop, location or look
- `401`: Missing or invalid token
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api.md) · [All operations](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/revisions/b454211e598e?raw)