{"openapi":"3.1.0","info":{"title":"Cosmic REST API v3","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.\n\n## When to use this API\n\nReach 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.\n\n## Authentication\n\nReads 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.\n\n## Scope of this document\n\nThis 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:\n\n- 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`.\n- 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.\n- AI generation endpoints (`/v3/ai/*`) are served by `https://dapi.cosmicjs.com`.\n\nBe 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"}},"externalDocs":{"description":"Cosmic API documentation","url":"https://www.cosmicjs.com/docs/api"},"servers":[{"url":"https://api.cosmicjs.com/v3","description":"Production"}],"tags":[{"name":"Status","description":"Service health."},{"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"}},{"name":"Object types","description":"Object types define the content model: the Metafields, localization settings, and display options shared by every Object in the type.","externalDocs":{"url":"https://www.cosmicjs.com/docs/api/object-types"}},{"name":"Object revisions","description":"Revisions are the version history of an Object. They can be created and read, but never edited or deleted.","externalDocs":{"url":"https://www.cosmicjs.com/docs/api/revisions"}},{"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"}},{"name":"Blocks","description":"Content Blocks configured on the Bucket."}],"security":[{"readKey":[]}],"paths":{"/status":{"get":{"operationId":"getStatus","tags":["Status"],"summary":"Check API status","description":"Confirm the API is reachable and learn which AWS region served the request. Requires no authentication, so it is safe to use as a connectivity check before supplying keys.","security":[],"responses":{"200":{"description":"The API is reachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","tags":["Status"],"summary":"Get this OpenAPI document","description":"Retrieve the machine-readable description of this API. Requires no authentication. Also served from `https://www.cosmicjs.com/openapi.json`, which proxies this endpoint.","security":[],"responses":{"200":{"description":"The OpenAPI 3.1 document describing this API.","content":{"application/json":{"schema":{"type":"object","description":"An OpenAPI 3.1 document.","required":["openapi","info","paths"],"properties":{"openapi":{"type":"string","examples":["3.1.0"]},"info":{"type":"object","additionalProperties":true},"paths":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/buckets/{slug}/object-types":{"parameters":[{"$ref":"#/components/parameters/BucketSlug"}],"get":{"operationId":"listObjectTypes","tags":["Object types"],"summary":"List Object types","description":"Retrieve every Object type in the Bucket, each with its full Metafield model. Use this to discover the content model before creating or querying Objects: the `slug` of each type is what you pass as `type` in Object queries, and the `metafields` array tells you which `metadata` keys an Object of that type accepts.","parameters":[{"$ref":"#/components/parameters/ReadKey"},{"$ref":"#/components/parameters/Pretty"}],"responses":{"200":{"description":"The Object types in the Bucket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectTypeListResponse"}}}},"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"}}},"post":{"operationId":"createObjectType","tags":["Object types"],"summary":"Create an Object type","description":"Create a new Object type, defining the content model that its Objects will follow. Only `title` is required; the `slug` is derived from the title when omitted. Define `metafields` here so that Objects created in this type can carry the corresponding `metadata` values.","security":[{"writeKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectTypeCreate"},"examples":{"minimal":{"summary":"Title only","value":{"title":"Motorcycles"}},"withMetafields":{"summary":"With a content model","value":{"title":"Bikes","slug":"bikes","singular":"Bike","emoji":"🏍️","metafields":[{"title":"Image","key":"image","type":"file","required":true,"media_validation_type":"image"},{"title":"Headline","key":"headline","type":"text","required":false}]}}}}}},"responses":{"200":{"description":"The created Object type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectTypeResponse"}}}},"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}/object-types/{type_slug}":{"parameters":[{"$ref":"#/components/parameters/BucketSlug"},{"$ref":"#/components/parameters/TypeSlug"}],"get":{"operationId":"getObjectType","tags":["Object types"],"summary":"Get an Object type","description":"Retrieve a single Object type by its slug, including the full Metafield model. Use this when you already know the type and want its field definitions without listing every type in the Bucket.","parameters":[{"$ref":"#/components/parameters/ReadKey"},{"$ref":"#/components/parameters/Pretty"}],"responses":{"200":{"description":"The requested Object type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectTypeResponse"}}}},"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":"updateObjectType","tags":["Object types"],"summary":"Update an Object type","description":"Update an Object type in place. Only the properties you send are changed. Sending `metafields` replaces the whole array, so read the type first and send the complete list rather than only the field you want to alter.","security":[{"writeKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectTypeUpdate"},"examples":{"rename":{"summary":"Rename a type","value":{"title":"Motorcycles","slug":"motorcycles","singular":"Motorcycle"}}}}}},"responses":{"200":{"description":"The updated Object type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectTypeResponse"}}}},"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":"deleteObjectType","tags":["Object types"],"summary":"Delete an Object type","description":"Delete an Object type and every Object in it. 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 type was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"},"example":{"message":"Object Type with slug 'bikes' 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"}}}},"/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"}}}},"/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`.\n\nThe `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"}}}},"/buckets/{slug}/objects/{object_id}/revisions":{"parameters":[{"$ref":"#/components/parameters/BucketSlug"},{"$ref":"#/components/parameters/ObjectId"}],"get":{"operationId":"listObjectRevisions","tags":["Object revisions"],"summary":"List an Object's revisions","description":"Retrieve the version history of an Object, newest first by default. Revisions are immutable.","parameters":[{"$ref":"#/components/parameters/ReadKey"},{"$ref":"#/components/parameters/PreviewToken"},{"$ref":"#/components/parameters/Props"},{"$ref":"#/components/parameters/RevisionSort"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Skip"},{"$ref":"#/components/parameters/UseCache"},{"$ref":"#/components/parameters/Pretty"}],"responses":{"200":{"description":"The Object's revisions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevisionListResponse"}}}},"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"}}},"post":{"operationId":"createObjectRevision","tags":["Object revisions"],"summary":"Add a revision to an Object","description":"Create a new revision of an Object without publishing it. The revision is created with status `draft`; publish it by updating the Object itself with `status: published`. Use this to stage an edit for review rather than changing live content.","security":[{"writeKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevisionCreate"},"examples":{"draftEdit":{"summary":"Stage a title and content edit","value":{"title":"Updated Blog Post Title","metadata":{"content":"This is the updated content for the blog post...","featured_post":true},"status":"draft"}}}}}},"responses":{"200":{"description":"The created revision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevisionResponse"}}}},"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}/revisions/{revision_id}":{"parameters":[{"$ref":"#/components/parameters/BucketSlug"},{"$ref":"#/components/parameters/ObjectId"},{"$ref":"#/components/parameters/RevisionId"}],"get":{"operationId":"getObjectRevision","tags":["Object revisions"],"summary":"Get a single revision","description":"Retrieve one revision of an Object by its id, including the `metadata` values as they were at that point in history.","parameters":[{"$ref":"#/components/parameters/ReadKey"},{"$ref":"#/components/parameters/PreviewToken"},{"$ref":"#/components/parameters/Props"},{"$ref":"#/components/parameters/UseCache"},{"$ref":"#/components/parameters/Pretty"}],"responses":{"200":{"description":"The requested revision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevisionResponse"}}}},"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}/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\"}`.\n\nThe `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":{"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."}},"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"},"TypeSlug":{"name":"type_slug","in":"path","required":true,"description":"The Object type slug, unique within the Bucket.","schema":{"type":"string"},"example":"blog-posts"},"ObjectId":{"name":"object_id","in":"path","required":true,"description":"The Object id.","schema":{"type":"string"},"example":"5ff75368c2dfa81a91695cec"},"RevisionId":{"name":"revision_id","in":"path","required":true,"description":"The revision id.","schema":{"type":"string"},"example":"64fe8a1b24090e0008683e53"},"MediaId":{"name":"media_id","in":"path","required":true,"description":"The media id.","schema":{"type":"string"},"example":"602fd622853cca45f4c9fd96"},"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"}},"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"}},"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}"},"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"},"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"}},"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"]}},"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"]}},"RevisionSort":{"name":"sort","in":"query","required":false,"description":"Sort order. Prefix with `-` for descending.","schema":{"type":"string","enum":["created_at","-created_at"],"default":"-created_at"}},"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}},"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}},"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"}},"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}},"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}},"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}}},"responses":{"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'"}}}},"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."}}}},"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'"}}}},"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`."}}}},"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."}}}},"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"}}}}},"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}}}},"StatusResponse":{"type":"object","properties":{"message":{"type":"string"},"region":{"type":"string","description":"The AWS region that served the request.","examples":["us-west-2"]}}},"MessageResponse":{"type":"object","description":"Returned by delete operations.","required":["message"],"properties":{"message":{"type":"string"}}},"Metadata":{"type":"object","description":"Values of the Metafields defined on the Object type, keyed by Metafield `key`.\n\nThe value shape follows the Metafield type, and differs between write and read for two of them:\n\n- Text, textarea, markdown, and HTML Metafields are strings. Number Metafields are numbers, switches are booleans, dates are ISO 8601 strings.\n- 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.\n- 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`.\n- Repeater Metafields are arrays of objects keyed by the child Metafield keys.","additionalProperties":true},"Metafield":{"type":"object","description":"One field in an Object type's content model.","required":["title","key","type"],"properties":{"id":{"type":"string","description":"Assigned by Cosmic. Omit when creating."},"title":{"type":"string","description":"Label shown to editors in the dashboard."},"key":{"type":"string","description":"The key used in an Object's `metadata`."},"type":{"type":"string","description":"The Metafield type. See the Metafields documentation for the full list and the value shape each one expects.","examples":["text","textarea","html-textarea","markdown","number","switch","date","file","files","object","objects","select-dropdown","radio-buttons","check-boxes","json","parent","repeater"]},"value":{"description":"Default value for the Metafield."},"helptext":{"type":"string","description":"Guidance shown to editors beneath the field."},"required":{"type":"boolean","description":"Whether Objects in this type must supply a value."},"media_validation_type":{"type":"string","description":"Restricts uploads for File Metafields.","examples":["image","video","audio"]},"repeater_fields":{"type":"array","description":"Child Metafields, for `repeater` types.","items":{"$ref":"#/components/schemas/Metafield"}},"options":{"type":"array","description":"Choices for select, radio, and checkbox types.","items":{"type":"object","additionalProperties":true}}},"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},"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},"ObjectResponse":{"type":"object","required":["object"],"properties":{"object":{"$ref":"#/components/schemas/Object"}}},"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."}}},"ObjectType":{"type":"object","description":"The content model shared by every Object in the type.","properties":{"id":{"type":"string"},"title":{"type":"string"},"singular":{"type":"string","description":"Singular label, used in dashboard copy such as \"New Bike\"."},"slug":{"type":"string","description":"Unique within the Bucket. This is the value you pass as `type` when querying Objects."},"singleton":{"type":"boolean","description":"Whether the type holds exactly one Object, as for a home page."},"emoji":{"type":"string","description":"Unicode emoji shown beside the type in the dashboard."},"metafields":{"type":"array","items":{"$ref":"#/components/schemas/Metafield"}},"options":{"type":"object","properties":{"slug_field":{"type":"boolean","description":"Whether editors can see and edit the slug field."}},"additionalProperties":true},"localization":{"type":"boolean","description":"Whether Objects in this type can exist in multiple locales."},"locales":{"type":"array","description":"Locale codes available in this type.","items":{"type":"string"}},"priority_locale":{"type":["string","null"],"description":"Default locale for new Objects in this type."},"created_at":{"type":"string","format":"date-time"},"modified_at":{"type":"string","format":"date-time"}},"additionalProperties":true},"ObjectTypeCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"singular":{"type":"string"},"slug":{"type":"string","description":"Derived from `title` when omitted."},"singleton":{"type":"boolean"},"emoji":{"type":"string"},"metafields":{"type":"array","items":{"$ref":"#/components/schemas/Metafield"}},"options":{"type":"object","additionalProperties":true},"localization":{"type":"boolean","default":false},"locales":{"type":"array","items":{"type":"string"}},"priority_locale":{"type":"string"}},"additionalProperties":false},"ObjectTypeUpdate":{"type":"object","description":"Only the properties sent are changed. Sending `metafields` replaces the entire array.","minProperties":1,"properties":{"title":{"type":"string"},"singular":{"type":"string"},"slug":{"type":"string"},"singleton":{"type":"boolean"},"emoji":{"type":"string"},"metafields":{"type":"array","items":{"$ref":"#/components/schemas/Metafield"}},"options":{"type":"object","additionalProperties":true},"localization":{"type":"boolean"},"locales":{"type":"array","items":{"type":"string"}},"priority_locale":{"type":"string"}},"additionalProperties":false},"ObjectTypeResponse":{"type":"object","required":["object_type"],"properties":{"object_type":{"$ref":"#/components/schemas/ObjectType"}}},"ObjectTypeListResponse":{"type":"object","required":["object_types"],"properties":{"object_types":{"type":"array","items":{"$ref":"#/components/schemas/ObjectType"}}}},"Revision":{"type":"object","description":"An immutable snapshot of an Object at a point in time.","properties":{"id":{"type":"string"},"object_id":{"type":"string","description":"The Object this revision belongs to."},"type":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["published","draft"]},"content":{"type":["string","null"],"deprecated":true},"metadata":{"$ref":"#/components/schemas/Metadata"},"bucket":{"type":"string"},"thumbnail":{"type":["string","null"]},"locale":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string"},"modified_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":true},"RevisionCreate":{"type":"object","description":"Creates a draft revision. Publish by updating the Object with `status: published`.","properties":{"title":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["published","draft"],"default":"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"],"description":"UNIX millisecond timestamp."},"unpublish_at":{"type":["string","number"],"description":"UNIX millisecond timestamp."},"trigger_webhook":{"type":"boolean"}},"additionalProperties":false},"RevisionResponse":{"type":"object","required":["revision"],"properties":{"revision":{"$ref":"#/components/schemas/Revision"}}},"RevisionListResponse":{"type":"object","required":["revisions"],"properties":{"revisions":{"type":"array","items":{"$ref":"#/components/schemas/Revision"}},"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},"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"}}},"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}}}},"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},"BatchRequest":{"type":"object","required":["operations"],"properties":{"operations":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/BatchOperation"}}},"additionalProperties":false},"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}}}}}}}