---
title: "Link an entity to another"
method: POST
path: "/v1/entities/{id}/links"
tags: ["Entities"]
---

# Link an entity to another

`POST /v1/entities/{id}/links`

## Request

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

One asserted relation FROM this entity, checked by the app's rules: `wears`, `carries` (character, look or skin to a prop, product or skin), `owns`, `includes`, `rides` (to a prop or character), `lives_in`, `born_in` (single: a new one replaces the old), `found_in`, `interior` (prop to place), `family_of`, `friend_of`, `enemy_of`, `works_for`, `related_to` (character to character). The target is yours and of the kind `to_type` names. Idempotent: a repeat answers `200` with the link that already says it; a new one is `201`. Free.

## Request body

- object
  - `relation` string, required
  - `to_type` 'character' | 'prop' | 'location' | 'skin' | 'product', required
  - `to_id` string, required
  - `note` string, nullable

## Response `200`

The link already existed

- object
  - `link` EntityLink: A relation asserted in the app — what it wears or carries, where it lives, who it is family of — read from this entity's side.
    - `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

## Other responses

- `201`: The link was made
- `400`: A prop cannot wear
- `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/7f7d4a72b17c?raw)