Paillette
Reference/Start/Overview

Paillette API

Resolve a source, search or translate through REST, and manage artwork records and collections with provenance-aware metadata.

Basehttps://paillette-api.berlayar.ai/api/v1AuthX-API-KeySourcengs

Authentication

Server-to-server calls use X-API-Key. Public source discovery and collection reads work without a key; search, artwork lookup, translation, extract, and management writes require one.

MCP clients connect to /api/v1/mcp using Streamable HTTP JSON-RPC. Protected resource metadata is exposed at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/api/v1/mcp.

API keys can call all available MCP tools. OAuth tokens need mcp:all or matching grouped scopes such as mcp:read, mcp:write, artworks:read, collections:write, translations:create, or extract:create.

Field sources

Search results include normalized metadata plus source labels. Check these fields before displaying catalogue text or citations.

results[].metadata.description
stringoptional

Verified Roots/NHB catalogue caption selected for display when available. NGS Art+ payload descriptions are retained in source_records, not exposed as public caption text.

results[].metadata.field_sources
Record<string, string>optional

Per-field source labels, for example description: roots or title: ngs.

results[].metadata.source_provenance
Record<string, { source, ref, type }>optional

Source URLs used for normalized fields, including Roots/NHB refs where a Roots caption is used.

results[].metadata.source_records.ngs
object | nulloptional

Original NGS source payload excerpt. This is useful for catalogue fields, identifiers, credit lines, and NGS image/detail refs.

GET/api/v1/orgspublic

List sources

List public sources and the keys used in REST paths and MCP arguments.

Path0 fields

No path fields.

Body1 field
limit
integerdefault20

Optional query param. Range: 1-100.

Response3 fields
data[].key
stringoptional

Short source key used in search paths and MCP arguments.

data[].slug
stringoptional

Canonical public source slug.

metadata.total
integeroptional

Total number of sources available to the caller.

GET/api/v1/orgs/slug/{slug}public

Lookup source

Resolve a source by canonical slug before building source-specific calls.

Path1 field
slug
stringrequired

Path param. Source slug, for example national-gallery-singapore.

Body0 fields

No body fields.

Response3 fields
data[].key
stringoptional

Short source key used in search paths and MCP arguments.

data[].slug
stringoptional

Canonical public source slug.

metadata.total
integeroptional

Total number of sources available to the caller.

POST/api/v1/orgspublicsample only

Create source

Create a source owned by the authenticated principal. The generated source API key is returned only on creation.

Path0 fields

No path fields.

Body4 fields
name
stringrequired

Source display name.

slug
stringoptional

Optional stable URL/API slug. Generated from name if omitted.

description
stringoptional

Optional public or internal description.

website
stringoptional

Optional source website URL.

Response3 fields
data.id
stringoptional

Created source ID.

data.slug
stringoptional

Created source slug.

data.api_key
stringoptional

Generated source API key. Returned only on creation.

POST/api/v1/orgs/{orgKey}/search/textrequires key

Text search

Natural-language search against a source's text embeddings.

Path1 field
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

Body3 fields
query
stringrequired

Natural-language search query. 1-500 characters.

topK
integerdefault10

Maximum result count. Range: 1-100.

minScore
numberdefault0.7

Similarity floor accepted by the API. Range: 0-1.

Response11 fields
count
integeroptional

Number of ranked results returned.

queryTime
integeroptional

Server-side query time in milliseconds.

results[].similarity
numberoptional

Cosine similarity score. Higher is closer.

results[].metadata.description
stringoptional

Verified Roots/NHB catalogue caption selected for display when available. NGS Art+ payload descriptions are retained in source_records, not exposed as public caption text.

results[].metadata.field_sources
Record<string, string>optional

Per-field source labels, for example description: roots or title: ngs.

results[].metadata.source_provenance
Record<string, { source, ref, type }>optional

Source URLs used for normalized fields, including Roots/NHB refs where a Roots caption is used.

results[].metadata.source_records.ngs
object | nulloptional

