Skip to content

Metafields

Metafields are powerful components that can be added to Objects and Object Types. Metafields added to Object Types will be default for all new Objects in the type.

Endpoints

GET /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields
GET /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields/:key
POST /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields
PATCH /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields/:key
DELETE /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields/:key

Data Model

ParameterRequiredTypeDescription
typerequiredEnumtext, textarea, html-textarea, select-dropdown, object, objects, file, date, radio-buttons, check-boxes, repeater, parent, markdown, json, switch, number
titlerequiredStringYour Metafield title
keyrequiredStringUnique identifier for your Metafield
valuevariesVaries by typeMetafield value. Property required to be present (empty string ok) except for repeater and parent (should not be present). See example model below for various value types and requirements.
requiredBoolA value is required
regexStringRestrict the value to match a regular expresssion
regex_messageStringThe message displayed when the value fails the regex
minlengthNumberAdd minlength to text or textarea Metafields
maxlengthNumberAdd maxlength to text or textarea Metafields
optionsRequired for options, radio, checkbox and switchVaries by typeArray of options for select, radio, and checkbox Metafields and string for switch Metafield with possible values true,false and yes,no
childrenArrayArray of nested Metafields
object_typeStringValid Object Type slug. Applies only to object and objects Metafield
repeater_fieldsArrayArray of nested Metafields. Applies only to repeater Metafield

Example Metafields

{
  "metafields": [
    {
      "type": "text",
      "title": "Headline",
      "key": "headline",
      "value": "3030 Palo Alto Blvd.",
      "required": true
    },
    {
      "type": "textarea",
      "title": "Basic Text",
      "key": "basic_text",
      "value": "This home is a must see!",
      "required": true
    },
    {
      "type": "html-textarea",
      "title": "Extended Text",
      "key": "extended_text",
      "value": "<p>Some <strong>HTML content</strong> for <em>dramatic</em> effect!</p>"
    },
    {
      "type": "markdown",
      "title": "Markdown Text",
      "key": "markdown_text",
      "value": "# Hello World!"
    },
    {
      "type": "select-dropdown",
      "title": "State",
      "key": "state",
      "value": "California",
      "options": [
        {
          "key": "CA",
          "value": "California"
        },
        {
          "key": "TX",
          "value": "Texas"
        }
      ]
    },
    {
      "type": "object",
      "title": "Pages",
      "key": "pages",
      "object_type": "pages",
      "value": "5a4806974fa85fc8a7000002" // Object ID
    },
    {
      "type": "objects",
      "title": "Other Listings",
      "key": "other_listings",
      "object_type": "listings",
      "value": "5a4806974fa85fc8a7000007,5a4806974fa85fc8a7000008" // Comma-separated Object IDs
    },
    {
      "type": "file",
      "title": "Hero",
      "key": "hero",
      "value": "media-name-property-in-bucket.jpg" // This is the name of your media. Gets converted to url and imgix_url automatically
    },
    {
      "type": "date",
      "title": "Listing Start Date",
      "key": "listing_start_date",
      "value": "2020-10-15"
    },
    {
      "type": "json",
      "title": "JSON Data",
      "key": "json_data",
      "value": {
        "strings": "cheese",
        "arrays": ["Bradbury", "Charles", "Ramono", "the last Jedi", "Liotta"],
        "objects": {
          "bools": true,
          "nestable": true
        }
      }
    },
    {
      "type": "radio-buttons",
      "title": "Deposit Required",
      "key": "deposit_required",
      "value": "The Other",
      "options": [
        {
          "value": "This"
        },
        {
          "value": "That"
        },
        {
          "value": "The Other"
        }
      ]
    },
    {
      "type": "check-boxes",
      "title": "Amenities",
      "key": "amenities",
      "value": ["Pool", "Gym"],
      "options": [
        {
          "value": "Pool"
        },
        {
          "value": "Gym"
        },
        {
          "value": "Landscaping"
        }
      ]
    },
    {
      "type": "switch",
      "title": "This is great",
      "key": "this_is_great",
      "value": true,
      "options": "true,false"
    },
    {
      "type": "parent", // ! Value is not allowed for parent Metafield !
      "title": "Call Out Section",
      "key": "call_out_section",
      "children": [
        {
          "type": "text",
          "title": "Headline",
          "key": "headline",
          "value": "You're Going to Love it Here!"
        },
        {
          "type": "html-textarea",
          "title": "Section Content",
          "key": "section_content",
          "value": "<p>You are going to <strong>love</strong> it in Cosmic Village. The best place to raise a team!</p>"
        },
        {
          "type": "file",
          "title": "Hero",
          "key": "hero",
          "value": "big-beautiful-image.jpg"
        }
      ]
    },
    {
      "type": "repeater", // ! Value is not allowed for repeater Metafield !
      "title": "Testimonials",
      "key": "testimonials",
      // Available repeaters
      "repeater_fields": [
        {
          "title": "Name",
          "key": "name",
          "value": "",
          "type": "text",
          "required": false
        },
        {
          "title": "Quote",
          "key": "quote",
          "value": "",
          "type": "text",
          "required": false
        }
      ],
      //  Repeating items and values
      "children": [
        {
          "type": "repeating_item",
          "children": [
            {
              "type": "text",
              "title": "Name",
              "key": "name",
              "value": "Fiona Apple"
            },
            {
              "type": "text",
              "title": "Name",
              "key": "name",
              "value": "Jon Brion"
            }
          ]
        }
      ]
    }
  ]
}

