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.
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.
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.
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 adding Metafields to Object types in the Metafields page.