{"openapi":"3.1.0","info":{"title":"FullStack AI Hub Knowledge Curator & Authoring (ChatGPT Action)","version":"1.3.0","description":"Authoring, editing, assessment generation, and integrity verification API for curriculum contributors and automated authoring agents."},"servers":[{"url":"https://fullstackaihub.com","description":"Apex Instant Gateway"},{"url":"https://mcp.fullstackaihub.com","description":"Dedicated Subdomain Gateway"}],"paths":{"/api/curator/validate":{"post":{"operationId":"validateContentIntegrity","summary":"Validate Curriculum Referential Integrity","description":"Run schema validation, acyclic DAG verification, and cross-reference checks.","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"strict":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Validation integrity report"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Forbidden — requires write:knowledge or admin:full"}}}},"/api/curator/concept":{"post":{"operationId":"curateConceptLesson","summary":"Curate Canonical Concept Lesson","description":"Create or update concept frontmatter and MDX lesson file under content/concepts/.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","title","summary","topicId"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"topicId":{"type":"string"},"depth":{"type":"string","enum":["mapped","researched","lesson","lab"]},"sourceIds":{"type":"array","items":{"type":"string"}},"outcomes":{"type":"array","items":{"type":"string"}},"lessonContent":{"type":"string"}}}}}},"responses":{"200":{"description":"Concept curation status"},"400":{"description":"Invalid input or topicId not found"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Forbidden — requires write:knowledge or admin:full"}}}},"/api/curator/relation":{"post":{"operationId":"proposeConceptRelation","summary":"Propose Knowledge Graph Edge","description":"Propose directed relationship between concepts and verify acyclic DAG integrity.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to","type","rationale"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"type":{"type":"string","enum":["prerequisite","enables","related","alternative","applied-in","evaluated-by","risk-mitigated-by"]},"rationale":{"type":"string"}}}}}},"responses":{"200":{"description":"Relation proposal status"},"400":{"description":"Invalid concept or cycle detected"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Forbidden — requires write:knowledge or admin:full"}}}},"/api/curator/assessment":{"post":{"operationId":"generateConceptAssessment","summary":"Generate Interactive Assessment","description":"Create YAML assessment pack with theory questions and decision scenario.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conceptId","theoryQuestions","decisionScenario"],"properties":{"conceptId":{"type":"string"},"theoryQuestions":{"type":"array","items":{"type":"object"}},"decisionScenario":{"type":"object"}}}}}},"responses":{"200":{"description":"Assessment generation status"},"400":{"description":"Invalid assessment schema"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Forbidden — requires write:knowledge or admin:full"}}}},"/api/curator/taxonomy":{"get":{"operationId":"getBlogTaxonomy","summary":"Get Blog Authoring Taxonomy & Available Covers","description":"Fetch valid territoryIds, sample conceptIds, sample sourceIds, built-in cover images, uploaded /images/blog/ assets, and supported blog post types before publishing.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Authoring taxonomy, covers, and valid IDs"},"401":{"description":"Missing or invalid Bearer API key"},"403":{"description":"Insufficient API key scopes (requires write:knowledge or admin:full)"}}}},"/api/curator/blog":{"get":{"operationId":"listCuratorBlogPosts","summary":"List Published Engineering Blog Posts","description":"List engineering blog posts, essays, guides, and briefings with filtering by type, tag, or search query.","security":[{"bearerAuth":[]}],"parameters":[{"name":"type","in":"query","required":false,"description":"Filter by publication type (all, essay, guide, brief, executive-briefing, case-study, paper-breakdown, system-breakdown)","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Filter by tag slug","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Case-insensitive keyword filter on title, summary, or tags","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max items to return (1-100, default 30)","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"List of matching blog posts with canonical URLs and metadata"},"401":{"description":"Missing or invalid Bearer API key"},"403":{"description":"Insufficient API key scopes"}}},"post":{"operationId":"publishBlogPost","summary":"Publish or Update an Engineering Blog Post","description":"Create or update an MDX engineering blog post, essay, guide, or briefing with SEO metadata, cover/inline images, Acorn MDX math sanitization, primary sources, and instant sitemap/RSS indexing.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","title","summary","body"],"properties":{"slug":{"type":"string","description":"Kebab-case URL slug"},"title":{"type":"string","description":"Article headline"},"summary":{"type":"string","description":"Concise card & feed summary"},"body":{"type":"string","description":"Full Markdown/MDX article body"},"type":{"type":"string","enum":["essay","guide","brief","executive-briefing"],"default":"essay"},"author":{"type":"string"},"authorRole":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"coverImage":{"type":"string","description":"Cover URL (/images/blog/... or /images/covers/...)"},"images":{"type":"array","items":{"type":"string"}},"seoTitle":{"type":"string"},"seoDescription":{"type":"string"},"featured":{"type":"boolean"},"keyTakeaways":{"type":"array","items":{"type":"string"}},"thesis":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}},"readingMinutes":{"type":"integer"},"publishedAt":{"type":"string"},"territoryIds":{"type":"array","items":{"type":"string"}},"conceptIds":{"type":"array","items":{"type":"string"}},"sourceIds":{"type":"array","items":{"type":"string"}},"newSources":{"type":"array","items":{"type":"object","required":["id","title","url","publisher"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"publisher":{"type":"string"},"publishedAt":{"type":"string"},"primary":{"type":"boolean"}}}}}}}}},"responses":{"200":{"description":"Blog post published with canonical URLs and sanitizer diagnostics"},"400":{"description":"Missing required fields or schema validation error"},"401":{"description":"Missing or invalid Bearer API key"},"403":{"description":"Insufficient API key scopes"}}}},"/api/curator/assets":{"post":{"operationId":"uploadBlogAsset","summary":"Upload Blog Image or SVG Diagram","description":"Upload an SVG diagram or base64-encoded image (PNG/JPEG/WebP/GIF) to /images/blog/<filename> and return the publicPath and Markdown embed snippet.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","content"],"properties":{"filename":{"type":"string","description":"Target filename (.svg, .png, .jpg, .jpeg, .webp, .gif)"},"content":{"type":"string","description":"UTF-8 SVG markup, raw base64, or data:image URI"},"encoding":{"type":"string","enum":["utf8","base64"]},"altText":{"type":"string"}}}}}},"responses":{"200":{"description":"Asset uploaded with publicPath, fullUrl, and markdownEmbed"},"400":{"description":"Invalid asset filename, extension, or disallowed SVG script"},"401":{"description":"Missing or invalid Bearer API key"},"403":{"description":"Insufficient API key scopes"}}}},"/api/curator/sources":{"post":{"operationId":"upsertEvidenceSource","summary":"Register or Update Primary Evidence Source","description":"Register or update a canonical evidence citation in sources.yaml before or alongside blog publishing.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","title","url","publisher"],"properties":{"id":{"type":"string","description":"Kebab-case source identifier"},"title":{"type":"string"},"url":{"type":"string"},"publisher":{"type":"string"},"publishedAt":{"type":"string"},"verifiedAt":{"type":"string"},"primary":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Source created or updated in sources.yaml"},"400":{"description":"Invalid source metadata or URL"},"401":{"description":"Missing or invalid Bearer API key"},"403":{"description":"Insufficient API key scopes"}}}},"/api/curator/health":{"get":{"operationId":"getCurriculumHealth","summary":"Inspect Curriculum Health & Metrics","description":"Inspect concept depth counts, domain distributions, evidence coverage, and assessment readiness.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Curriculum health status"},"401":{"description":"Missing or invalid Bearer token"},"403":{"description":"Forbidden — requires write:knowledge or admin:full"}}}},"/mcp":{"post":{"operationId":"callKnowledgeCuratorTool","summary":"Execute Authoring / Governance Tool","description":"Curate concepts, generate assessments, propose relations, validate schemas, or inspect audit logs.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":"integer","example":1},"method":{"type":"string","example":"tools/call"},"params":{"type":"object","properties":{"name":{"type":"string","enum":["fsai.curate_concept","fsai.generate_assessment","fsai.propose_concept_relation","fsai.validate_content","fsai.inspect_curriculum_health","fsai.get_audit_log","fsai.get_blog_taxonomy","fsai.list_blog_posts","fsai.upload_blog_asset","fsai.upsert_evidence_source","fsai.publish_blog_post"]},"arguments":{"type":"object"}},"required":["name","arguments"]}},"required":["jsonrpc","method","params"]}}}},"responses":{"200":{"description":"Tool execution result"},"403":{"description":"Forbidden — requires write:knowledge or admin:full"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"FSAI Live API Key with write:knowledge or admin:full scope"}}}}