Original NGS source payload excerpt. This is useful for catalogue fields, identifiers, credit lines, and NGS image/detail refs.

results[].metadata.source_records.roots
object | nulloptional

Verified Roots/NHB source payload excerpt. Use caption when present; it is not labelled as NGS text.

results[].metadata.generated_caption.text
string | nulloptional

Generated visual caption used for semantic retrieval/debugging. Includes model, prompt version, generated time, and source URLs.

results[].metadata.search_sources
Array<{ channel, source, weight, rank, score }>optional

Search provenance for hybrid results. Generated-caption vector hits are labelled generated_caption_embedding and source custom_metadata.generated_caption.text.

results[].metadata.classification
string | nulloptional

Optional source catalogue classification from the ingestion DB. Treat as secondary metadata, not a universal object type.

POST/api/v1/orgs/{orgKey}/search/imagerequires key

Image search

Multipart image search against a source's visual embeddings.

Path1 field
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

Body3 fields
image
Filerequired

Multipart image file. Allowed: JPEG, PNG, WebP.

topK
integerdefault10

Maximum result count. Range: 1-100.

minScore
numberdefault0.7

Similarity floor for image-vector matches. Range: 0-1.

Response11 fields
count
integeroptional

Number of ranked results returned.

queryTime
integeroptional

Server-side query time in milliseconds.

results[].similarity
numberoptional

Cosine similarity score. Higher is closer.

results[].metadata.description
stringoptional

Verified Roots/NHB catalogue caption selected for display when available. NGS Art+ payload descriptions are retained in source_records, not exposed as public caption text.

results[].metadata.field_sources
Record<string, string>optional

Per-field source labels, for example description: roots or title: ngs.

results[].metadata.source_provenance
Record<string, { source, ref, type }>optional

Source URLs used for normalized fields, including Roots/NHB refs where a Roots caption is used.

results[].metadata.source_records.ngs
object | nulloptional

Original NGS source payload excerpt. This is useful for catalogue fields, identifiers, credit lines, and NGS image/detail refs.

results[].metadata.source_records.roots
object | nulloptional

Verified Roots/NHB source payload excerpt. Use caption when present; it is not labelled as NGS text.

results[].metadata.generated_caption.text
string | nulloptional

Generated visual caption used for semantic retrieval/debugging. Includes model, prompt version, generated time, and source URLs.

results[].metadata.search_sources
Array<{ channel, source, weight, rank, score }>optional

Search provenance for hybrid results. Generated-caption vector hits are labelled generated_caption_embedding and source custom_metadata.generated_caption.text.

results[].metadata.classification
string | nulloptional

Optional source catalogue classification from the ingestion DB. Treat as secondary metadata, not a universal object type.

POST/api/v1/orgs/{orgKey}/search/colorrequires key

Colour search

Find artworks whose extracted palettes match one or more hex colours.

Path1 field
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

Body4 fields
colors
string[]required

Hex colours. Pattern: #RRGGBB. Min 1, max 5.

matchMode
"any" | "all"defaultany

Whether any colour or every colour must match.

threshold
numberdefault10

DeltaE distance threshold. Range: 0-30.

limit
integerdefault20

Maximum result count. Range: 1-100.

Response11 fields
count
integeroptional

Number of ranked results returned.

queryTime
integeroptional

Server-side query time in milliseconds.

results[].similarity
numberoptional

Cosine similarity score. Higher is closer.

results[].metadata.description
stringoptional

Verified Roots/NHB catalogue caption selected for display when available. NGS Art+ payload descriptions are retained in source_records, not exposed as public caption text.

results[].metadata.field_sources
Record<string, string>optional

Per-field source labels, for example description: roots or title: ngs.

results[].metadata.source_provenance
Record<string, { source, ref, type }>optional

Source URLs used for normalized fields, including Roots/NHB refs where a Roots caption is used.

results[].metadata.source_records.ngs
object | nulloptional

Original NGS source payload excerpt. This is useful for catalogue fields, identifiers, credit lines, and NGS image/detail refs.

