{"openapi":"3.1.0","info":{"title":"Cosmic (BYOK) API","version":"0.1.0","description":"Cosmic (BYOK) lets an AI assistant read your own Cosmic data through the Cosmic API with a key you supply (bucket read key). Read-only: 9 tools (list_object_types, get_object_type, list_objects, get_object, list_object_revisions, get_object_revision, list_media, get_media_item, list_blocks). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-cosmic.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-cosmic/docs"},"termsOfService":"https://connectorbay.com/byok-cosmic/terms"},"servers":[{"url":"https://byok-cosmic.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-cosmic/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_object_types":{"post":{"operationId":"list_object_types","summary":"List the bucket's object types (content models) with their fields (metafields), singleton flag and locales. Use for \"Wha","description":"List the bucket's object types (content models) with their fields (metafields), singleton flag and locales. Use for \"What content types does my Cosmic bucket have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Your Cosmic bucket slug, shown under Bucket Settings > API Access.","maxLength":200,"title":"Slug","type":"string"}},"required":["slug"],"title":"list_object_typesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_object_type":{"post":{"operationId":"get_object_type","summary":"Get one object type by its slug, with all its metafield definitions. Use for \"Show the 'blog-posts' content type in Cosm","description":"Get one object type by its slug, with all its metafield definitions. Use for \"Show the 'blog-posts' content type in Cosmic\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Your Cosmic bucket slug, shown under Bucket Settings > API Access.","maxLength":200,"title":"Slug","type":"string"},"type_slug":{"description":"Object type slug, for example 'blog-posts'.","maxLength":200,"title":"Type Slug","type":"string"}},"required":["slug","type_slug"],"title":"get_object_typeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_objects":{"post":{"operationId":"list_objects","summary":"List or filter the bucket's objects (content entries). Filter with a JSON query such as {\"type\":\"blog-posts\"}; page with","description":"List or filter the bucket's objects (content entries). Filter with a JSON query such as {\"type\":\"blog-posts\"}; page with limit and skip or the last id. Use for \"List my Cosmic blog posts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Your Cosmic bucket slug, shown under Bucket Settings > API Access.","maxLength":200,"title":"Slug","type":"string"},"query":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"JSON filter, for example {\"type\":\"blog-posts\"} or {\"type\":\"blog-posts\",\"metadata.featured\":true}. Supports comparison operators such as $in, $gt, $ne.","title":"Query"},"props":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated properties to return, including nested paths such as metadata.image.imgix_url; leave out for everything. Narrowing it keeps answers small.","title":"Props"},"status":{"anyOf":[{"enum":["published","draft","any"],"type":"string"},{"type":"null"}],"default":"published","description":"Which version to read: published (default), draft or any (latest draft or published). Drafts may need a key with draft access.","title":"Status"},"sort":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Sort order; prefix with - for descending, for example '-created_at' or 'title'.","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 1000).","title":"Limit"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Skip"},"after":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"For large collections: the id of the last object of the previous page, in place of skip.","title":"After"},"depth":{"anyOf":[{"maximum":3,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many levels of object relationships to expand (0 to 3).","title":"Depth"}},"required":["slug"],"title":"list_objectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_object":{"post":{"operationId":"get_object","summary":"Get one object by its ID with its fields, status, locale and dates. Use for \"Show Cosmic object 5ff75368c2dfa81a91695cec","description":"Get one object by its ID with its fields, status, locale and dates. Use for \"Show Cosmic object 5ff75368c2dfa81a91695cec\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Your Cosmic bucket slug, shown under Bucket Settings > API Access.","maxLength":200,"title":"Slug","type":"string"},"object_id":{"description":"Object ID, for example '5ff75368c2dfa81a91695cec'.","maxLength":200,"title":"Object Id","type":"string"},"props":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated properties to return, including nested paths such as metadata.image.imgix_url; leave out for everything. Narrowing it keeps answers small.","title":"Props"},"status":{"anyOf":[{"enum":["published","draft","any"],"type":"string"},{"type":"null"}],"default":"published","description":"Which version to read: published (default), draft or any (latest draft or published). Drafts may need a key with draft access.","title":"Status"},"depth":{"anyOf":[{"maximum":3,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many levels of object relationships to expand (0 to 3).","title":"Depth"}},"required":["slug","object_id"],"title":"get_objectArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_object_revisions":{"post":{"operationId":"list_object_revisions","summary":"List the saved revisions of one object, newest first by default, with status, title and dates. Use for \"What is the revi","description":"List the saved revisions of one object, newest first by default, with status, title and dates. Use for \"What is the revision history of this Cosmic object\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Your Cosmic bucket slug, shown under Bucket Settings > API Access.","maxLength":200,"title":"Slug","type":"string"},"object_id":{"description":"Object ID.","maxLength":200,"title":"Object Id","type":"string"},"sort":{"anyOf":[{"enum":["created_at","-created_at"],"type":"string"},{"type":"null"}],"default":"-created_at","description":"Sort by created_at: created_at (oldest first) or -created_at (newest first).","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 1000).","title":"Limit"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Skip"}},"required":["slug","object_id"],"title":"list_object_revisionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_object_revision":{"post":{"operationId":"get_object_revision","summary":"Get one revision of an object by its revision ID, including the stored fields. Use for \"Show this revision of the Cosmic","description":"Get one revision of an object by its revision ID, including the stored fields. Use for \"Show this revision of the Cosmic object\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Your Cosmic bucket slug, shown under Bucket Settings > API Access.","maxLength":200,"title":"Slug","type":"string"},"object_id":{"description":"Object ID.","maxLength":200,"title":"Object Id","type":"string"},"revision_id":{"description":"Revision ID from list_object_revisions.","maxLength":200,"title":"Revision Id","type":"string"}},"required":["slug","object_id","revision_id"],"title":"get_object_revisionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_media":{"post":{"operationId":"list_media","summary":"List the bucket's media library files with name, type, size, dimensions, alt text and URLs. Filter with a JSON query. Us","description":"List the bucket's media library files with name, type, size, dimensions, alt text and URLs. Filter with a JSON query. Use for \"What images are in my Cosmic media library\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Your Cosmic bucket slug, shown under Bucket Settings > API Access.","maxLength":200,"title":"Slug","type":"string"},"query":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"JSON filter, for example {\"folder\":\"blog\"} or {\"type\":\"image/png\"}.","title":"Query"},"props":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated properties to return, including nested paths such as metadata.image.imgix_url; leave out for everything. Narrowing it keeps answers small.","title":"Props"},"sort":{"anyOf":[{"enum":["created_at","-created_at","modified_at","-modified_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order.","title":"Sort"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 1000).","title":"Limit"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Skip"}},"required":["slug"],"title":"list_mediaArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_media_item":{"post":{"operationId":"get_media_item","summary":"Get one media library file by its ID with URLs, dimensions and alt text. Use for \"Show Cosmic media item 602fd622853cca4","description":"Get one media library file by its ID with URLs, dimensions and alt text. Use for \"Show Cosmic media item 602fd622853cca45f4c9fd96\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Your Cosmic bucket slug, shown under Bucket Settings > API Access.","maxLength":200,"title":"Slug","type":"string"},"media_id":{"description":"Media ID, for example '602fd622853cca45f4c9fd96'.","maxLength":200,"title":"Media Id","type":"string"},"props":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated properties to return, including nested paths such as metadata.image.imgix_url; leave out for everything. Narrowing it keeps answers small.","title":"Props"}},"required":["slug","media_id"],"title":"get_media_itemArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_blocks":{"post":{"operationId":"list_blocks","summary":"List the reusable content blocks defined in the bucket. Use for \"Which content blocks does my Cosmic bucket define\".","description":"List the reusable content blocks defined in the bucket. Use for \"Which content blocks does my Cosmic bucket define\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Your Cosmic bucket slug, shown under Bucket Settings > API Access.","maxLength":200,"title":"Slug","type":"string"}},"required":["slug"],"title":"list_blocksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}