Skip to main content
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.
You can also manage field definitions through the API, SDK, or MCP server. Agents should call get_fields before writing post field values, create any missing field with create_field, then pass values under fields when creating or updating a post.

​
Field types

select and multiselect fields require predefined options. Option values are what you receive in the API and what you send when writing post values.

​
Writing fields through the API

Create field definitions first:
Then pass values by field key when creating or updating posts:
Unknown field keys, wrong value types, and option values that do not match a configured select or multiselect option are rejected with 400 responses.

​
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

​
Unset fields

If a field exists in your workspace but a post has no value for it yet, Marble returns that key with null.

​
Important behavior

  • Field keys are workspace-scoped and must be unique.
  • Post writes never create fields implicitly. Create or update field definitions first, then write values to posts.
  • 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.