results[].metadata.source_records.roots
object | nulloptional

Verified Roots/NHB source payload excerpt. Use caption when present; it is not labelled as NGS text.

results[].metadata.generated_caption.text
string | nulloptional

Generated visual caption used for semantic retrieval/debugging. Includes model, prompt version, generated time, and source URLs.

results[].metadata.search_sources
Array<{ channel, source, weight, rank, score }>optional

Search provenance for hybrid results. Generated-caption vector hits are labelled generated_caption_embedding and source custom_metadata.generated_caption.text.

results[].metadata.classification
string | nulloptional

Optional source catalogue classification from the ingestion DB. Treat as secondary metadata, not a universal object type.

GET/api/v1/orgs/{orgKey}/artworks/{artworkId}requires key

Artwork lookup

Fetch one artwork record with source-labelled metadata and imagery.

Path2 fields
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

artworkId
stringrequired

Artwork ID returned by search endpoints.

Body0 fields

No body fields.

Response4 fields
id
stringoptional

Artwork identifier returned by search endpoints.

title
stringoptional

Display title from the source record.

metadata.field_sources
Record<string, string>optional

Per-field source labels for normalized catalogue metadata.

metadata.source_records
objectoptional

Original source payload excerpts used during normalization.

GET/api/v1/orgs/{orgKey}/collectionspublicsample only

List collections

List collections in a source. This route is public for public sources.

Path1 field
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

Body0 fields

No body fields.

Response5 fields
data[].id
stringoptional

Collection ID for list responses.

data.id
stringoptional

Collection ID for single-record responses.

data.name
stringoptional

Collection display name.

data.artwork_count
integeroptional

Number of artworks currently attached to the collection.

data.thumbnail_artwork_id
string | nulloptional

Artwork used as the collection thumbnail, when set.

POST/api/v1/orgs/{orgKey}/collectionspublicsample only

Create collection

Create a collection in a source. Provide an id when clients need stable collection IDs.

Path1 field
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

Body4 fields
id
stringoptional

Optional stable collection ID. Generated when omitted.

name
stringrequired

Collection display name.

description
string | nulloptional

Optional collection description.

thumbnail_artwork_id
string | nulloptional

Optional artwork ID used as the collection thumbnail.

Response5 fields
data[].id
stringoptional

Collection ID for list responses.

data.id
stringoptional

Collection ID for single-record responses.

data.name
stringoptional

Collection display name.

data.artwork_count
integeroptional

Number of artworks currently attached to the collection.

data.thumbnail_artwork_id
string | nulloptional

Artwork used as the collection thumbnail, when set.

POST/api/v1/orgs/{orgKey}/collections/upsertrequires keysample only

Upsert collection

Create or update a collection by stable id. The response includes a created flag.

Path1 field
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

Body4 fields
id
stringoptional

Optional stable collection ID. When present, matching collections are updated.

name
stringrequired

Collection display name.

description
string | nulloptional

Optional collection description.

thumbnail_artwork_id
string | nulloptional

Optional artwork ID used as the collection thumbnail.

Response3 fields
data.created
booleanoptional

True when a new collection was inserted; false when updated.

data.collection.id
stringoptional

Created or updated collection ID.

data.collection.name
stringoptional

Collection display name.

GET/api/v1/orgs/{orgKey}/collections/{collectionId}publicsample only

Collection lookup

Fetch one collection scoped to the source.

Path2 fields
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

collectionId
stringrequired

Collection ID returned by list/create/upsert.

Body0 fields

No body fields.

Response5 fields
data[].id
stringoptional

Collection ID for list responses.

data.id
stringoptional

Collection ID for single-record responses.

data.name
stringoptional

Collection display name.

data.artwork_count
integeroptional

Number of artworks currently attached to the collection.

data.thumbnail_artwork_id
string | nulloptional

Artwork used as the collection thumbnail, when set.

PATCH/api/v1/orgs/{orgKey}/collections/{collectionId}publicsample only

Update collection

Patch collection metadata scoped to the source.

Path2 fields
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

collectionId
stringrequired

