Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.marblecms.com/llms.txt

Use this file to discover all available pages before exploring further.

Custom fields let you add your own metadata to every post in a workspace. Instead of forcing everything into tags or description, you can model structured values like release dates, reading levels, priorities, product names, or any internal metadata your team needs.

​
Why use custom fields

  • Extend Marble’s default post schema without changing your frontend code structure each time.
  • Keep metadata consistent across all posts with typed inputs.
  • Return custom field values directly in API responses under a single fields object.

​
Create and manage fields

1

Open Custom Fields

Open your workspace settings, then select the Custom Fields section under the developer settings area.
2

Create a field

Add a field name, key, type, and optional description. Mark it as required if editors must provide a value.
3

Use it in the editor

Open any post and set values in the Metadata tab. Every post can store a value for each custom field.

​
Field types

TypeInput in MarbleAPI value
textMulti-line textstring | null
numberNumeric inputnumber | null
booleanToggle/switchboolean | null
dateDate pickerstring | null (ISO date, e.g. 2026-04-02)
richtextRich text editorstring | null (HTML string)
selectSingle optionstring | null
multiselectMultiple optionsstring[] | null
select and multiselect fields require predefined options. Option values are what you receive in the API.

​
API response shape

Custom fields are exposed on posts as post.fields (single post) and posts[].fields (list posts). In the current public API, custom fields are returned in GET post responses.

​
Example response

{
  "post": {
    "id": "cm9x...",
    "slug": "shipping-custom-fields",
    "title": "Shipping Custom Fields",
    "fields": {
      "release_date": "2026-04-02",
      "priority_score": 7,
      "evergreen": true,
      "target_channels": ["blog", "newsletter"],
      "editor_note": "<p>Republish in Q3</p>"
    }
  }
}

​
Unset fields

If a field exists in your workspace but a post has no value for it yet, Marble returns that key with null. 
{
  "fields": {
    "release_date": null,
    "priority_score": null
  }
}

​
Important behavior

  • Field keys are workspace-scoped and must be unique.
  • Field type and options are effectively schema choices. Plan them early to avoid migration work later.
  • Deleting a field removes that field and its stored values from all posts.