Objects

Learn about Objects; the basic building blocks of content in your Cosmic Bucket.

Use the following methods to create, read, update, and delete Objects.

The Object model

The Object model contains all the information about Objects.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for Object.

  • Name
    type
    Type
    string
    Description

    Object type slug.

  • Name
    title
    Type
    string
    Description

    Object title.

  • Name
    slug
    Type
    string
    Description

    Object slugs are unique per each Object type. Localized versions of Objects are linked with the same slug. See localization.

  • Name
    content
    Type
    string
    Description

    HTML Content. (deprecatated in API v3, use Metafield instead)

  • Name
    metadata
    Type
    object
    Description

    Values of the Metafields created in the Object type.

  • Name
    created_by
    Type
    string
    Description

    The id of the user who created the Object.

  • Name
    created_at
    Type
    string
    Description

    Date the Object was created.

  • Name
    modified_by
    Type
    string
    Description

    The id of the user who last modified the Object.

  • Name
    modified_at
    Type
    string
    Description

    Date Object was last modified.

  • Name
    published_at
    Type
    string
    Description

    Date Object was last published.

  • Name
    publish_at
    Type
    string
    Description

    UNIX millisecond timestamp. Publish automatically at a later time.

  • Name
    unpublish_at
    Type
    string
    Description

    UNIX millisecond timestamp. Unpublish automatically at a later time.

  • Name
    locale
    Type
    string
    Description

    See localization for locale options.

  • Name
    thumbnail
    Type
    string
    Description

    Media name. Media must be available in Bucket. See media.

The Object model

{
  "id": "63dc57ca24090e0008683d42",
  "slug": "add-a-headless-cms-to-astro-in-3-easy-steps",
  "title": "Add a headless CMS to Astro in 3 easy steps",
  "bucket": "63dc24a4d71e244b63c88fca",
  "created_at": "2023-02-03T00:39:38.35Z",
  "modified_at": "2023-03-23T12:08:13.547Z",
  "status": "published",
  "thumbnail": "https://imgix.cosmicjs.com/1c8531f0-97fb-11ed-81d8-8f0123e10511-A-photo-of-Michelangelos-sculpture-of-David-wearing-headphones-djing.webp",
  "published_at": "2023-03-23T12:08:13.547Z",
  "modified_by": "629e6cdda6f4f100091ae2e0",
  "publish_at": null,
  "type": "blog-posts",
  "metadata": {
    "content": "Astro is a lightweight web framework capable of shipping highly performant websites with minimal (or non-existent) JavaScript bundles. In this guide...",
    "image": {
      "url": "https://cdn.cosmicjs.com/02670ac0-38ef-11ed-adfd-ddb1795c6ac6-add-a-headless-cms-to-astro-in-3-easy-steps.png",
      "imgix_url": "https://imgix.cosmicjs.com/02670ac0-38ef-11ed-adfd-ddb1795c6ac6-add-a-headless-cms-to-astro-in-3-easy-steps.png"
    },
    "published_date": "2022-09-20",
    "author": {
      "title": "Stefan Kudla"
    }
  }
}

GET/v3/buckets/:bucket_slug/objects

Get Objects

This endpoint enables you to retrieve a list of your Objects.

Optional parameters

  • Name
    query
    Type
    object
    Description

    A JSON object to perform Object search and filtering. See queries section for more detail. Must be URL encoded for REST requests.

