Discover fields & options

Ask the API what blocks, theme settings, and custom attributes a collection supports — so you can build valid writes without guessing

Every collection's blocks, theme settings, and custom attributes are specific to the tenant and its theme. Rather than hard-coding field names or guessing valid values, ask the API first. Each mutation endpoint has a matching read-only …/schema endpoint that describes exactly what you can write.

The workflow

Discover → create → mutate. Read the schema once, then construct your create/block/settings/attribute writes from it.

The schema endpoints

Endpoint	Describes
`GET /{version}/{tenant}/{collection}/blocks/schema`	The block types available and each block's fields
`GET /{version}/{tenant}/{collection}/theme-settings/schema`	A record's theme settings (for its template)
`GET /{version}/{tenant}/{collection}/custom-attributes/schema`	A collection's custom attributes
`GET /{version}/{tenant}/theme/settings/schema`	The theme's site-wide settings

curl -H "Authorization: users API-Key a1b2c3d4-…" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events/custom-attributes/schema"

What a field looks like

Every field comes back in a uniform shape, so one piece of code can handle them all:

{
  "key": "theme_color",        // the name to use in your write
  "type": "select",            // text · richText · number · checkbox · select · date ·
                               // relationship · upload · customObject · array · group
  "label": "Theme Color",
  "options": [                 // present for select / radio — use one of these values
    { "value": "azure", "label": "Azure" },
    { "value": "midnight", "label": "Midnight" }
  ],
  "relationTo": "media",        // present for relationship / upload
  "customObjectType": "genre",  // present for customObject — the type to link
  "hasMany": false,
  "fields": [ /* nested fields, present for array / group */ ]
}

options lists the only valid values for a select/radio — send one of them exactly.
customObjectType tells you which custom-objects a customObject field links to (see below).
fields recurses for array and group types, describing each sub-field.

Building values from the schema

Use the field's type to construct its value:

`type`	Send
`text`, `textarea`, `email`	a string
`richText`	an HTML string (or `<key>_html`)
`number`	a number
`checkbox`	a boolean
`select`, `radio`	one of the field's `options` values
`date`	an ISO 8601 string
`relationship`, `upload`	an id (or an array of ids when `hasMany`)
`customObject`	a custom-object instance id (or an array when `hasMany`)
`array`	a list of objects shaped by the field's nested `fields`
`group`	an object shaped by the field's nested `fields`

Linking custom-objects

A customObject field links to instances of the type named in customObjectType. List the matching instances, then set their id(s):

# the schema said: { "key": "genres", "type": "customObject", "customObjectType": "genre", "hasMany": true }
curl -H "Authorization: users API-Key a1b2c3d4-…" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/custom-object-instances?where[definition.handle][equals]=genre"
# → pick an id, then: "set": { "genres": ["<instance-id>"] }

Instances may belong to your tenant or, if your tenant is in a tenant group, to another member that shares them — both are listed and both can be linked. If no instances of that type exist anywhere in scope, the field simply can't be linked yet.

Next steps

Edit content blocks — apply the block/theme-settings schema you just read.
Field selection — trim what a read returns.