Community Library

The Community Library API lets you browse the shared catalog of characters, locations and objects on your Nodaro instance, and clone a listing into your own library. The catalog is curated: the instance's admins publish listings, and every signed-in user can search, favorite, clone and report them.

The library is a multi-user feature. It exists on Nodaro Cloud and on self-hosted Business edition; on a Community edition instance these routes are not registered and answer 404. The routes take a bearer token: a personal API token (ndr_…), an OAuth app token (ndr_app_…) or your session token. See Authentication.

A deployment that does not allow public work serves no listing. GET /v1/community/browse and GET /v1/community/favorites answer empty lists, and a listing's card (GET /v1/community/detail/:slug), its full detail and a clone answer 404 not_found.

Endpoints

What a listing holds

Every read route returns listings with these public fields only.

Browse and search

GET /v1/community/browse returns { data: Listing[], nextCursor }. Pass nextCursor back as cursor for the next page; it is null when there are no more results.

curl "https://app.nodaro.ai/v1/community/browse?entityType=character&sort=popular&limit=20" \
  -H "Authorization: Bearer $NODARO_API_KEY"

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const { data, nextCursor } = await client.community.browse({
  entityType: 'character',
  sort: 'popular',
  limit: 20,
})

{
  "data": [
    {
      "id": "e4b2d8f1-6a3c-4e9b-8d7f-1c5a3e9b2d6f",
      "entity_type": "character",
      "slug": "detective-mara",
      "title": "Detective Mara",
      "description": "Noir-styled investigator",
      "category": "people",
      "style": "realistic",
      "tags": ["noir", "detective"],
      "creator_display_name": "Nodaro Team",
      "preview_media_url": "https://cdn.nodaro.ai/community/detective-mara.png",
      "clone_count": 128,
      "favorite_count": 41,
      "created_at": "2026-08-30T14:02:11Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0zMCJ9"
}

GET /v1/community/detail/:slug returns { data: Listing }, or 404 not_found when the listing does not exist or was taken down. GET /v1/community/favorites returns { data: Listing[] }.

Clone a listing

POST /v1/community/listings/:id/clone copies a listing into your library and returns { entityType, id }: the kind and the id of your new character, location or object. The body is { entityType }, which must match the listing's kind.

• It is a copy, not a link. The listing's images and clips are copied into your own storage. Later changes to the original, or the listing being taken down, do not affect your copy.
• It is yours. The clone is an ordinary character, location or object. Rename it, edit it, regenerate its assets or delete it.
• Names do not collide. When you already have one with the same name, the clone gets the same name followed by a number, such as "Lantern 2".
• It uses your storage. When your account is over its storage limit, the clone is refused with 413 storage_limit_exceeded.

An OAuth app token needs the assets:write scope to clone. Personal API tokens need no scope.

curl -X POST https://app.nodaro.ai/v1/community/listings/e4b2d8f1-6a3c-4e9b-8d7f-1c5a3e9b2d6f/clone \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entityType": "character" }'

const { id } = await client.community.clone(listingId, 'character')
const mara = await client.characters.get(id)

{ "entityType": "character", "id": "5a7c9e1b-3d4f-4a2c-b8e6-9f1d3b5a7c2e" }

Use the new id with the Characters, Locations or Objects API.

Favorite a listing

POST /v1/community/listings/:id/favorite toggles your favorite and returns { favorited }: true after adding it, false after removing it.

const { favorited } = await client.community.favorite(listingId)
const { data: favorites } = await client.community.favorites()

Report a listing

POST /v1/community/listings/:id/report flags a listing for the admins to review and returns { ok: true }. The body is { reason }, one of:

await client.community.report(listingId, 'real_person_no_consent')

A listing can be taken down after a report. Copies that users already cloned stay in their libraries.

Nodaro Keepers: the shared catalog

Nodaro Keepers is a shelf of ready-made characters, creatures, locations and objects that everyone can use. The platform's admins choose the items on it. Like the Community Library, it exists on Nodaro Cloud and on Business edition.

Using an item copies it into your own account, with the same rule as cloning a listing:

• The copy is a row of your own. You can edit it in the Studio, it is listed with your other items, and you can delete it.
• It brings what keeps its renders consistent: the public text, the main image and the variant assets, such as angles, expressions and poses. Every file is copied into your own storage and counts against it.
• Voices: a premade or library voice is carried. A custom or cloned voice is reduced to its name and sample.
• Never carried: the owner's picker selections, reference photos and trained-model fields.
• The original never changes. A later change to it does not reach the copies, and taking it off the shelf removes no copy.

Reading the shelf and copying an item cost no credits.

Read the shelf. GET /v1/keepers/catalog takes kind (character, creature, location or object), limit (1 to 200, default 50) and cursor (a previous page's next). Without kind, the page runs through the kinds in that order. It returns { data, next }. Each item is { id, kind, name, description, imageUrl, previewUrl, category, sort, createdAt }:

• previewUrl is a 480-pixel-wide copy of imageUrl, for a tile.
• category is the shelf heading, and sort is the shelf order: lowest first, then newest first.
• The shelf holds display fields only: never a user id, a prompt, a reference photo or a trained-model field.
• A cursor that cannot be read answers 400 validation_error, never the first page.
• The answer is cached for 60 seconds, so a change to the shelf shows within a minute. One address can read the shelf 60 times a minute, and more answers 429.

Copy an item. POST /v1/keepers/catalog/:kind/:id/copy returns { id, name, kind, created }. id is your own row: read it with GET /v1/characters/:id and the other asset routes. The copy goes into your default project, with a new canvas id.

• One copy per person and item. A second call, or two calls at once, returns the same copy with created: false.
• A copy you archived comes back unarchived.
• A copy you already have stays yours, whether or not the item is still on the shelf.
• An OAuth app token needs the assets:write scope.

# Anyone can read the shelf
curl "https://app.nodaro.ai/v1/keepers/catalog?kind=character&limit=20"

# A signed-in user copies one item
curl -X POST "https://app.nodaro.ai/v1/keepers/catalog/character/$ITEM_ID/copy" \
  -H "Authorization: Bearer $NODARO_API_KEY"

{ "id": "5a7c9e1b-3d4f-4a2c-b8e6-9f1d3b5a7c2e", "name": "Mira", "kind": "character", "created": true }

Every character, creature, location and object read carries its shelf state as catalog, catalogSort and catalogCategory. They are false, 0 and null on your own rows and on every copy.

Publishing is curated

The catalog is curated by the instance's admins. Publishing a listing is not part of the public API or the SDK. See Community Library.

Errors