Optional methods

  • Name
    props
    Type
    string|array
    Description

    Declare which properties to return in comma-separated string (or array if using the NPM module). Remove to see all Object properties. Can include nested metadata. Example: id,title,metadata.author.metadata.image.url.

  • Name
    status
    Type
    enum
    Description

    Set to any for latest draft or published Object.
    Options published | any
    Default published

  • Name
    sort
    Type
    enum
    Description

    Order of Objects returned.
    Options created_at, -created_at, modified_at, -modified_at, random, order, metadata.$key, -metadata.$key
    Use - for descending order.
    Default -order (order in dashboard, top down)

    Sort by Metadata
    Sort by metadata using metadata.$key and -metadata.$key. For example, setting sort to metadata.price will return Objects from low to high price. To enable sortable Metafields, go to Object type > Settings in the dashboard. Metafields that can be sortable include Text, Number, and Date Metafields. You are currently limited to 2 sortable Metafields per Object type.

  • Name
    limit
    Type
    number
    Description

    Limit the number of Objects returned.
    Default 1000

  • Name
    skip
    Type
    number
    Description

    Used for pagination. The number of Objects to skip.
    Default 0

  • Name
    depth
    Type
    number
    Description

    The depth of Object references using Object Relationship Metafields. Circular reference is prohibited.
    Default 0

  • Name
    after
    Type
    string
    Description

    Used for pagination. Get Objects after specified Object id (can only use one of skip or after).

  • Name
    useCache
    Type
    bool
    Description

    Set to false for real-time updates. Increases latency of endpoint.
    Default true

  • Name
    pretty
    Type
    bool
    Description

    Set to true for reader-friendly formated JSON response.
    Default false

Request

GET
/v3/buckets/:bucket_slug/objects
import { createBucketClient } from '@cosmicjs/sdk'

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

await cosmic.objects.find({
  type: 'object-type-slug'
}).props([
  'id',
  'slug',
  'title',
  'metadata.content',
  'metadata.description',
  'metadata.parent.title'
]).limit(1)

Response

{
  "objects": [
    {
      "id": "5f7357967286d7773adc551e",
      "slug": "learning",
      "title": "Learning",
      "metadata": {
        "content": "<p>Learning is fun!!</p>",
        "description": "This is the example description",
        "parent": {
          "title": "Example Post"
        }
      }
    }
  ],
  "total": 6,
  "limit": 1
}

GET/v3/buckets/:bucket_slug/objects

Get a single Object by slug

This endpoint enables you to get a single Object by slug. To get a single Object by slug indicate the type and slug in the query parameter.

With the Cosmic NPM module, you can use the findOne method to return an object. If using the REST API, it will return an array.

Optional parameters

  • Name
    query
    Type
    object
    Description

    A JSON object to perform Object search and filtering. See queries section for more detail. Must be URL encoded for REST requests.

Optional methods

  • Name
    props
    Type
    string|array
    Description

    Declare which properties to return in comma-separated string (or array if using the NPM module). Remove to see all Object properties. Can include nested metadata. Example: id,title,metadata.author.metadata.image.url.

  • Name
    status
    Type
    enum
    Description

    Set to any for latest draft or published Object.
    Options published | any
    Default published

  • Name
    depth
    Type
    number
    Description

    The depth of Object references using Object Relationship Metafields. Circular reference is prohibited.
    Default 0

  • Name
    useCache
    Type
    bool
    Description

    Set to false for real-time updates. Increases latency of endpoint.
    Default true

  • Name
    pretty
    Type
    bool
    Description

    Set to true for reader-friendly formated JSON response.
    Default false

Request

GET
/v3/buckets/:bucket_slug/objects
import { createBucketClient } from '@cosmicjs/sdk'

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

await cosmic.objects.findOne({
  type: 'object-type-slug',
  slug: 'object-slug'
}).props([
  'slug',
  'title',
  'metadata.content',
  'metadata.image.imgix_url',
])

Response

{
  "object": {
    "slug": "my-blog-post-slug",
    "title": "My Blog Post",
    "metadata": {
      "content": "<p>Learning is fun!!</p>",
      "image": {
        "imgix_url": "https://imgix.cosmicjs.com/123asdf..."
      }
    }
  }
}

GET/v3/buckets/:bucket_slug/object/:id

Get a single Object by id

This endpoint enables you to get a single Object by id. To get a single Object by id, indicate the id in the query parameter. To get an Object by slug, see the above example.

