{"openapi":"3.1.0","info":{"title":"Umbraco Heartcore (BYOK) API","version":"0.1.0","description":"Umbraco Heartcore (BYOK) lets an AI assistant read your own Umbraco Heartcore data through the Umbraco Heartcore API with a key you supply (Heartcore API key (Settings > Headless > API Keys)). Read-only: 11 tools (list_root_content, get_content, get_content_by_url, list_content_by_type, list_content_children, list_content_descendants, list_content_ancestors, search_content, list_root_media,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-heartcore.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-heartcore/docs"},"termsOfService":"https://connectorbay.com/byok-heartcore/terms"},"servers":[{"url":"https://byok-heartcore.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-heartcore/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_root_content":{"post":{"operationId":"list_root_content","summary":"List the published content items at the root of the content tree, optionally only one content type. Use for \"What are th","description":"List the published content items at the root of the content tree, optionally only one content type. Use for \"What are the top-level pages of my Heartcore site\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"content_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only content of this content type alias (for example product).","title":"Content Type"}},"title":"list_root_contentArguments","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_content":{"post":{"operationId":"get_content","summary":"Get one published content item by id with all its properties, urls and links. Use for \"Show Heartcore content item df1eb","description":"Get one published content item by id with all its properties, urls and links. Use for \"Show Heartcore content item df1eb830-411b-4d41-a343-3917b76d533c\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Content item id (a GUID), from list_root_content or a children listing.","maxLength":200,"title":"Id","type":"string"},"depth":{"anyOf":[{"maximum":5,"minimum":0,"type":"integer"},{"type":"null"}],"default":1,"description":"How many levels of referenced content or media to include (0 to 5).","title":"Depth"}},"required":["id"],"title":"get_contentArguments","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_content_by_url":{"post":{"operationId":"get_content_by_url","summary":"Get one published content item by its site URL path, for example /products/tattoo/. Use for \"Which Heartcore content ite","description":"Get one published content item by its site URL path, for example /products/tattoo/. Use for \"Which Heartcore content item serves the URL /products/tattoo/\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"url":{"description":"URL path of the page, for example /products/tattoo/.","maxLength":200,"title":"Url","type":"string"},"depth":{"anyOf":[{"maximum":5,"minimum":0,"type":"integer"},{"type":"null"}],"default":1,"description":"How many levels of referenced content or media to include (0 to 5).","title":"Depth"}},"required":["url"],"title":"get_content_by_urlArguments","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_content_by_type":{"post":{"operationId":"list_content_by_type","summary":"List published content items of one content type alias, paged. Use for \"List all Heartcore product pages\".","description":"List published content items of one content type alias, paged. Use for \"List all Heartcore product pages\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"content_type":{"description":"Content type alias, for example product.","maxLength":200,"title":"Content Type","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page.","title":"Page Size"}},"required":["content_type"],"title":"list_content_by_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_content_children":{"post":{"operationId":"list_content_children","summary":"List the published children of a content item, paged, optionally only one content type. Use for \"What pages sit under He","description":"List the published children of a content item, paged, optionally only one content type. Use for \"What pages sit under Heartcore item ec4aafcc-0c25-4f25-a8fe-705bfae1d324\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Content item id (a GUID), from list_root_content or a children listing.","maxLength":200,"title":"Id","type":"string"},"content_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only content of this content type alias (for example product).","title":"Content Type"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page.","title":"Page Size"}},"required":["id"],"title":"list_content_childrenArguments","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_content_descendants":{"post":{"operationId":"list_content_descendants","summary":"List every published descendant of a content item, paged, optionally only one content type. Use for \"List everything bel","description":"List every published descendant of a content item, paged, optionally only one content type. Use for \"List everything below the products section in Heartcore\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Content item id (a GUID), from list_root_content or a children listing.","maxLength":200,"title":"Id","type":"string"},"content_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only content of this content type alias (for example product).","title":"Content Type"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page.","title":"Page Size"}},"required":["id"],"title":"list_content_descendantsArguments","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_content_ancestors":{"post":{"operationId":"list_content_ancestors","summary":"List the ancestors of a content item up to the root, optionally only one content type. Use for \"What is the breadcrumb p","description":"List the ancestors of a content item up to the root, optionally only one content type. Use for \"What is the breadcrumb path of Heartcore item df1eb830-411b-4d41-a343-3917b76d533c\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Content item id (a GUID), from list_root_content or a children listing.","maxLength":200,"title":"Id","type":"string"},"content_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only content of this content type alias (for example product).","title":"Content Type"}},"required":["id"],"title":"list_content_ancestorsArguments","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/search_content":{"post":{"operationId":"search_content","summary":"Search published content by keyword, paged. Use for \"Which Heartcore pages mention jacket\".","description":"Search published content by keyword, paged. Use for \"Which Heartcore pages mention jacket\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"description":"Search keyword.","maxLength":200,"title":"Term","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page.","title":"Page Size"}},"required":["term"],"title":"search_contentArguments","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_root_media":{"post":{"operationId":"list_root_media","summary":"List the media items and folders at the root of the media library. Use for \"What folders are in my Heartcore media libra","description":"List the media items and folders at the root of the media library. Use for \"What folders are in my Heartcore media library\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_root_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":{"post":{"operationId":"get_media","summary":"Get one media item by id with its type, url, size and image dimensions. Use for \"How big is Heartcore media item 662af6c","description":"Get one media item by id with its type, url, size and image dimensions. Use for \"How big is Heartcore media item 662af6ca-411a-4c93-a6c7-22c4845698e7\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Media item id (a GUID), from list_root_media or list_media_children.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_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/list_media_children":{"post":{"operationId":"list_media_children","summary":"List the media items inside a media folder, paged. Use for \"Which files are in the Design folder of my Heartcore media l","description":"List the media items inside a media folder, paged. Use for \"Which files are in the Design folder of my Heartcore media library\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Media item id (a GUID), from list_root_media or list_media_children.","maxLength":200,"title":"Id","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page.","title":"Page Size"}},"required":["id"],"title":"list_media_childrenArguments","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}}}}