Object types

Learn about Object types; used to organize and model Objects in your Cosmic Bucket.

The Object type model

The Object type model contains all the information about the Object type including content modeling using Metafields, localization, preview links, and more.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for Object type.

  • Name
    title
    Type
    string
    Description

    Object type title.

  • Name
    singular
    Type
    string
    Description

    Singular title of the Object type.

  • Name
    slug
    Type
    string
    Description

    Object type slugs are unique per Bucket.

  • Name
    singleton
    Type
    boolean
    Description

    Single or multiple Objects in this type.

  • Name
    emoji
    Type
    string
    Description

    Valid Unicode emoji displayed on the Object type table.

  • Name
    metafields
    Type
    array
    Description

    Array of Metafields. See Metafields model.

  • Name
    options
    Type
    object
    Description

    Contains boolean property slug_field which controls the display options for the slug field for Objects in the type.

  • Name
    localization
    Type
    boolean
    Description

    Add localization to the Object type. Default: false

  • Name
    locales
    Type
    array
    Description

    Array of available locales in the Object type. See available locale codes.

  • Name
    priority_locale
    Type
    string
    Description

    Default locale when creating new Objects in this type. Objects will be grouped by this locale in the Object type table in the dashboard.

The Object type model

{
  "id": "63bde47897d49d0008a270b3",
  "title": "Bikes",
  "slug": "bikes",
  "singular": "Bike",
  "emoji": "🏍️",
  "created_at": "2023-01-10T22:19:36.128Z",
  "modified_at": "2023-03-16T21:09:09.914Z",
  "singleton": false,
  "options": {
    "slug_field": true
  },
  "metafields": [
    {
      "id": "c7c50911-3b38-4b22-a307-392eb9f84739",
      "title": "Image",
      "key": "image",
      "type": "file",
      "value": "",
      "helptext": "",
      "required": false,
    },
    {
      "id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
      "title": "Headline",
      "key": "headline",
      "type": "text",
      "value": "",
      "helptext": "",
      "required": false
    }
  ]
}

GET/v3/buckets/:bucket_slug/object-types

Get Object types

This endpoint enables you to retrieve a list of your Object types in the Bucket.

Request

GET
/v3/buckets/:bucket_slug/object-types
import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY'
})

await cosmic.objectTypes.find()

Response

{
  "object_types": [
    {
      "id": "63bde47897d49d0008a270b3",
      "title": "Bikes",
      "slug": "bikes",
      "singular": "Bike",
      "emoji": "🏍️",
      "created_at": "2023-01-10T22:19:36.128Z",
      "modified_at": "2023-03-16T21:09:09.914Z",
      "singleton": false,
      "options": {
        "slug_field": true
      },
      "metafields": [
        {
          "id": "c7c50911-3b38-4b22-a307-392eb9f84739",
          "title": "Image",
          "key": "image",
          "type": "file",
          "value": "",
          "helptext": "",
          "required": false,
        },
        {
          "id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
          "title": "Headline",
          "key": "headline",
          "type": "text",
          "value": "",
          "helptext": "",
          "required": false
        }
       ...
      ]
    },
    {
      "id": "63bde4c297d49d0008a270b4",
      "title": "Cars",
      "slug": "cars",
      "singular": "Car",
      "emoji": "🚗",
      "created_at": "2023-01-10T22:19:36.128Z",
      "modified_at": "2023-03-16T21:09:09.914Z",
      "singleton": false,
      "options": {
        "slug_field": true
      },
      "metafields": [
        {
          "id": "c7c50911-3b38-4b22-a307-392eb9f84739",
          "title": "Image",
          "key": "image",
          "type": "file",
          "value": "",
          "helptext": "",
          "required": false,
        },
        {
          "id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
          "title": "Headline",
          "key": "headline",
          "type": "text",
          "value": "",
          "helptext": "",
          "required": false
        }
       ...
      ]
    }
  ]
}