Optional parameters

  • Name
    query
    Type
    object
    Description

    A JSON object to perform Object search and filtering. See queries section for more detail. Must be URL encoded for REST requests.

Optional methods

  • Name
    props
    Type
    string|array
    Description

    Declare which properties to return in comma-separated string (or array if using the NPM module). Remove to see all Object properties. Can include nested metadata. Example: id,title,metadata.author.metadata.image.url.

  • Name
    status
    Type
    enum
    Description

    Set to any for latest draft or published Object.
    Options published | any
    Default published

  • Name
    depth
    Type
    number
    Description

    The depth of Object references using Object Relationship Metafields. Circular reference is prohibited.
    Default 0

  • Name
    useCache
    Type
    bool
    Description

    Set to false for real-time updates. Increases latency of endpoint.
    Default true

  • Name
    pretty
    Type
    bool
    Description

    Set to true for reader-friendly formated JSON response.
    Default false

Request

GET
/v3/buckets/:bucket_slug/objects/:id
import { createBucketClient } from '@cosmicjs/sdk'

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

await cosmic.objects.findOne({
  id: 'object-id'
}).props([
  'slug',
  'title',
  'metadata.content',
  'metadata.image.imgix_url'
])

Response

{
  "object": {
    "slug": "learning",
    "title": "Learning",
    "metadata": {
      "content": "<p>Learning is fun!!</p>",
      "image": {
        "imgix_url": "https://imgix.cosmicjs.com/123asdf..."
      }
    }
  }
}

POST/v3/buckets/:bucket_slug/objects

Create an Object

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

Required parameters

  • Name
    title
    Type
    string
    Description

    Object title.

  • Name
    type
    Type
    string
    Description

    Object type slug.

Optional parameters

  • Name
    slug
    Type
    string
    Description

    If slug is not included, the title will be converted into the slug.

  • Name
    metadata
    Type
    object
    Description

    If validation requirements are set on Metafields on the Object type, they will need to pass the validation requirements.

  • Name
    trigger_webhook
    Type
    boolean
    Description

    Triggers corresponding Object action webhook (See Webhooks).

Request

POST
/v3/buckets/${BUCKET_SLUG}/objects
import { createBucketClient } from '@cosmicjs/sdk'

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

await cosmic.objects.insertOne({
  title: 'Blog Post Example Title',
  type: 'blog-posts',
  metadata: {
    content: 'Here is an example blog post content...',
    seo_description: 'This is an example blog post SEO description.',
    featured_post: true
  }
})

Response

{
  "id": "5ff75368c2dfa81a91695cec",
  "title": "Blog Post Example Title",
  "slug": "blog-post-example-title",
  "type":"blog-posts-type-slug",
  "metadata":{
    "content": "Here is an example blog post content...",
    "seo_description": "This is an example blog post SEO description.",
    "featured_post": true
  }
}

PATCH/v3/buckets/${BUCKET_SLUG}/objects/:id

Update an Object

This endpoint enables you to update an Object.

Required parameters

  • Name
    id
    Type
    string
    Description

    Object id.

Optional parameters

  • Name
    title
    Type
    string
    Description

    Object title.

  • Name
    slug
    Type
    string
    Description

    Object slug.

  • Name
    status
    Type
    enum
    Description

    Options published | draft

  • Name
    metadata
    Type
    object
    Description

    If validation requirements are set on Metafields on the Object type, they will need to pass the validation requirements.

  • Name
    publish_at
    Type
    string
    Description

    UNIX millisecond timestamp. Publish automatically at a later time.

  • Name
    unpublish_at
    Type
    string
    Description

    UNIX millisecond timestamp. Unpublish automatically at a later time.

  • Name
    locale
    Type
    string
    Description

    See Localization(link to localization) for locale options.

  • Name
    thumbnail
    Type
    string
    Description

    Media name. Media must be available in Bucket. See Media(link to media).

  • Name
    trigger_webhook
    Type
    boolean
    Description

    Triggers corresponding Object action webhook (See Webhooks).

