---
title: "Get one entity with its sheets, looks, links and facets"
method: GET
path: "/v1/entities/{id}"
tags: ["Entities"]
---

# Get one entity with its sheets, looks, links and facets

`GET /v1/entities/{id}`

## Request

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

The entity, its reference set with signed URLs, its baked `sheet` and `items_sheet` (baked on this read when its views changed — free; see EntitySheet), a character's `looks`, its `links` both ways, and `facets` — the other entities it has been photographed with, by how many scans they share. `photo_count` is not repeated here; `facets[].count` is the number that matters.

For a video, prefer `sheet.asset_id` as the reference when the sheet is `ready`: one image carries every view.

Somebody else's id answers `404`, not `403`: the API does not confirm that another user's row exists.

## Response `200`

The entity, its sheets, looks, links and facets

- object: A character, prop, place, skin or look the user reuses, with the canonical reference set that keeps it looking like itself from shot to shot. A look is one outfit or state of a character, with views of its own; its character is `parent_id`. A skin is the garments themselves, with no one in them: it belongs to nobody and is worn by anybody.
  - `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
  - `sheet` EntitySheet: A baked sheet: the entity's views (or, for `items_sheet`, what it wears, carries or includes) composited onto one white sheet, stored as an asset. Pass `asset_id` to `POST /v1/videos` as a `reference_image_ids` entry — one reference instead of loose views. `GET /v1/entities/{id}` bakes a sheet whose views changed before answering — free, and cached by what went in, so a repeat read answers the same asset. `state` says what came back: `ready` is the current sheet; `stale` means the bake failed this time, and `asset_id` and `url` are `null` (read again, or open the entity in the app).
    - `state` 'ready' | 'stale': `ready`: `asset_id` and `url` are the current sheet. `stale`: the bake failed on this read; both are `null`.
    - `asset_id` string, nullable
    - `url` string, uri, nullable: Signed URL, on the usual signing window.
    - `views` integer: `sheet` only: how many views are on it.
    - `items` integer: `items_sheet` only: how many items are on it.
  - `items_sheet` EntitySheet: A baked sheet: the entity's views (or, for `items_sheet`, what it wears, carries or includes) composited onto one white sheet, stored as an asset. Pass `asset_id` to `POST /v1/videos` as a `reference_image_ids` entry — one reference instead of loose views. `GET /v1/entities/{id}` bakes a sheet whose views changed before answering — free, and cached by what went in, so a repeat read answers the same asset. `state` says what came back: `ready` is the current sheet; `stale` means the bake failed this time, and `asset_id` and `url` are `null` (read again, or open the entity in the app).
    - `state` 'ready' | 'stale': `ready`: `asset_id` and `url` are the current sheet. `stale`: the bake failed on this read; both are `null`.
    - `asset_id` string, nullable
    - `url` string, uri, nullable: Signed URL, on the usual signing window.
    - `views` integer: `sheet` only: how many views are on it.
    - `items` integer: `items_sheet` only: how many items are on it.
  - `looks` object[]: A character's looks, by name. Empty for every other kind.
    - `id` string
    - `name` string
    - `thumb_url` string, uri, nullable
  - `links` EntityLink[]
    - `id` string: What `DELETE /v1/entities/{id}/links/{link_id}` takes.
    - `relation` string
    - `direction` 'out' | 'in': `out` when this entity is the subject; `in` when the other end points at it.
    - `label` string: How the relation reads from this side.
    - `to` object
      - `type` string: An entity kind, or `product`.
      - `id` string
      - `name` string
    - `note` string, nullable
  - `facets` EntityFacet[]
    - `entity_type` string
    - `entity_id` string
    - `name` string, nullable: Null when the row it points at has since been deleted.
    - `kind` 'character' | 'prop' | 'location', nullable: The facet's own kind; null for a product.
    - `count` integer: Scans the two share.

## Other responses

- `401`: Missing or invalid token
- `404`: Entity not found
- `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)