GET/v3/buckets/:bucket_slug/object-types/:slug

Get a single Object type

Get a single Object type by slug.

Required parameters

  • Name
    slug
    Type
    string
    Description

    The Object type slug.

Request

GET
/v3/buckets/:bucket_slug/object-types/:slug
import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY'
})

await cosmic.objectTypes.findOne('object-type-slug')

Response

{
  "object_type": {
    "id": "63bde47897d49d0008a270b3",
    "title": "Bikes",
    "slug": "bikes",
    "singular": "Bike",
    "emoji": "🏍️",
    "created_at": "2023-01-10T22:19:36.128Z",
    "modified_at": "2023-03-16T21:09:09.914Z",
    "singleton": false,
    "options": {
      "slug_field": true
    },
    "metafields": [
      {
        "id": "c7c50911-3b38-4b22-a307-392eb9f84739",
        "title": "Image",
        "key": "image",
        "type": "file",
        "value": "",
        "helptext": "",
        "required": false,
      },
      {
        "id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
        "title": "Headline",
        "key": "headline",
        "type": "text",
        "value": "",
        "helptext": "",
        "required": false
      }
      ...
    ]
  }
}

POST/v3/buckets/:bucket_slug/object-types

Create an Object type

This endpoint enables you to create an Object type in your Bucket.

The data request payload will need to be sent in JSON format with the Content-Type: application/json header set.

Required parameters

  • Name
    title
    Type
    string
    Description

    Object type title.

Optional parameters

  • Name
    singular
    Type
    string
    Description

    Singular title of the Object type.

  • Name
    slug
    Type
    string
    Description

    Object type slugs are unique per Bucket. Default: title converted to slug.

  • Name
    singleton
    Type
    boolean
    Description

    Single or multiple Objects in this type.

  • Name
    emoji
    Type
    string
    Description

    Valid Unicode emoji displayed on the Object type table.

  • Name
    metafields
    Type
    array
    Description

    Array of Metafields. See Metafields Model.

  • Name
    options
    Type
    object
    Description

    Contains boolean property slug_field which controls the display options for the slug field for Objects in the type.

  • Name
    localization
    Type
    boolean
    Description

    Add localization to the Object type. Default: false

  • Name
    locales
    Type
    array
    Description

    Array of available locales in the Object type. See available locale codes.

  • Name
    priority_locale
    Type
    string
    Description

    Default locale when creating new Objects in this type. Objects will be grouped by this locale in the Object type table in the dashboard.

Request

POST
/v3/buckets/${BUCKET_SLUG}/object-types
import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY',
  writeKey: 'BUCKET_WRITE_KEY'
})

await cosmic.objectTypes.insertOne({
  title: "Bikes",
  slug: "bikes",
  emoji: "🏍️",
  metafields: [
    {
      "title": "Image",
      "key": "image",
      "type": "file",
      "value": "",
      "required": true
    },
    {
      "title": "Headline",
      "key": "headline",
      "type": "text",
      "value": "",
      "required": false
    }
  ]
})

Response

{
  "object_type": {
    "id": "63bde47897d49d0008a270b3",
    "title": "Bikes",
    "slug": "bikes",
    "singular": "Bike",
    "emoji": "🏍️",
    "created_at": "2023-01-10T22:19:36.128Z",
    "modified_at": "2023-03-16T21:09:09.914Z",
    "singleton": false,
    "options": {
      "slug_field": true
    },
    "metafields": [
      {
        "id": "c7c50911-3b38-4b22-a307-392eb9f84739",
        "title": "Image",
        "key": "image",
        "type": "file",
        "value": "",
        "helptext": "",
        "required": false,
      },
      {
        "id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
        "title": "Headline",
        "key": "headline",
        "type": "text",
        "value": "",
        "helptext": "",
        "required": false
      }
      ...
    ]
  }
}

