Biblioteca da comunidade

A API da Biblioteca da comunidade permite explorar o catálogo compartilhado de personagens, locais e objetos da sua instância do Nodaro e clonar uma publicação para a sua própria biblioteca. O catálogo tem curadoria: quem publica são os administradores da instância, e todo usuário com login pode pesquisar, favoritar, clonar e denunciar as publicações.

A biblioteca é um recurso multiusuário. Ela existe no Nodaro Cloud e na Business edition self-hosted. Em uma instância da Community Edition, essas rotas não são registradas e respondem 404. As rotas aceitam um token Bearer: um token de API pessoal (ndr_…), um token de app OAuth (ndr_app_…) ou o token da sua sessão. Veja Autenticação.

Endpoints

O que uma publicação contém

Toda rota de leitura retorna as publicações apenas com estes campos públicos.

Explorar e pesquisar

GET /v1/community/browse retorna { data: Listing[], nextCursor }. Para a próxima página, envie nextCursor de volta como cursor. Ele é null quando não há mais resultados.

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 retorna { data: Listing }, ou 404 not_found quando a publicação não existe ou foi removida. GET /v1/community/favorites retorna { data: Listing[] }.

Clonar uma publicação

POST /v1/community/listings/:id/clone copia uma publicação para a sua biblioteca e retorna { entityType, id }: o tipo e o ID do seu novo personagem, local ou objeto. O corpo é { entityType }, que precisa corresponder ao tipo da publicação.

• É uma cópia, não um vínculo. As imagens e os clipes da publicação são copiados para o seu próprio armazenamento. Alterações posteriores na original, ou a remoção da publicação, não afetam a sua cópia.
• É sua. O clone é um personagem, local ou objeto comum. Renomeie, edite, gere as mídias novamente ou exclua o clone.
• Os nomes não entram em conflito. Quando você já tem um com o mesmo nome, o clone recebe um nome único com um sufixo de cópia.
• Usa o seu armazenamento. Quando a sua conta passa do limite de armazenamento, a clonagem é recusada com 413 storage_limit_exceeded.

Um token de app OAuth precisa do escopo assets:write para clonar. Tokens de API pessoais não precisam de escopo.

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 o novo ID com a API de Personagens, de Locais ou de Objetos.

Favoritar uma publicação

POST /v1/community/listings/:id/favorite alterna o seu favorito e retorna { favorited }: true depois de adicionar e false depois de remover.

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

Denunciar uma publicação

POST /v1/community/listings/:id/report sinaliza uma publicação para a análise dos administradores e retorna { ok: true }. O corpo é { reason }, com um destes valores:

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

Uma publicação pode ser removida após uma denúncia. As cópias que os usuários já clonaram continuam nas bibliotecas deles.

A publicação tem curadoria

O catálogo tem curadoria dos administradores da instância. Publicar um item não faz parte da API pública nem do SDK. Veja Biblioteca da comunidade.

Erros