Collection ID to update.

Body3 fields
name
stringoptional

Updated collection display name.

description
string | nulloptional

Updated collection description.

thumbnail_artwork_id
string | nulloptional

Updated thumbnail artwork ID.

Response5 fields
data[].id
stringoptional

Collection ID for list responses.

data.id
stringoptional

Collection ID for single-record responses.

data.name
stringoptional

Collection display name.

data.artwork_count
integeroptional

Number of artworks currently attached to the collection.

data.thumbnail_artwork_id
string | nulloptional

Artwork used as the collection thumbnail, when set.

DELETE/api/v1/orgs/{orgKey}/collections/{collectionId}publicsample only

Delete collection

Delete a collection scoped to the source.

Path2 fields
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

collectionId
stringrequired

Collection ID to delete.

Body0 fields

No body fields.

Response2 fields
success
booleanoptional

Whether the delete completed successfully.

data.id
stringoptional

Deleted or detached resource ID, when returned.

POST/api/v1/orgs/{orgKey}/artworks/upsertrequires keysample only

Upsert artwork record

Create or update an artwork record by id, source record id, or accession number. The response includes a created flag.

Path1 field
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

Body17 fields
id
stringoptional

Optional stable artwork ID.

collection_id
string | nulloptional

Optional source collection/group ID.

title
stringoptional

Artwork title. Required when creating a new record.

artist
string | nulloptional

Artist or maker display name.

year
integer | nulloptional

Normalized production year.

date_text
string | nulloptional

Source date text when a precise year is unavailable.

medium
string | nulloptional

Medium or materials text.

description
string | nulloptional

Catalogue description or caption.

accession_number
string | nulloptional

Accession or object number. Used as an upsert match key.

source_institution
string | nulloptional

Institution or system that supplied the source record.

source_collection
string | nulloptional

Source collection name.

source_record_id
string | nulloptional

Source system record ID. Used as an upsert match key.

source_url
string | nulloptional

Canonical source record URL.

image_url
string | nulloptional

Primary artwork image URL.

thumbnail_url
string | nulloptional

Thumbnail image URL.

field_sources
objectoptional

Optional per-field provenance labels.

custom_metadata
objectoptional

Optional source-specific metadata payload.

Response3 fields
data.created
booleanoptional

True when a new artwork was inserted; false when updated.

data.artwork.id
stringoptional

Created or updated artwork ID.

data.artwork.metadata
objectoptional

Normalized artwork metadata, including source fields.

PATCH/api/v1/orgs/{orgKey}/artworks/{artworkId}requires keysample only

Update artwork

Patch artwork metadata scoped to the source.

Path2 fields
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

artworkId
stringrequired

Artwork ID to update.

Body4 fields
title
stringoptional

Updated artwork title.

artist
string | nulloptional

Updated artist or maker display name.

medium
string | nulloptional

Updated medium or materials text.

description
string | nulloptional

Updated catalogue description or caption.

Response4 fields
id
stringoptional

Artwork identifier returned by search endpoints.

title
stringoptional

Display title from the source record.

metadata.field_sources
Record<string, string>optional

Per-field source labels for normalized catalogue metadata.

metadata.source_records
objectoptional

Original source payload excerpts used during normalization.

DELETE/api/v1/orgs/{orgKey}/artworks/{artworkId}requires keysample only

Delete artwork

Soft-delete an artwork scoped to the source.

Path2 fields
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

artworkId
stringrequired

Artwork ID to delete.

Body0 fields

No body fields.

Response2 fields
success
booleanoptional

Whether the delete completed successfully.

data.id
stringoptional

Deleted or detached resource ID, when returned.

POST/api/v1/orgs/{orgKey}/collections/{collectionId}/artworksrequires keysample only

Add artwork to collection

Attach an artwork to a collection. Collection and artwork must belong to the same source.

Path2 fields
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

collectionId
stringrequired

Collection ID to update.

Body2 fields
artwork_id
stringrequired

Artwork ID from the same source.

position
integerdefault0