PATCH/v3/buckets/${BUCKET_SLUG}/object-types/:slug

Update an Object type

This endpoint enables you to update an Object type.

If using the NPM module, use the $set method to update the Object type properties specificed.

Optional parameters

  • Name
    singular
    Type
    string
    Description

    Singular title of the Object type.

  • Name
    slug
    Type
    string
    Description

    Object type slugs are unique per Bucket. Default: title converted to slug.

  • Name
    singleton
    Type
    boolean
    Description

    Single or multiple Objects in this type.

  • Name
    emoji
    Type
    string
    Description

    Valid Unicode emoji displayed on the Object type table.

  • Name
    metafields
    Type
    array
    Description

    Array of Metafields. See Metafields Model.

  • Name
    options
    Type
    object
    Description

    Contains boolean property slug_field which controls the display options for the slug field for Objects in the type.

  • Name
    localization
    Type
    boolean
    Description

    Add localization to the Object type. Default: false

  • Name
    locales
    Type
    array
    Description

    Array of available locales in the Object type. See available locale codes.

  • Name
    priority_locale
    Type
    string
    Description

    Default locale when creating new Objects in this type. Objects will be grouped by this locale in the Object type table in the dashboard.

Request

PATCH
/v3/buckets/${BUCKET_SLUG}/object-types/:slug
import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY',
  writeKey: 'BUCKET_WRITE_KEY'
})

await cosmic.objectTypes.updateOne('object-type-slug', {
  title: 'Motorcycles',
  slug: 'motorcycles',
  singular: 'Motorcycle'
})

Response

{
  "object_type": {
    "id": "63bde47897d49d0008a270b3",
    "title": "Motorcycles",
    "slug": "motorcycles",
    "singular": "Motorcycle",
    "emoji": "🏍️",
    "created_at": "2023-01-10T22:19:36.128Z",
    "modified_at": "2023-03-16T21:09:09.914Z",
    "singleton": false,
    "options": {
      "slug_field": true
    },
    "metafields": [
      {
        "id": "c7c50911-3b38-4b22-a307-392eb9f84739",
        "title": "Image",
        "key": "image",
        "type": "file",
        "value": "",
        "helptext": "",
        "required": false,
      },
      {
        "id": "1157a40b-9a1a-4d06-96e0-2338f01d366d",
        "title": "Headline",
        "key": "headline",
        "type": "text",
        "value": "",
        "helptext": "",
        "required": false
      }
      ...
    ]
  }
}

DELETE/v3/buckets/${BUCKET_SLUG}/object-types/:slug

Delete an Object type

This endpoint enables you to delete an Object type and all Objects in this type from your Bucket.

Required parameters

  • Name
    slug
    Type
    string
    Description

    Object type slug.

Optional parameters

  • Name
    trigger_webhook
    Type
    boolean
    Description

    Triggers corresponding Object action webhook (See Webhooks).

Request

DELETE
/v3/buckets/${BUCKET_SLUG}/object-types/:slug
import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY',
  writeKey: 'BUCKET_WRITE_KEY'
})

await cosmic.objectTypes.deleteOne("object-type-slug")

Response

{
  "message": "Object type with slug ':slug' deleted successfully from bucket."
}

Metafields

Learn about Metafields; the way you compose your content model for your Objects in Cosmic.

Data Model

ParameterRequiredTypeDescription
typerequiredEnumtext, textarea, html-textarea, select-dropdown, object, objects, file, date, radio-buttons, check-boxes, repeater, parent, markdown, json, switch, number, color, emoji
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": "Author",
      "key": "author",
      "object_type": "authors",
      "value": "5a4806974fa85fc8a7000002" // Object ID
    },
    {
      "type": "objects",
      "title": "Categories",
      "key": "categories",
      "object_type": "categories",
      "value": ["5a4806974fa85fc8a7000007,5a4806974fa85fc8a7000008"] // 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
    }
  ]
}