Cosmic Objects API

openapi: 3.2.0
info:
  title: Cosmic REST API v3 Objects API
  version: 3.0.0
  summary: Read and write content, content models, and media in a Cosmic Bucket.
  description: 'The Cosmic v3 REST API for content operations against a single Bucket.


    ## When to use this API


    Reach for this API to model content (Object types and Metafields), create and query content (Objects), read version history (Revisions), and manage media metadata. A Bucket is the unit of isolation: every path below is scoped to one Bucket slug, and the access keys are per-Bucket.


    ## Authentication


    Reads use the Bucket read key as a `read_key` query parameter. Writes use the Bucket write key as an `Authorization: Bearer` header. Both keys are found under Bucket > Settings > API Access in the dashboard. There is no account-level credential: a key grants access to exactly one Bucket.


    ## Scope of this document


    This document describes only the endpoints served by `https://api.cosmicjs.com/v3`. Other documented parts of the Cosmic surface live on different hosts and are not yet specified here:


    - Agent signup, agent status, and user endpoints (`/v3/agents/*`, `/v3/users/*`) are served by `https://dapi.cosmicjs.com`. An agent with no prior Cosmic account should start at `POST https://dapi.cosmicjs.com/v3/agents/sign-up`.

    - Media upload (`POST /v3/buckets/{slug}/media`) is served by `https://workers.cosmicjs.com`. Media read, update, and delete are on this host and are specified below.

    - AI generation endpoints (`/v3/ai/*`) are served by `https://dapi.cosmicjs.com`.


    Be aware of one quirk when probing this host: an unrecognized path under `/v3` currently answers `200` with a body of `{"message":"Route not found", ...}` rather than a `404`. Treat that body, not the status line, as the signal that a path does not exist. The response names the host that serves the path you probably wanted.'
  termsOfService: https://www.cosmicjs.com/terms-of-service
  contact:
    name: Cosmic Support
    email: support@cosmicjs.com
    url: https://www.cosmicjs.com/contact
  license:
    name: Proprietary
    url: https://www.cosmicjs.com/terms-of-service
servers:
- url: https://api.cosmicjs.com/v3
  description: Production
security:
- readKey: []
tags:
- name: Objects
  description: Objects are the basic building blocks of content. Every Object belongs to an Object type and carries its field values under `metadata`.
  externalDocs:
    url: https://www.cosmicjs.com/docs/api/objects
