---
title: "Create an Object"
method: POST
path: "/buckets/{slug}/objects"
tags: ["Objects"]
---

# Create an Object

`POST /buckets/{slug}/objects`

Create a single Object. `title` and `type` are required; the `slug` is derived from the title when omitted. Values in `metadata` must satisfy any validation configured on the Object type's Metafields. To create several Objects at once, use the batch endpoint instead of looping over this one.

## Request body

- ObjectCreate
  - `title` string, required
  - `type` string, required — Object type slug. The type must already exist.
  - `slug` string — Derived from `title` when omitted.
  - `status` 'published' | 'draft'
  - `content` string
  - `metadata` Metadata — Values of the Metafields defined on the Object type, keyed by Metafield `key`. The value shape follows the Metafield type, and differs between write and read for two of them: - Text, textarea, markdown, and HTML Metafields are strings. Number Metafields are numbers, switches are booleans, dates are ISO 8601 strings. - Object Relationship Metafields are written as an Object `id` string (or an array of ids for the multiple variant) and returned as a nested Object (or array of Objects) once `depth` is at least 1. - File and Image Metafields are written as a media `name` string (or an array of names) and returned as an object with `url` and `imgix_url`, plus `alt_text`, `width`, and `height` when requested via `props`. - Repeater Metafields are arrays of objects keyed by the child Metafield keys.
  - `thumbnail` string — Media `name`. The media must already exist in the Bucket.
  - `locale` string
  - `publish_at` union — UNIX millisecond timestamp.
    - string
    - number
  - `unpublish_at` union — UNIX millisecond timestamp.
    - string
    - number
  - `trigger_webhook` boolean — Fire the corresponding Object webhook.

## Response `200`

The created Object.

- ObjectResponse
  - `object` Object, required — A single piece of content. Which properties are present depends on `props`.
    - `id` string — Unique identifier.
    - `type` string — Object type slug.
    - `title` string
    - `slug` string — Unique within the Object type. Localized versions of an Object share a slug and count as one Object against plan limits.
    - `status` 'published' | 'draft'
    - `content` string, nullable — HTML content. Deprecated in v3; use a Metafield instead.
    - `metadata` Metadata — Values of the Metafields defined on the Object type, keyed by Metafield `key`. The value shape follows the Metafield type, and differs between write and read for two of them: - Text, textarea, markdown, and HTML Metafields are strings. Number Metafields are numbers, switches are booleans, dates are ISO 8601 strings. - Object Relationship Metafields are written as an Object `id` string (or an array of ids for the multiple variant) and returned as a nested Object (or array of Objects) once `depth` is at least 1. - File and Image Metafields are written as a media `name` string (or an array of names) and returned as an object with `url` and `imgix_url`, plus `alt_text`, `width`, and `height` when requested via `props`. - Repeater Metafields are arrays of objects keyed by the child Metafield keys.
    - `bucket` string — Bucket id.
    - `thumbnail` string, nullable — Media `name` of the Object thumbnail. Returned as a URL on read.
    - `locale` string, nullable — Locale code, when the Object type has localization enabled.
    - `created_at` string, date-time
    - `created_by` string — User id.
    - `modified_at` string, date-time
    - `modified_by` string — User id.
    - `published_at` string, date-time, nullable
    - `publish_at` union — UNIX millisecond timestamp for scheduled publishing.
      - string
      - number
    - `unpublish_at` union — UNIX millisecond timestamp for scheduled unpublishing.
      - string
      - number
    - `assigned_to` string, nullable — User id.
    - `assigned_by` string, nullable — User id.
    - `assigned_at` string, date-time, nullable

## Other responses

- `400` — The request was invalid, most often a malformed `query` or a Metafield value that failed validation.
- `401` — The access key is missing or incorrect.
- `402` — The Bucket needs to be upgraded before it can be used again.
- `404` — The addressed resource does not exist in this Bucket. Note that this covers a resource missing from a route that exists; an unrecognized route answers 200 with a `Route not found` body instead, as described in the API description above.
- `429` — Too many requests hit the API too quickly. Back off and retry.
- `500` — Something went wrong on the Cosmic side.

---

[API](https://skmtc.dev/cosmicjs/apis/cosmic-rest-api-v3.md) · [All operations](https://skmtc.dev/cosmicjs/apis/cosmic-rest-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cosmicjs/cosmic-rest-api-v3/revisions/e0aa2a0913b3/schema)