Sort position within the collection.

Response3 fields
data.collection_id
stringoptional

Collection ID that was changed.

data.artwork_id
stringoptional

Artwork ID that was added or removed.

data.position
integeroptional

Stored position for add operations.

DELETE/api/v1/orgs/{orgKey}/collections/{collectionId}/artworks/{artworkId}requires keysample only

Remove artwork from collection

Remove a collection membership without deleting the collection or artwork.

Path3 fields
orgKey
stringrequired

Source key from GET /orgs. Use ngs for National Gallery Singapore.

collectionId
stringrequired

Collection ID to update.

artworkId
stringrequired

Artwork ID to remove from the collection.

Body0 fields

No body fields.

Response3 fields
data.collection_id
stringoptional

Collection ID that was changed.

data.artwork_id
stringoptional

Artwork ID that was added or removed.

data.position
integeroptional

Stored position for add operations.

POST/api/v1/translate/textrequires key

Translate text

Translate English catalogue text to Chinese, Malay, or Tamil.

Path0 fields

No path fields.

Body3 fields
text
stringrequired

English source text. 1-50,000 characters.

sourceLang
"en"required

Only English source text is accepted.

targetLang
"zh" | "ms" | "ta"required

Chinese, Malay, or Tamil.

Response4 fields
translatedText
stringoptional

Translated output in the requested target language.

provider
stringoptional

Translation provider used for the response.

cached
booleanoptional

Whether the response came from translation cache.

usage.remaining
integeroptional

Free translations remaining after the request, when returned.

POST/api/v1/extractrequires key

Extract image

Extract image objects from public image URLs. target=object is the default for preserving mounted artworks, scrolls, and visible supports. Live jobs use fal SAM3 when configured. Free accounts get 10 submitted inputs lifetime.

Path0 fields

No path fields.

Body6 fields
imageUrls
string[]required

Public image URLs. Each submitted URL or uploaded file counts against the free lifetime /extract allowance.

target
"object" | "content"defaultobject

object preserves the visible artwork object/support. content is experimental and crops tighter.

preserveFilenames
booleandefaulttrue

Preserve source filenames in generated outputs.

filenamePrefix
stringoptional

Optional prefix when not preserving source names.

filenameSuffix
stringoptional

Optional suffix when not preserving source names.

preview
booleandefaultfalse

Request lightweight preview outputs with the job.

Response7 fields
id
stringoptional

Extract job ID.

status
"pending" | "queued" | "processing" | "completed" | "failed"optional

Current job state.

target
"object" | "content"optional

Requested extract target.

counts.inputs
integeroptional

Number of submitted images or archive inputs.

downloadUrl
string | nulloptional

Zip download URL once the job is completed.

usage.remaining
integeroptional

Free /extract inputs remaining after job creation, when returned.

warnings[]
stringoptional

Non-fatal job warnings such as a missing worker dispatch config.

MCP client config

Point the client at /api/v1/mcp and send the same API key used for REST calls. OAuth clients can also discover protected resource metadata from /.well-known/oauth-protected-resource/api/v1/mcp.

API keys can call all exposed tools. OAuth tokens need mcp:all or matching grouped scopes such as mcp:read, mcp:write, artworks:read, collections:write, translations:create, or extract:create.

mcpServers

{
  "mcpServers": {
    "paillette": {
      "url": "https://paillette-api.berlayar.ai/api/v1/mcp",
      "headers": {
        "X-API-Key": "plt_stg_your_api_key"
      }
    }
  }
}

MCP tool reference

search_artworks

Natural-language artwork search across a source.

orgId
stringdefaultngs

Optional source key, slug, or UUID. Use ngs for National Gallery Singapore.

collection
stringdefaultngs

Optional alias for orgId.

query
stringrequired

Natural-language search query.

topK
integerdefault10

Maximum result count. Range: 1-100.

minScore
numberdefault0.3

Similarity floor. Range: 0-1.

list_orgs

List source organisations and their short keys before calling search tools.

limit
integerdefault20

Optional. Range: 1-100.

