Custom objects

Custom objects let a site define its own content types: sponsors, instruments, donor tiers, anything the built-in types do not cover. These endpoints expose those definitions and their instances as read-only JSON, so a theme can render custom data in the browser.

Each custom object type has a handle: a stable identifier you set when you create the type. The endpoints below are addressed by that handle.

Custom object types also have an Expose in public API option in Basker. When it is off, the instance endpoints for that handle return 404. The definition endpoints still return the public structure of the type, such as label, handle, and field definitions.

List object definitions

GET {your-domain}/api/custom-object-definitions.json

Returns every custom object type defined on your site, including each handle, label, and the fields it defines.

{
  "docs": [
    {
      "id": "000000000000000000000006",
      "handle": "sponsor",
      "label": "Sponsor",
      "icon": "Award",
      "description": "Partner organizations that support our season",
      "fieldDefinitions": [
        { "name": "tier", "label": "Tier", "type": "text" },
        { "name": "logo", "label": "Logo", "type": "upload", "publicApiPopulation": "summary" },
        { "name": "website", "label": "Website", "type": "text" }
      ]
    }
  ],
  "totalDocs": 1,
  "limit": 100,
  "totalPages": 1,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}

Query parameters

Get one object definition

GET {your-domain}/api/custom-object-definitions/{handle}

Returns one definition by its handle, wrapped in a doc object. Read the definition when you need the field list before you render instances.

{
  "doc": {
    "id": "000000000000000000000006",
    "handle": "sponsor",
    "label": "Sponsor",
    "icon": "Award",
    "description": "Partner organizations that support our season",
    "fieldDefinitions": [
      { "name": "tier", "label": "Tier", "type": "text" },
      { "name": "logo", "label": "Logo", "type": "upload", "publicApiPopulation": "summary" }
    ]
  }
}

List instances of an object type

GET {your-domain}/api/custom-objects/{handle}

Returns the published instances of the custom object type identified by {handle}.

Query parameters

Response

A standard paginated list. Each instance carries a title plus the values for the fields defined on its type, keyed by field name directly on the instance.

{
  "docs": [
    {
      "id": "000000000000000000000007",
      "title": "Remarkable Theatre Supporters Circle",
      "tier": "Principal",
      "website": "https://supporters.remarkable-theatre.example",
      "logo": { "url": "https://..." }
    }
  ],
  "totalDocs": 1,
  "limit": 100,
  "totalPages": 1,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}

The keys match the field names from the type definition. Read the definition first when you need the field list and the labels.

Liquid uses the same shape. A custom object instance reached from a block or relationship field has its fields at the top level, for example tier.website. It has no attributes.custom object.

Relationship response controls

Relationship, media, and file fields on a custom object can set their Public API response shape.

For example, a transportation group might link to many transportation records. Set that relationship field to Reference only when the group endpoint needs the IDs for a map lookup. Set it to Summary when it needs a title and a URL.

Get one instance by ID

GET {your-domain}/api/custom-objects/{handle}/{id}

Returns one instance, wrapped in a doc object, with the same field shape as items in the list response.

Errors

Examples

Render a sponsor wall:

const res = await fetch('/api/custom-objects/sponsor?limit=100');
const { docs } = await res.json();

for (const sponsor of docs) {
  const { title, tier, website, logo } = sponsor;
  // tier, website, logo?.url
}

Find the events tagged with one sponsor, using a custom attribute on the event:

const res = await fetch(`/api/events.json?attributeWhere[custom.sponsor][equals]=${sponsorId}`);
const { docs } = await res.json();

Caching

Responses are cacheable at the edge and refresh when an editor publishes a change to a definition or an instance. Public responses carry Cache-Control: public, s-maxage=3600, max-age=60, stale-while-revalidate=86400, stale-if-error=86400. Keep query parameters stable across visitors so responses stay cacheable.

See also

• Custom objects: define custom content types from the admin.
• Custom data: when to use custom objects rather than custom attributes.
• Content endpoints: read the built-in content types, and filter them.