Cosmic Media API

Media are the images, files, and documents in a Bucket. Upload is served by workers.cosmicjs.com and is not part of this document.

GitHub OpenAPI

Operations 4

GET /buckets/{slug}/media List and query media #
GET /buckets/{slug}/media/{media_id} Get a media item by id #
PATCH /buckets/{slug}/media/{media_id} Update media metadata #
DELETE /buckets/{slug}/media/{media_id} Delete a media item #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/cosmicjs-com:cosmicjs-com-media-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

cosmicjs-com-media-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Cosmic REST API v3 Media 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: Media
  description: Media are the images, files, and documents in a Bucket. Upload is served by workers.cosmicjs.com and is not part of this document.
  externalDocs:
    url: https://www.cosmicjs.com/docs/api/media
paths:
  /buckets/{slug}/media:
    parameters:
    - $ref: '#/components/parameters/BucketSlug'
    get:
      operationId: listMedia
      tags:
      - Media
      summary: List and query media
      description: 'Query media in the Bucket. This is also how you fetch a single media item by name: pass `query={"name":"7f9403a32f29-toucan.jpg"}`.


        The `name` of a media item is the value you assign to a File or Image Metafield when creating or updating an Object. Upload is not part of this host: `POST /v3/buckets/{slug}/media` is served by `https://workers.cosmicjs.com`.'
      parameters:
      - $ref: '#/components/parameters/ReadKey'
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Props'
      - $ref: '#/components/parameters/MediaSort'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Skip'
      - $ref: '#/components/parameters/UseCache'
      - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: The matching media.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /buckets/{slug}/media/{media_id}:
    parameters:
    - $ref: '#/components/parameters/BucketSlug'
    - $ref: '#/components/parameters/MediaId'
    get:
      operationId: getMedia
      tags:
      - Media
      summary: Get a media item by id
      description: Retrieve a single media item by its id. To fetch by file name instead, query the media list endpoint with `query={"name":"..."}`.
      parameters:
      - $ref: '#/components/parameters/ReadKey'
      - $ref: '#/components/parameters/Props'
      - $ref: '#/components/parameters/UseCache'
      - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: The requested media item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaResponse'
        '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: updateMedia
      tags:
      - Media
      summary: Update media metadata
      description: 'Update the folder, alt text, or user metadata on a media item. The underlying file is not replaced: to change the file, upload a new one via `https://workers.cosmicjs.com` and repoint the referencing Metafields.'
      security:
      - writeKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaUpdate'
            examples:
              altTextAndFolder:
                summary: Set alt text and move to a folder
                value:
                  folder: national-parks
                  alt_text: Picture of Grand Teton National Park
      responses:
        '200':
          description: The updated media item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaResponse'
        '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: deleteMedia
      tags:
      - Media
      summary: Delete a media item
      description: 'Delete a media item from the Bucket. The file is removed from storage and the CDN caches are purged, so its URL stops working. Objects and Metafields that reference the media are not updated automatically: clear those references yourself. This is destructive and not reversible through the API.'
      security:
      - writeKey: []
      parameters:
      - $ref: '#/components/parameters/TriggerWebhook'
      responses:
        '200':
          description: The media item was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Media with id '602fd622853cca45f4c9fd96' 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:
  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:
    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
    MediaId:
      name: media_id
      in: path
      required: true
      description: The media id.
      schema:
        type: string
      example: 602fd622853cca45f4c9fd96
    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}'
    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
    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
    MediaSort:
      name: sort
      in: query
      required: false
      description: Sort order. Prefix with `-` for descending.
      schema:
        type: string
        enum:
        - created_at
        - -created_at
        - modified_at
        - -modified_at
        - random
  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
    MessageResponse:
      type: object
      description: Returned by delete operations.
      required:
      - message
      properties:
        message:
          type: string
    MediaUpdate:
      type: object
      description: Only the properties sent are changed. The underlying file cannot be replaced through this endpoint.
      minProperties: 1
      properties:
        folder:
          type: string
        alt_text:
          type: string
          description: Images only.
        metadata:
          type: object
          additionalProperties: true
        trigger_webhook:
          type: boolean
      additionalProperties: false
    MediaResponse:
      type: object
      required:
      - media
      properties:
        media:
          $ref: '#/components/schemas/Media'
    MediaListResponse:
      type: object
      required:
      - media
      properties:
        media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        total:
          type: integer
        limit:
          type: integer
    Media:
      type: object
      description: An image, file, or document in the Bucket.
      properties:
        id:
          type: string
        name:
          type: string
          description: Unique file name within the Bucket. This is the value you assign to a File or Image Metafield.
        original_name:
          type: string
          description: The file name as uploaded.
        size:
          type:
          - integer
          - string
          description: File size in bytes.
        type:
          type: string
          description: MIME type.
          examples:
          - image/png
          - video/mp4
          - application/pdf
        bucket:
          type: string
          description: Bucket id.
        folder:
          type:
          - string
          - 'null'
        alt_text:
          type:
          - string
          - 'null'
          description: Images only.
        width:
          type:
          - integer
          - 'null'
          description: Pixel width. Images only.
        height:
          type:
          - integer
          - 'null'
          description: Pixel height. Images only.
        url:
          type: string
          format: uri
          description: CDN URL.
        imgix_url:
          type: string
          format: uri
          description: imgix URL, which accepts image processing query parameters.
        metadata:
          type:
          - object
          - 'null'
          description: Arbitrary JSON metadata you attach to the media.
          additionalProperties: true
        created_at:
          type: string
          format: date-time
      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