Cosmic Blocks API

openapi: 3.2.0
info:
  title: Cosmic REST API v3 Blocks 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: Blocks
  description: Content Blocks configured on the Bucket.
paths:
  /buckets/{slug}/blocks:
    parameters:
    - $ref: '#/components/parameters/BucketSlug'
    get:
      operationId: listBlocks
      tags:
      - Blocks
      summary: List content Blocks
      description: Retrieve the content Blocks configured on the Bucket. Returns an empty array when the Bucket has none.
      parameters:
      - $ref: '#/components/parameters/ReadKey'
      - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: The Bucket's content Blocks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlocksResponse'
        '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:
  parameters:
    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
    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
  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
    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
    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.
  schemas:
    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
    BlocksResponse:
      type: object
      required:
      - blocks
      properties:
        blocks:
          type: array
          description: The Bucket's content Blocks. Empty when none are configured.
          items:
            type: object
            additionalProperties: true
  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