paths:
  /buckets/{slug}/objects:
    parameters:
    - $ref: '#/components/parameters/BucketSlug'
    get:
      operationId: listObjects
      tags:
      - Objects
      summary: List and query Objects
      description: 'Query Objects in the Bucket. This is the main read endpoint and also the way to fetch a single Object by slug: pass `query={"type":"posts","slug":"my-post"}` and read the first element of `objects`.


        The `query` parameter is a URL-encoded JSON object following MongoDB comparison and logical operator syntax. Use `props` to limit the response to the fields you need, which matters because the API rejects responses over roughly 6 MB with a 413. Use `depth` to resolve Object Relationship Metafields into nested Objects. For large collections, prefer cursor pagination with `after` over large `skip` offsets.'
      parameters:
      - $ref: '#/components/parameters/ReadKey'
      - $ref: '#/components/parameters/PreviewToken'
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Props'
      - $ref: '#/components/parameters/ObjectStatus'
      - $ref: '#/components/parameters/ObjectSort'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Skip'
      - $ref: '#/components/parameters/Depth'
      - $ref: '#/components/parameters/After'
      - $ref: '#/components/parameters/UseCache'
      - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: The matching Objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: No Objects matched the query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 404
                message: No objects found for your query in bucket 'my-bucket'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createObject
      tags:
      - Objects
      summary: Create an Object
      description: 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.
      security:
      - writeKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectCreate'
            examples:
              blogPost:
                summary: A blog post
                value:
                  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
      responses:
        '200':
          description: The created Object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /buckets/{slug}/objects/batch:
    parameters:
    - $ref: '#/components/parameters/BucketSlug'
    post:
      operationId: batchObjects
      tags:
      - Objects
      summary: Batch create, update, and delete Objects
      description: Perform up to 25 Object operations in a single request. Each operation succeeds or fails independently, so inspect the `status` of every entry in the response rather than relying on the HTTP status alone. Prefer this over repeated single-Object calls when changing many Objects.
      security:
      - writeKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            examples:
              mixed:
                summary: One of each method
                value:
                  operations:
                  - method: add
                    object:
                      title: New Post
                      type: posts
                      metadata:
                        content: Hello
                  - method: edit
                    object_id: 5ff75368c2dfa81a91695cec
                    object:
                      title: Updated Title
                  - method: delete
                    object_id: 5ff75368c2dfa81a91695ced
      responses:
        '200':
          description: The per-operation results, in request order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /buckets/{slug}/objects/{object_id}:
    parameters:
    - $ref: '#/components/parameters/BucketSlug'
    - $ref: '#/components/parameters/ObjectId'
    get:
      operationId: getObject
      tags:
      - Objects
      summary: Get an Object by id
      description: Retrieve a single Object by its id. To fetch by slug instead, query the Objects list endpoint with `query={"type":"...","slug":"..."}`.
      parameters:
      - $ref: '#/components/parameters/ReadKey'
      - $ref: '#/components/parameters/PreviewToken'
      - $ref: '#/components/parameters/Props'
      - $ref: '#/components/parameters/ObjectStatus'
      - $ref: '#/components/parameters/Depth'
      - $ref: '#/components/parameters/UseCache'
      - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: The requested Object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      operationId: updateObject
      tags:
      - Objects
      summary: Update an Object
      description: Update an Object in place. Only the properties you send are changed, and within `metadata` only the keys you send are changed, so you can update a single Metafield without resending the rest. Set `status` to `published` to publish a draft.
      security:
      - writeKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectUpdate'
            examples:
              retitle:
                summary: Change the title
                value:
                  title: New Title Edit
              metafields:
                summary: Update Metafield values
                value:
                  metadata:
                    headline: This guitar amp is LOUD!
                    max_volume: 11
                    on_sale: true
              relationship:
                summary: Set Object Relationship Metafields by id
                value:
                  metadata:
                    author: 629e6cdda6f4f100091ae2e0
                    categories:
                    - 63bde47897d49d0008a270b3
                    - 63bde4c297d49d0008a270b4
      responses:
        '200':
          description: The updated Object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteObject
      tags:
      - Objects
      summary: Delete an Object
      description: 'Delete an Object from the Bucket. This is destructive and not reversible through the API: confirm with the user before calling it.'
      security:
      - writeKey: []
      parameters:
      - $ref: '#/components/parameters/TriggerWebhook'
      responses:
        '200':
          description: The Object was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Object with id '5ff75368c2dfa81a91695cec' deleted successfully from bucket.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ObjectResponse:
      type: object
      required:
      - object
      properties:
        object:
          $ref: '#/components/schemas/Object'
    BatchRequest:
      type: object
      required:
      - operations
      properties:
        operations:
          type: array
          minItems: 1
          maxItems: 25
          items:
            $ref: '#/components/schemas/BatchOperation'
      additionalProperties: false
    Error:
      type: object
      description: The error shape returned by every non-2xx response.
      required:
      - status
      - message
      properties:
        status:
          type: integer
          description: The HTTP status code, repeated in the body.
        message:
          type: string
          description: A human-readable explanation that tries to name the specific problem.
        documentation:
          type: string
          format: uri
          description: Where to look for the correct usage. Present on the `Route not found` response returned for unrecognized paths.
        hints:
          type: array
          description: Recovery suggestions, such as the host that actually serves the requested path. Present on the `Route not found` response returned for unrecognized paths.
          items:
            type: string
        details:
          type: array
          description: Per-field validation failures, when the error came from schema validation.
          items:
            type: object
            additionalProperties: true
    MessageResponse:
      type: object
      description: Returned by delete operations.
      required:
      - message
      properties:
        message:
          type: string
    ObjectCreate:
      type: object
      required:
      - title
      - type
      properties:
        title:
          type: string
        type:
          type: string
          description: Object type slug. The type must already exist.
        slug:
          type: string
          description: Derived from `title` when omitted.
        status:
          type: string
          enum:
          - published
          - draft
        content:
          type: string
          deprecated: true
        metadata:
          $ref: '#/components/schemas/Metadata'
        thumbnail:
          type: string
          description: Media `name`. The media must already exist in the Bucket.
        locale:
          type: string
        publish_at:
          type:
          - string
          - number
          description: UNIX millisecond timestamp.
        unpublish_at:
          type:
          - string
          - number
          description: UNIX millisecond timestamp.
        trigger_webhook:
          type: boolean
          description: Fire the corresponding Object webhook.
      additionalProperties: false
    ObjectUpdate:
      type: object
      description: Only the properties sent are changed. Within `metadata`, only the keys sent are changed.
      minProperties: 1
      properties:
        title:
          type: string
        slug:
          type: string
        status:
          type: string
          enum:
          - published
          - draft
        content:
          type: string
          deprecated: true
        metadata:
          $ref: '#/components/schemas/Metadata'
        thumbnail:
          type: string
          description: Media `name`.
        locale:
          type: string
        publish_at:
          type:
          - string
          - number
          - 'null'
          description: UNIX millisecond timestamp. Send `null` to clear.
        unpublish_at:
          type:
          - string
          - number
          - 'null'
          description: UNIX millisecond timestamp. Send `null` to clear.
        trigger_webhook:
          type: boolean
      additionalProperties: false
    ObjectListResponse:
      type: object
      required:
      - objects
      properties:
        objects:
          type: array
          items:
            $ref: '#/components/schemas/Object'
        total:
          type: integer
          description: Total number of Objects matching the query, ignoring `limit` and `skip`.
        limit:
          type: integer
          description: The `limit` applied to this response.
    BatchResponse:
      type: object
      required:
      - operations
      description: Results in request order. Operations succeed or fail independently, so check each `status`.
      properties:
        operations:
          type: array
          items:
            type: object
            properties:
              method:
                type: string
                enum:
                - add
                - edit
                - delete
              status:
                type: string
                enum:
                - success
                - error
              object:
                $ref: '#/components/schemas/Object'
              message:
                type: string
                description: Present on deletes and on failures.
            additionalProperties: true
    Object:
      type: object
      description: A single piece of content. Which properties are present depends on `props`.
      properties:
        id:
          type: string
          description: Unique identifier.
        type:
          type: string
          description: Object type slug.
        title:
          type: string
        slug:
          type: string
          description: Unique within the Object type. Localized versions of an Object share a slug and count as one Object against plan limits.
        status:
          type: string
          enum:
          - published
          - draft
        content:
          type:
          - string
          - 'null'
          description: HTML content. Deprecated in v3; use a Metafield instead.
          deprecated: true
        metadata:
          $ref: '#/components/schemas/Metadata'
        bucket:
          type: string
          description: Bucket id.
        thumbnail:
          type:
          - string
          - 'null'
          description: Media `name` of the Object thumbnail. Returned as a URL on read.
        locale:
          type:
          - string
          - 'null'
          description: Locale code, when the Object type has localization enabled.
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
          description: User id.
        modified_at:
          type: string
          format: date-time
        modified_by:
          type: string
          description: User id.
        published_at:
          type:
          - string
          - 'null'
          format: date-time
        publish_at:
          type:
          - string
          - number
          - 'null'
          description: UNIX millisecond timestamp for scheduled publishing.
        unpublish_at:
          type:
          - string
          - number
          - 'null'
          description: UNIX millisecond timestamp for scheduled unpublishing.
        assigned_to:
          type:
          - string
          - 'null'
          description: User id.
        assigned_by:
          type:
          - string
          - 'null'
          description: User id.
        assigned_at:
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: true
    Metadata:
      type: object
      description: '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.'
      additionalProperties: true
    BatchOperation:
      type: object
      required:
      - method
      description: One operation in a batch request.
      properties:
        method:
          type: string
          enum:
          - add
          - edit
          - delete
        object_id:
          type: string
          description: Required for `edit` and `delete`.
        object:
          type: object
          description: Required for `add` and `edit`. Accepts the same properties as the single-Object create and update endpoints.
          additionalProperties: true
        trigger_webhook:
          type: boolean
      additionalProperties: false
  responses:
    TooManyRequests:
      description: Too many requests hit the API too quickly. Back off and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 429
            message: Too many requests.
    NotFound:
      description: 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.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 404
            message: 'object with id: ''5ff75368c2dfa81a91695cec'' not found in bucket ''my-bucket'''
    Unauthorized:
      description: The access key is missing or incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 401
            message: Not authorized. This Bucket requires the correct read access key. Find this in Bucket > Settings in your Dashboard after logging in. Read the docs for more info https://www.cosmicjs.com/docs
    PaymentRequired:
      description: The Bucket needs to be upgraded before it can be used again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 402
            message: Payment required. Please upgrade your plan to continue.
    BadRequest:
      description: The request was invalid, most often a malformed `query` or a Metafield value that failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 400
            message: 'Metafield validation: invalid ''value'' for metafield with key: ''number'' and type: ''number'''
    PayloadTooLarge:
      description: The response exceeded the 6 MB limit. Narrow `props`, lower `limit`, or paginate.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 413
            message: Response too large. Reduce `limit`, use `props` to exclude large fields (e.g. metadata), or paginate with `skip`/`after`.
    InternalServerError:
      description: Something went wrong on the Cosmic side.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 500
            message: Internal server error. Please contact support@cosmicjs.com
  parameters:
    Depth:
      name: depth
      in: query
      required: false
      description: How many levels of Object Relationship Metafields to resolve into nested Objects. Circular references are rejected.
      schema:
        type: integer
        minimum: 0
        maximum: 3
        default: 0
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of results to return.
      schema:
        type: integer
        minimum: 1
        default: 1000
    Skip:
      name: skip
      in: query
      required: false
      description: 'Offset pagination: number of results to skip. Use `after` instead for large collections. Only one of `skip` and `after` may be used.'
      schema:
        type: integer
        minimum: 0
        default: 0
    Props:
      name: props
      in: query
      required: false
      description: Comma-separated list of properties to return, including nested metadata paths. Omit to return everything. Narrowing `props` is the main way to keep responses under the 6 MB response cap and to reduce latency.
      schema:
        type: string
      example: id,slug,title,metadata.content,metadata.image.imgix_url
    UseCache:
      name: useCache
      in: query
      required: false
      description: Set to `false` to bypass the cache and read through to the database. Guarantees you see writes you just made, at the cost of higher latency.
      schema:
        type: boolean
        default: true
    Query:
      name: query
      in: query
      required: false
      description: A URL-encoded JSON object used to filter results. Follows MongoDB comparison (`$eq`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$all`, `$ne`, `$nin`), evaluation (`$regex` with `$options`), and logical (`$and`, `$or`, `$not`, `$nor`) operators. Query Object Relationship Metafields by the related Object's `id`, not its `slug`.
      schema:
        type: string
      example: '{"type":"blog-posts","metadata.featured":true}'
    ObjectSort:
      name: sort
      in: query
      required: false
      description: Sort order. Prefix with `-` for descending. Sorting by `metadata.$key` requires that Metafield to be marked sortable under Object type > Settings, and is limited to two sortable Metafields per type.
      schema:
        type: string
        default: -order
        examples:
        - created_at
        - -created_at
        - modified_at
        - -modified_at
        - random
        - order
        - -order
        - metadata.price
        - -metadata.price
    ObjectStatus:
      name: status
      in: query
      required: false
      description: Which version of each Object to return. `any` returns the latest draft or published version.
      schema:
        type: string
        enum:
        - published
        - draft
        - any
        default: published
    PreviewToken:
      name: preview_token
      in: query
      required: false
      description: A short-lived JWT issued by the Cosmic dashboard (object editor > Preview). When present and valid, the request is treated as `status=any` so the latest draft is returned. Bound to one Bucket for one hour. Still requires `read_key`. Invalid or expired tokens return 401.
      schema:
        type: string
    ObjectId:
      name: object_id
      in: path
      required: true
      description: The Object id.
      schema:
        type: string
      example: 5ff75368c2dfa81a91695cec
    Pretty:
      name: pretty
      in: query
      required: false
      description: Set to `true` to indent the JSON response for human reading. Increases response size.
      schema:
        type: boolean
        default: false
    After:
      name: after
      in: query
      required: false
      description: 'Cursor pagination: the `id` of the last Object from the previous page. Follows the current `sort` order with `id` as a tiebreaker, works with any `sort` except `random`, and is more efficient than large `skip` offsets. Only one of `skip` and `after` may be used.'
      schema:
        type: string
    BucketSlug:
      name: slug
      in: path
      required: true
      description: The Bucket slug. Found under Bucket > Settings in the dashboard.
      schema:
        type: string
      example: my-bucket
    ReadKey:
      name: read_key
      in: query
      required: false
      description: The Bucket read key. Required unless the Bucket has no read key configured.
      schema:
        type: string
    TriggerWebhook:
      name: trigger_webhook
      in: query
      required: false
      description: Set to `true` to fire the corresponding webhook for this action.
      schema:
        type: boolean
        default: false
  securitySchemes:
    readKey:
      type: apiKey
      in: query
      name: read_key
      description: The Bucket read key, passed as a query parameter. Grants read access to a single Bucket and nothing else. Find it under Bucket > Settings > API Access in the dashboard. Buckets with no read key configured accept reads without one.
    writeKey:
      type: http
      scheme: bearer
      description: 'The Bucket write key, passed as `Authorization: Bearer <write_key>`. Grants read and write access to a single Bucket and nothing else. Find it under Bucket > Settings > API Access in the dashboard. The bare key without the `Bearer ` prefix is also accepted, but `Bearer` is the documented form. Buckets with no write key configured accept writes without one.'
externalDocs:
  description: Cosmic API documentation
  url: https://www.cosmicjs.com/docs/api