Request

PATCH
/v3/buckets/${BUCKET_SLUG}/objects/:id
import { createBucketClient } from '@cosmicjs/sdk'

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

await cosmic.objects.updateOne("object-id", {
  title: 'New Title Edit',
  metadata: {
    featured_post: false
  }
})

Response

{
  "id": "5ff75368c2dfa81a91695cec",
  "title": "New Title Edit",
  "slug": "blog-post-title",
  "type":"blog-posts",
  "metadata":{
    "content": "Here is the blog post content...",
    "seo_description": "This is the blog post SEO description.",
    "featured_post": false
  }
}

PATCH/v3/buckets/${BUCKET_SLUG}/objects/:id

Update Object metadata

Learn how to update Object metadata.

Use the metadata property when doing create or update requests to the Objects API endpoint.

Update basic Metafields

To update basic Metafields on Objects such as text and numbers, make sure to send the corresponding type.

Required parameter

  • Name
    metadata
    Type
    object
    Description

    Using the metadata property, update metadata values using the Object type Metafield key:value format.

Request

PATCH
/v3/buckets/${BUCKET_SLUG}/objects/:id
import { createBucketClient } from '@cosmicjs/sdk'

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

await cosmic.objects.updateOne('object-id', {
  metadata: {
    headline: 'This guitar amp is LOUD!',
    max_volume: 11,
    on_sale: true
  }
})

Response

{
  "id": "5ff75368c2dfa81a91695cec",
  "title": "Fender Spinal Tap Edition Amp",
  "slug": "fender-spinal-tap-edition-amp",
    "metadata": {
      "headline": "This guitar amp is LOUD!",
      "max_volume": 11,
      "on_sale": true
    }
  }
}

Object relationship Metafield

Single Object To add or update a single Object relationship Metafield, set the Object id as a string in the metadata.$key value.

Multiple Object To add or update a multiple Object relationship Metafield, use an array of Object ids.

Request

PATCH
/v3/buckets/${BUCKET_SLUG}/objects/:id
import { createBucketClient } from '@cosmicjs/sdk'

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

await cosmic.objects.updateOne('object-id', {
  metadata: {
    author: 'author-object-id', // Object id
    categories: ['cat1-object-id','cat2-object-id','cat3-object-id']  // Object ids
  }
})

Response

{
  "id": "5ff75368c2dfa81a91695cec",
  "title": "New Title Edit",
  "slug": "blog-post-title",
    "metadata": {
      "author": "author-object-id",
      "categories": ["cat1-object-id","cat2-object-id","cat3-object-id"]
    }
  }
}

Media Metafield

To add a value to a media Metafield, use the name of an existing media resource in the Bucket. See media model.

Request

PATCH
/v3/buckets/${BUCKET_SLUG}/objects/:id
import { createBucketClient } from '@cosmicjs/sdk'

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

await cosmic.objects.updateOne('object-id', {
  metadata: {
    image: "image-name-in-bucket.jpg"
  }
})

Response

{
  "id": "5ff75368c2dfa81a91695cec",
  "title": "New Title Edit",
  "slug": "blog-post-title",
    "metadata":{
      "image": {
        "url": "https://cdn.cosmicjs.com/image-name-in-bucket.jpg",
        "imgix_url": "https://imgix.cosmicjs.com/image-name-in-bucket.jpg"
      }
    }
  }
}

DELETE/v3/buckets/${BUCKET_SLUG}/objects/:id

Delete an Object

This endpoint enables you to delete Objects from your Bucket.

Required parameters

  • Name
    id
    Type
    string
    Description

    Object id.

Optional parameters

  • Name
    trigger_webhook
    Type
    boolean
    Description

    Triggers corresponding Object action webhook (See Webhooks).

Request

DELETE
/v3/buckets/${BUCKET_SLUG}/objects/:id
import { createBucketClient } from '@cosmicjs/sdk'

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

await cosmic.objects.deleteOne('object-id')

Response

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