lookup_artwork

Fetch one artwork by ID with public catalogue metadata.

orgId
stringdefaultngs

Optional source key, slug, or UUID. Use ngs for National Gallery Singapore.

collection
stringdefaultngs

Optional alias for orgId.

artworkId
stringrequired

Artwork ID returned by search_artworks.

list_collections

List collections for a source.

orgId
stringdefaultngs

Optional source key, slug, or UUID. Use ngs for National Gallery Singapore.

collection
stringdefaultngs

Optional alias for orgId.

upsert_collection

Create or update a collection. Provide collectionId for idempotent writes.

orgId
stringdefaultngs

Optional source key, slug, or UUID. Use ngs for National Gallery Singapore.

collection
stringdefaultngs

Optional alias for orgId.

collectionId
stringoptional

Optional stable collection ID.

name
stringrequired

Collection display name.

description
string | nulloptional

Optional collection description.

thumbnailArtworkId
string | nulloptional

Optional artwork ID used as the thumbnail.

upsert_artwork_record

Create or update artwork metadata by id, source record id, or accession number.

orgId
stringdefaultngs

Optional source key, slug, or UUID. Use ngs for National Gallery Singapore.

collection
stringdefaultngs

Optional alias for orgId.

id
stringoptional

Optional stable artwork ID.

collectionId
string | nulloptional

Optional source collection/group ID.

title
stringoptional

Artwork title. Required when creating a new record.

artist
string | nulloptional

Artist or maker display name.

year
integer | nulloptional

Normalized production year.

medium
string | nulloptional

Medium or materials text.

description
string | nulloptional

Catalogue description or caption.

accessionNumber
string | nulloptional

Accession or object number.

sourceRecordId
string | nulloptional

Source system record ID.

sourceUrl
string | nulloptional

Canonical source record URL.

add_artwork_to_collection

Attach an artwork record to a collection in the same source.

orgId
stringdefaultngs

Optional source key, slug, or UUID. Use ngs for National Gallery Singapore.

collection
stringdefaultngs

Optional alias for orgId.

collectionId
stringrequired

Collection ID to update.

artworkId
stringrequired

Artwork ID to add.

position
integerdefault0

Sort position within the collection.

remove_artwork_from_collection

Detach an artwork record from a collection without deleting the artwork.

orgId
stringdefaultngs

Optional source key, slug, or UUID. Use ngs for National Gallery Singapore.

collection
stringdefaultngs

Optional alias for orgId.

collectionId
stringrequired

Collection ID to update.

artworkId
stringrequired

Artwork ID to remove.

colour_search

Find artworks by extracted palette proximity.

orgId
stringdefaultngs

Optional source key, slug, or UUID. Use ngs for National Gallery Singapore.

collection
stringdefaultngs

Optional alias for orgId.

colors
string[]required

Hex colours. Pattern: #RRGGBB. Min 1, max 8.

matchMode
"any" | "all"defaultany

Whether any colour or every colour must match.

threshold
numberdefault18

Palette distance threshold. Range: 0-441.7.

limit
integerdefault10

Maximum result count. Range: 1-100.

translate_text

Translate English text to Chinese, Malay, or Tamil.

text
stringrequired

English source text. 1-50,000 characters.

sourceLang
"en"defaulten

Optional. Only English source text is accepted.

targetLang
"zh" | "ms" | "ta"required

Chinese, Malay, or Tamil.

extract_images

Create an /extract job from image URLs. target defaults to object. Counts against the lifetime /extract allowance.

imageUrls
string[]required

Public image URLs. Min 1, max 50.

target
"object" | "content"defaultobject

Use object for mounted artworks and scrolls.

preserveFilenames
booleandefaulttrue

Preserve source filenames in generated outputs.

returnPreview
booleandefaultfalse

Request preview outputs with the job.

API keys

Sign in to create keys and run live requests.

Key management is tied to your Paillette account. The top-bar key input stays available for pasted keys.

Usage & billing

Search API todaySign in
Free translationsSign in
Free /extractSign in