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: 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