Validation

You can use optional validation parameters to make sure editors using the Web Dashboard enter the correct values.

Reference the Metafield model to learn more.

ParameterRequiredTypeDescription
requiredBoolA value is required
regexStringRestrict the value to match a regular expresssion
regex_messageStringThe message displayed when the value fails the regex
minlengthNumberAdd minlength to text or textarea Metafields
maxlengthNumberAdd maxlength to text or textarea Metafields

Example Metafields with Validations

{
  "title": "Users",
  "singular": "User",
  "slug": "users",
  "metafields": [
    {
      "key": "first_name",
      "title": "First Name",
      "type": "text",
      "value": "",
      "required": true,
      "minlength": 2
    },
    {
      "key": "last_name",
      "title": "Last Name",
      "type": "text",
      "value": "",
      "required": true,
      "minlength": 2
    },
    {
      "key": "email",
      "title": "Email",
      "type": "text",
      "value": "",
      "regex": "/^([a-z0-9_.-]+)@([da-z.-]+).([a-z.]{2,6})$/",
      "regex_message": "You must enter a valid email."
    },
    {
      "key": "avatar",
      "title": "Avatar",
      "type": "file",
      "value": ""
    },
    {
      "key": "tagline",
      "title": "Tagline",
      "type": "text",
      "value": "",
      "maxlength": 50
    }
  ]
}

The following endpoints allow you to create, read, update, and delete Metafields in your Object. (Currently REST API only.)

Get your keys
Your read and write keys will be required to perform the following requests. These can be found in Bucket Settings > API Access in your Bucket Dashboard .

Get Metafields

Returns Metafields in an Object.

Definition

GET /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields
ParameterRequiredTypeDescription
read_keyrequiredStringRestrict read access to your Bucket
prettyEnumtrue, Makes the response more reader-friendly

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields \
    -d read_key=${YOUR_BUCKET_READ_KEY} \
    -G

Example Response

{
  "metafields": [
    {
      "type": "number",
      "title": "Phone Number",
      "key": "phone_number",
      "id": "Hvix3sGVi0",
      "value": ""
    },
    {
      "type": "radio-buttons",
      "title": "This or That",
      "key": "this_or_that",
      "id": "QCEI7BnfuO",
      "value": "",
      "options": [
        {
          "value": "This"
        },
        {
          "value": "That"
        }
      ]
    }
  ],
  "total": 2
}

Get Metafield

Returns a single Metafield from an Object.

Definition

GET /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields/:key

Parameters

ParameterRequiredTypeDescription
read_keyrequiredStringRestrict read access to your Bucket
prettyEnumtrue, Makes the response more reader-friendly

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields/:key \
    -d read_key=${YOUR_BUCKET_READ_KEY} \
    -G

Example Response

{
  "metafield": {
    "type": "radio-buttons",
    "title": "This or That",
    "key": "this_or_that",
    "id": "QCEI7BnfuO",
    "value": "",
    "options": [
      {
        "value": "This"
      },
      {
        "value": "That"
      }
    ]
  }
}

Add Metafield

Creates a new Metafield on an Object.

Definition

POST /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields

Parameters

See Metafields Model for available parameters.

