Skip to content

Object Types

The following endpoints enable you to create, read, update, and delete Object Types in your Bucket. See API Introduction for getting started information.

🛑

This is for Object modeling only. Are you looking for ways to interact with Objects? Go to the Objects section.

🔑

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

Endpoints

GET /v2/buckets/${YOUR_BUCKET_SLUG}/object-types
POST /v2/buckets/${YOUR_BUCKET_SLUG}/object-types
PATCH /v2/buckets/${YOUR_BUCKET_SLUG}/object-types/:slug
DELETE /v2/buckets/${YOUR_BUCKET_SLUG}/object-types/:slug

Data Model

AttributeTypeNotes
slugStringPlural slug of your Object Type
titleStringPlural title of your Object Type
singularStringSingular title of your Object Type
metafieldsArray of MetafieldsDefault Metafields for each Object in this type. Add Metafields to your Object. See Metafields Model.
options.slug_fieldBooleanSet to false to hide the slug field
options.content_editorBooleanSet to false to hide the content editor
localizationBooleantrue, Adds localization to the Object Type
localesrequired if localization is true Array of StringArray of active locales in the Object Type. Check the available locale codes.
priority_localeStringDefault locale code for Objects in Object Type. Check the available locale codes
emojiStringValid Unicode emoji
singletonBooleanSingle or Multiple Objects

Get Object Types

Returns all Object Types in your Bucket.

Definition

GET /v2/buckets/${YOUR_BUCKET_SLUG}/object-types

Parameters

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

Methods

bucket.getObjectTypes()

Example Request

const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  read_key: "YOUR_BUCKET_READ_KEY",
});
const data = await bucket.getObjectTypes();

Example Response

{
  "object_types": [
    {
      "title": "Posts",
      "slug": "posts",
      "singular": "Post",
      "metafields": [
        {
          "children": null,
          "type": "object",
          "title": "Category",
          "key": "category",
          "id": "qc8ado5qusyaj9og8yi8",
          "object_type": "categories",
          "value": "5f7357967286d7773adc551e"
        },
        {
          "children": null,
          "type": "text",
          "title": "Headline",
          "key": "headline",
          "id": "g6Klj1ABP8",
          "value": ""
        }
      ],
      "options": {
        "slug_field": 1,
        "content_editor": 1
      },
      "preview_link": "",
      "priority_locale": null,
      "extensions": null,
      "order": 0,
      "localization": false,
      "locales": null,
      "emoji": ""
    },
    {
      "title": "Pages",
      "slug": "pages",
      "singular": "Page",
      "metafields": [],
      "options": {
        "slug_field": 1,
        "content_editor": 1
      },
      "preview_link": "",
      "priority_locale": null,
      "extensions": null,
      "emoji": "📁",
      "order": 1
    }
  ]
}

Get Object Type

Returns a single Object Type in your Bucket (REST is currently the only available method).

Definition

GET /v2/buckets/${YOUR_BUCKET_SLUG}/object-types/:slug

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}/object-types/:slug \
    -d read_key=${YOUR_BUCKET_READ_KEY} \
    -G

Example Response

{
  "object_type": {
    "title": "Pages",
    "slug": "pages",
    "singular": "Page",
    "metafields": [],
    "options": {
      "slug_field": 1,
      "content_editor": 1
    },
    "preview_link": "",
    "priority_locale": null,
    "extensions": null,
    "emoji": "📁",
    "order": 1
  }
}

Add Object Type

Creates a new Object Type in your Bucket (REST is currently the only available method).

⚠

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

POST /v2/buckets/${YOUR_BUCKET_SLUG}/object-types

Methods

bucket.addObjectType()

Example Request

const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  write_key: "YOUR_BUCKET_WRITE_KEY",
});
const params = {
  title: "Pages",
  singular: "Page",
  slug: "pages",
  emoji: "📄",
  singleton: false,
  metafields: [
    {
      type: "text",
      title: "Headline",
      key: "headline",
      required: true,
    },
    {
      type: "file",
      title: "Hero",
      key: "hero",
      required: true,
    },
  ],
};
const data = await bucket.addObjectType(params);

Example Response

{
  "object_type": {
    "title": "Categories",
    "slug": "categories",
    "singular": "Categories",
    "metafields": [],
    "created_at": "2021-01-07T14:08:24.309Z",
    "modifield_at": "2021-01-07T14:08:24.309Z",
    "localization": false,
    "locales": [],
    "priority_locale": ""
  }
}

Edit Object Type

Edits an existing Object Type in your Bucket.

⚠

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

PATCH /v2/buckets/${YOUR_BUCKET_SLUG}/object-types/:slug

Methods

bucket.editObjectType()

Example Request

const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  write_key: "YOUR_BUCKET_WRITE_KEY",
});
const data = await bucket.editObjectType({
  slug: "posts",
  title: "New Posts Title",
});

Example Body (JSON)

{
  "singular": "Category"
}

Example Response

{
  "object_type": {
    "title": "Categories",
    "slug": "categories",
    "singular": "Category",
    "metafields": [],
    "created_at": "2021-01-07T14:08:24.309Z",
    "modifield_at": "2021-01-07T14:17:04.124Z",
    "localization": false,
    "locales": [],
    "priority_locale": ""
  }
}

Delete Object Type

Delete an existing Object Type by type_slug from your Bucket.

⚠

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.

Note: This does not delete Objects in this Object Type.

Definition

DELETE /v2/buckets/${YOUR_BUCKET_SLUG}/object-types/:slug

Methods

bucket.deleteObjectType()

Example Request

const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  write_key: "YOUR_BUCKET_WRITE_KEY",
});
const data = await bucket.deleteObjectType({
  slug: "posts",
});

Example Response

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