# Objects

The following endpoints allow you to add, edit and delete Objects in your Bucket.

Quick Tip

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

# Add Object

Add a new Object to your Bucket.

Parameter Required Type Description
type_slug required String Add Object to Object Type
title required String Your Object title
slug String Unique identifier for your Object
content String Add Content to your Object
status Enum draft, published, defaults to published
options.slug_field Bool Set to false to hide the slug field
options.content_editor Bool Set to false to hide the content editor
metafields Array Add Metafields to your Object. See Metafields Model.
locale String Add localization to the Object
write_key String Your Bucket write key
publish_at Number UNIX millisecond timestamp. Publish automatically at a later time.
trigger_webhook Bool Triggers corresponding Object action Webhook (See Webhooks)

    # Get Objects

    Get Objects in your Bucket.

    Quick Tip

    For a quick reference to this endpoint click the "Developer Tools" button on your Object table in your Bucket Dashboard .

    Parameter Required Type Description Default
    type String The Object Type slug
    limit Number The number of Objects to return 1000
    skip Number The number of Objects to skip 0
    status Enum published, draft, all published
    hide_metafields Enum true, Hides metafields false
    sort Enum created_at, -created_at, modified_at, -modified_at, random, order order
    locale String Filter by locale
    q String Searches title and content properties for this string
    query JSON A JSON string to perform advanced queries
    metadata[key] String Search by Metafield value. Object IDs for Object Metafields (comma separated for multiple)
    metafield_key String (Deprecated, use metadata[key] instead) Metafield key to search for
    metafield_value String (Deprecated, use metadata[key] instead) Metafield contains value
    metafield_object_id String (Deprecated, use metadata[key] instead) Object Metafield Object ID (stored as Metafield value)
    filters[_id] String Filter by Object IDs (comma separated for multiple)
    filters[connected_to] String Returns Objects that reference the specified Object ID (String)
    props Enum Declare which properties to return in comma-separated string. Down to first-level metadata properties only. Reference full Object for all available properties. Example: ?props=slug,title,metadata.categories,metadata.author
    depth Number 0-3, Limits the depth of nested Objects from Object Metafields
    created_by String Created by User ID
    pretty Enum true, Makes the response more reader-friendly false
    read_key String Your Bucket read key

      # Search and Filter

      Get Objects based on search variables.

      Quick Tip

      Read the Changelog announcement to learn more.

      See the Get Objects Params to learn how to use params q, metadata[key], and created_by for flexible searching and filterting.

        # Advanced Queries (Beta)

        Advanced queries give you powerful NoSQL database-like functionality for content fetching. Use the query parameter to send a valid JSON (stringified) query on the Get Objects Endpoint. See example requests below.

        Note

        If accessing the endpoint via browser address bar, open and closed curly braces will need to be encoded: %7B and %7D respectively. This encoder tool may help.

        Definition

        GET https://api.cosmicjs.com/v1/:bucket_slug/objects?type=:type_slug&read_key=your-read-key-found-bucket-settings&query=:JSON_query
        

        # Available Keys to Query

        Parameter Description
        _id Object _id
        title Object Title
        slug Object Slug
        content Object Content
        created_at Object Created at Date
        published_at Object Published at Date
        modified_at Object Modified at Date
        created_by Object Created by user id
        modified_by Object Modified by user id
        metadata.$key Metadata value(s)

        # Query Selectors

        Parameter Description
        $eq Matches values that are equal to a specified value. Equivalent to direct key/value query.
        $gt Matches values that are greater than a specified value.
        $gte Matches values that are greater than or equal to a specified value.
        $lt Matches values that are less than a specified value.
        $lte Matches values that are less than or equal to a specified value.
        $in Matches any of the values specified in an array.
        $ne Matches all values that are not equal to a specified value.
        $nin Matches none of the values specified in an array.
        $all Matches arrays that contain all elements specified in the query.
        $regex, $options Search for string, use $options: "i" for case insensitive matches

        # Logic Operators

        Parameter Description
        $and Returns Objects that match all conditions
        $or Returns Objects that match any conditions

        # Example Queries

        To keep examples concise, the following variables are used:

          Matches Objects with exact title

            Matches Objects with exact _id

              Matches Objects with any _ids

                Match Objects with any _ids not equal to value

                  Match Objects except with _ids in the array of values

                    Match Objects with exact slug

                      Match Objects with string in content. Case insensive with $options.

                        Match metadata value (Number Metafield)

                          Match any slug values

                            Match any metadata values

                              Match all metadata values

                                Match greater than or equal to metadata value

                                  Match exact metadata value (Switch Metafield)

                                    Match nested JSON metadata value (JSON Metafield)

                                      Match Single Object Metafield value

                                        Match not equal to Single Object Metafield value

                                          Match all Multiple Object Metafield values

                                            Match any Multiple Object Metafield values

                                              Match doesn't have any Multiple Object Metafield values

                                                # Get Object

                                                Returns a single Object from your Bucket.

                                                Quick Tip

                                                For a quick reference to this endpoint click the "Developer Tools" button on your Edit Object view in your Bucket Dashboard .

                                                Parameter Required Type Description
                                                slug required String Unique identifier for your Object
                                                status Enum all, Return published and draft status Objects
                                                revision String The revision_id of the Object Revision
                                                hide_metafields Enum true, Hides metafields
                                                locale String Filter by locale
                                                props Enum Declare which properties to return in comma-separated string. Down to first-level metadata properties only. Reference full Object for all available properties. Example: ?props=slug,title,metadata.categories,metadata.author
                                                depth Number 0-3, Limits the depth of nested Objects from Object Metafields
                                                pretty Enum true, Makes the response more reader-friendly
                                                read_key String Your Bucket read key

                                                  # Object Revisions

                                                  Every Object has Revisions saved. Object Revisions cannot be edited or deleted.

                                                  # Get Object Revisions

                                                  Get Object Revisions from an Object.

                                                  Parameter Required Type Description
                                                  slug required String Unique identifier for your Object
                                                  limit Number The number of Revisions to return
                                                  skip Number The number of Revisions to skip
                                                  sort Enum created_at, -created_at (default is -created_at)
                                                  hide_metafields Enum true, Hides metafields
                                                  locale String Filter by locale
                                                  props Enum Declare which properties to return in comma-separated string. Down to first-level metadata properties only. Reference full Object for all available properties. Example: ?props=slug,title,metadata.categories,metadata.author
                                                  depth Number 0-3, Limits the depth of nested Objects from Object Metafields
                                                  pretty Enum true, Makes the response more reader-friendly
                                                  read_key String Your Bucket read key

                                                    # Add Object Revision

                                                    Adds Revision to an Object set to draft status. To edit a published Object use the Edit Object method. Same properties as Add Object params.

                                                      # Edit Object

                                                      Edit an existing Object in your Bucket. slug or id can be used as an identifier.

                                                      Parameter Required Type Description
                                                      slug String Unique identifier for your Object. If id present, used to modify your Object slug
                                                      id String Unique identifier for your Object
                                                      type_slug String Object Type
                                                      title String Your Bucket title
                                                      content String Add Content to your Object
                                                      status Enum draft, published, defaults to published
                                                      options.slug_field Bool Set to false to hide the slug field
                                                      options.content_editor Bool Set to false to hide the content editor
                                                      metafields Array Add Metafields to your Object. See Metafields Model.
                                                      locale String Edit Object locale
                                                      write_key String Your Bucket write key
                                                      publish_at Number UNIX millisecond timestamp. Publish automatically at a later time.
                                                      trigger_webhook Bool Triggers corresponding Object action Webhook (See Webhooks)

                                                        # Delete Object

                                                        Delete an existing Object in your Bucket.

                                                        Parameter Required Type Description
                                                        slug required String Unique identifier for your Object
                                                        write_key String Your Bucket write key
                                                        trigger_webhook Bool Triggers corresponding Object action Webhook (See Webhooks)