Required
Your Bucket write_key must be passed as Authorization Bearer in the header of the request. This can be found in Bucket Settings > API Access in your Admin Dashboard.

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields \
    -d '{"type":"number","key":"phone_number","title":"Phone Number","value":123456789}' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer <YOUR_BUCKET_WRITE_KEY>"

Example Response

{
  "message": "metafield with key: 'phone_number' added successfully in object with id:':id"
}

Edit Metafield

Edits a Metafield on an Object.

Definition

PATCH /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields/:key

Required
Your Bucket write_key must be passed as Authorization Bearer in the header of the request. This can be found in Bucket Settings > API Access in your Admin Dashboard.

Take a look at Metafield Model for reference to be passed in the body.

Note: At least one of the Parameters is required to process the request.

Methods

bucket.editObjectMetafield()

Example Request

const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  write_key: "YOUR_BUCKET_WRITE_KEY",
});
const params = {
  id: "object-id",
  key: "phone_number",
  value: 9876543210,
};
const data = await bucket.editObjectMetafield(params);
curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields/:key \
    -d '{"value":9876543210}' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer <YOUR_BUCKET_WRITE_KEY>"
    -X PATCH

Example Response

{
  "metafield": {
    "type": "number",
    "title": "Phone number",
    "key": "phone_number",
    "value": 9876543210
  }
}

Delete Object Metafield

Deletes a Metafield from an Object.

Required
Your Bucket write_key must be passed as Authorization Bearer in the header of the request. This can be found in Bucket Settings > API Access in your Admin Dashboard.

Definition

DELETE /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields/:key

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id/metafields/:key \
    -H "Authorization: Bearer <YOUR_BUCKET_WRITE_KEY>" \
    -X DELETE

Example Response

{
  "message": "metafield with key: ':key' deleted successfully from object with id:':id"
}

Object Metafields

You can connect Objects to create "one to many" and "many to many" relationships between Objects using Single and Multiple Object Metafields.

Parameters

ParameterRequiredTypeDescription
typerequiredEnumobject, objects
titlerequiredStringYour Metafield title
keyrequiredStringUnique identifier for your Metafield
object_typerequiredStringObject Type slug
valueStringFor single Object this is the id property. For multiple Objects it is comma-separated ids (order maintained).

Single Objects

For a Single Object Metafield, add the Object ID (id) to the value to connect the Object. The full Object will be returned on the Metadata response in the object property.

Multiple Objects

For Multiple Object Type Metafields, you can add the Object IDs as comma-separated values. The full Objects will be returned on the Metadata response in the objects property.

Example

Note that the Author is a single object Metafield with a single id in the value. The Categories Metafield is a Multiple objects Metafield with comma-separated Object IDs.

Request Body

{
  "title": "Blog Post Example",
  "type": "blog-posts",
  "content": "This is some amazing blog content...",
  "metafields": [
    {
      "title": "Headline",
      "key": "headline",
      "type": "text",
      "value": "What I Learned Today"
    },
    {
      "title": "Author",
      "key": "author",
      "type": "object",
      "object_type": "authors",
      "value": "5a4ab6e0cf2289b18a2f7599"
    },
    {
      "title": "Categories",
      "key": "categories",
      "type": "objects",
      "object_type": "categories",
      "value": "5a4ab6e0cf2289b18a2f7599,5a49d524c1174db128ca2bce"
    }
  ]
}

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/objects \
    -d ${REQUEST_BODY} \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer <YOUR_BUCKET_WRITE_KEY>"

Media Metafields

You can add media to your Object by using the Media Metafield. The full Media object including url and imgix_url will be provided in the metadata property when querying the Object.

Parameters

ParameterRequiredTypeDescription
typerequiredStringfile
titlerequiredStringYour Metafield title
keyrequiredStringUnique identifier for your Metafield
valueStringThe name property of the media in your Bucket.

Example

Request Body

{
  "title": "Blog Post Example with Media",
  "type": "blog-posts",
  "content": "This is some amazing blog content...",
  "metafields": [
    {
      "title": "Hero",
      "key": "hero",
      "type": "file",
      "value": "my-amazing-hero-image.jpg"
    }
  ]
}

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/objects \
    -d ${REQUEST_BODY} \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer <YOUR_BUCKET_WRITE_KEY>"
  • Note that the Metafield value is the media name.