{"openapi":"3.1.0","info":{"title":"The Beautiful Machine Magazine — mcpCMS Content & Agent API","version":"1.1.0","description":"Agent-native Headless CMS REST API for The Beautiful Machine Magazine (Detroit & Global Urban Fashion, Streetwear, Music & Culture), built for ChatGPT Custom Actions, Gemini Function Calling, MCP tools, and human editors.","contact":{"name":"The Beautiful Machine Editorial & Engineering Team","url":"https://github.com/jaffadan/mcpCMS"}},"servers":[{"url":"http://the-beautiful-machine-mag.onrender.com","description":"Active mcpCMS Core API Gateway"}],"paths":{"/api/content":{"get":{"operationId":"listArticles","summary":"List content articles","description":"Fetch a list of articles from the CMS catalog with optional filters for status, category, tag, and pagination.","parameters":[{"name":"status","in":"query","required":false,"description":"Filter by lifecycle status (draft, in_review, published, archived)","schema":{"type":"string","enum":["draft","in_review","published","archived"]}},{"name":"category","in":"query","required":false,"description":"Filter by content category (e.g. Fashion & Streetwear, Culture, Music & Sound, Relationships, Politics & City, People & Profiles, Personal Growth)","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Filter articles by a specific tag","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Number of articles to return (1-100, default 20)","schema":{"type":"integer","default":20}},{"name":"offset","in":"query","required":false,"description":"Number of articles to skip for pagination","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Articles retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentItem"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"post":{"operationId":"createArticle","summary":"Create a new article","description":"Creates a new content item in the CMS. Automatically calculates vector embeddings for semantic search.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateArticleInput"}}}},"responses":{"201":{"description":"Article created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ContentItem"}}}}}},"400":{"description":"Validation failed"}}}},"/api/content/{idOrSlug}":{"get":{"operationId":"getArticle","summary":"Get single article by ID or slug","description":"Retrieves the complete article details including full Markdown content, metadata, and tags by its unique ID or URL slug.","parameters":[{"name":"idOrSlug","in":"path","required":true,"description":"Article ID (e.g. art_mcp_001) or slug (e.g. getting-started-with-mcp-and-headless-cms)","schema":{"type":"string"}}],"responses":{"200":{"description":"Article found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ContentItem"}}}}}},"404":{"description":"Article not found"}}}},"/api/content/{id}":{"put":{"operationId":"updateArticle","summary":"Update an article","description":"Update fields of an existing article by ID. Automatically refreshes vector embeddings if content or metadata changes.","parameters":[{"name":"id","in":"path","required":true,"description":"Unique ID of the article to update","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateArticleInput"}}}},"responses":{"200":{"description":"Article updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ContentItem"}}}}}},"404":{"description":"Article not found"}}},"delete":{"operationId":"deleteArticle","summary":"Delete an article","description":"Permanently removes an article from the CMS store.","parameters":[{"name":"id","in":"path","required":true,"description":"Article ID to delete","schema":{"type":"string"}}],"responses":{"200":{"description":"Article deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"404":{"description":"Article not found"}}}},"/api/content/{id}/publish":{"post":{"operationId":"publishArticle","summary":"Publish an article","description":"Transitions an article to published status and sets publishedAt to current timestamp.","parameters":[{"name":"id","in":"path","required":true,"description":"Article ID to publish","schema":{"type":"string"}}],"responses":{"200":{"description":"Article published successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ContentItem"}}}}}},"404":{"description":"Article not found"}}}},"/api/search":{"get":{"operationId":"searchArticles","summary":"Hybrid search articles","description":"Performs blended full-text keyword and vector cosine similarity search across articles, returning relevance scores and context snippets.","parameters":[{"name":"query","in":"query","required":false,"description":"Keyword search term or natural language semantic query","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Filter search results to a specific category","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by content status","schema":{"type":"string","enum":["draft","in_review","published","archived"]}},{"name":"semantic","in":"query","required":false,"description":"When true, prioritizes vector semantic cosine similarity over keyword matching","schema":{"type":"boolean","default":false}},{"name":"limit","in":"query","required":false,"description":"Maximum results to return (default 20)","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Search results ranked by relevance","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"total":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"score":{"type":"number","description":"Relevance score between 0.0 and 1.0"},"snippet":{"type":"string","description":"Contextual highlight snippet"},"item":{"$ref":"#/components/schemas/ContentItem"}}}}}}}}}}}},"/api/stats":{"get":{"operationId":"getCmsStats","summary":"Get CMS statistics and distribution health","description":"Returns content metrics including article counts by status, categories, total readership views, and sync states for AI platforms.","responses":{"200":{"description":"System stats","content":{"application/json":{"schema":{"type":"object","properties":{"totalArticles":{"type":"integer"},"statusCounts":{"type":"object"},"categoryCounts":{"type":"object"},"totalViews":{"type":"integer"},"agentDistribution":{"type":"array"},"lastUpdated":{"type":"string"}}}}}}}}},"/api/discovery":{"get":{"operationId":"getAgentDiscovery","summary":"Agent Discovery metadata","description":"Provides machine-readable endpoint addresses for Model Context Protocol (MCP), ChatGPT Action schemas, and JSON feeds.","responses":{"200":{"description":"Discovery info","content":{"application/json":{"schema":{"type":"object","properties":{"cmsName":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"endpoints":{"type":"object"},"totalArticles":{"type":"integer"},"categories":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/content/{idOrSlug}/related":{"get":{"operationId":"getRelatedArticles","summary":"Get related articles for a given article ID or slug","description":"Returns the most closely related published articles based on shared tags, category, and vector similarity.","parameters":[{"name":"idOrSlug","in":"path","required":true,"description":"Article ID or URL slug (e.g. michigan-fashion-week-brings-it-to-new-york-fashion-week)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of related articles to return (default 4)","schema":{"type":"integer","default":4}}],"responses":{"200":{"description":"Related articles retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentItem"}},"total":{"type":"integer"}}}}}}}}},"/api/taxonomy":{"get":{"operationId":"getTaxonomy","summary":"Get live magazine categories, tags, and archival issues","description":"Returns all published categories, tags with counts, and archival edition names.","responses":{"200":{"description":"Taxonomy retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"totalPublishedArticles":{"type":"integer"},"categories":{"type":"array","items":{"type":"object"}},"tags":{"type":"array","items":{"type":"object"}},"issues":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/polls":{"get":{"operationId":"listPolls","summary":"List community polls and live vote percentages","description":"Returns interactive community polls from The Beautiful Machine Magazine with vote counts and percentages.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","closed"]}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Polls retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"integer"},"items":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/polls/{id}/vote":{"post":{"operationId":"votePoll","summary":"Cast a vote in an active community poll","description":"Records a community vote for the specified poll option and returns updated vote totals and percentages.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["optionId"],"properties":{"optionId":{"type":"string"},"voterHash":{"type":"string"}}}}}},"responses":{"200":{"description":"Vote recorded successfully"}}}},"/api/concierge/chat":{"post":{"operationId":"askStyleConcierge","summary":"Ask The Beautiful Machine AI Style & Culture Concierge","description":"Synthesizes an editorial response grounded in The Beautiful Machine Magazine articles along with matched articles and a contextual sponsor placement.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"User question about Detroit fashion, streetwear, techno, or relationships"}}}}}},"responses":{"200":{"description":"Concierge editorial response"}}}}},"components":{"schemas":{"ContentItem":{"type":"object","required":["id","slug","title","content","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"content":{"type":"string","description":"Full Markdown body"},"tags":{"type":"array","items":{"type":"string"}},"category":{"type":"string"},"author":{"type":"string"},"status":{"type":"string","enum":["draft","in_review","published","archived"]},"publishedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"metadata":{"type":"object"},"viewCount":{"type":"integer"}}},"CreateArticleInput":{"type":"object","required":["title","content"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","description":"Optional custom URL slug"},"summary":{"type":"string","maxLength":500},"content":{"type":"string","minLength":1,"description":"Markdown formatted article body"},"tags":{"type":"array","items":{"type":"string"},"default":[]},"category":{"type":"string","default":"General"},"author":{"type":"string","default":"Admin"},"status":{"type":"string","enum":["draft","in_review","published","archived"],"default":"draft"},"metadata":{"type":"object","default":{}}}},"UpdateArticleInput":{"type":"object","properties":{"title":{"type":"string"},"slug":{"type":"string"},"summary":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"category":{"type":"string"},"author":{"type":"string"},"status":{"type":"string","enum":["draft","in_review","published","archived"]},"metadata":{"type":"object"}}}}}}