{"openapi":"3.1.0","info":{"title":"SaSame Knowledge API","version":"0.5.0","description":"One full read model for human pages, search, LLM retrieval and MCP, plus CAS-versioned no-redeploy publishing, installation recipes and auditable promotion bundles."},"servers":[{"url":"https://srl-sasame.com"}],"components":{"securitySchemes":{"KnowledgePublisherBearer":{"type":"http","scheme":"bearer"},"KnowledgeAdminSession":{"type":"apiKey","in":"cookie","name":"sasame_knowledge_admin"}},"schemas":{"KnowledgeAction":{"type":"object","required":["id","label","href"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"href":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["primary","secondary","text"]},"audience":{"type":"array","items":{"type":"string","enum":["human","llm","agent","developer"]}},"copy_value":{"type":"string"}}},"KnowledgeInstallRecipe":{"type":"object","required":["id","platform","label","description"],"properties":{"id":{"type":"string"},"platform":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"endpoint":{"type":"string"},"command":{"type":"string"},"config":{"type":"string"},"action_url":{"type":"string"},"verification":{"type":"string"},"availability":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}}}},"KnowledgeDocument":{"type":"object","required":["id","slug","locale","title","kind","status","category","question","short_answer","description","tags","sections","examples","references","related_ids"],"properties":{"id":{"type":"string","pattern":"^doc:"},"slug":{"type":"string"},"locale":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived","deprecated","superseded","retired"]},"category":{"type":"string"},"question":{"type":"string"},"short_answer":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"sections":{"type":"array","items":{"type":"object","required":["heading","body"],"properties":{"heading":{"type":"string"},"body":{"type":"string"}}}},"examples":{"type":"array","items":{"type":"string"}},"references":{"type":"array","items":{"type":"object"}},"related_ids":{"type":"array","items":{"type":"string"}},"audiences":{"type":"array","items":{"type":"string","enum":["human","llm","agent","developer"]}},"aliases":{"type":"array","items":{"type":"string"}},"navigation":{"type":"object"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeAction"}},"install_recipes":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeInstallRecipe"}},"homepage":{"type":"object"},"redirects":{"type":"array","items":{"type":"object"}},"current_version":{"type":"integer","minimum":0}}},"PublishRequest":{"type":"object","required":["document","expected_version"],"properties":{"document":{"$ref":"#/components/schemas/KnowledgeDocument"},"expected_version":{"type":"integer","minimum":0},"source":{"type":"string","enum":["cms","ai","migration"]},"author_id":{"type":"string","pattern":"^author:"}}},"DraftRequest":{"type":"object","required":["document","expected_version"],"description":"Provider-neutral normalized draft. The server always forces document.status to draft and source to ai.","properties":{"document":{"$ref":"#/components/schemas/KnowledgeDocument"},"expected_version":{"type":"integer","minimum":0},"author_id":{"type":"string","pattern":"^author:"}}}}},"paths":{"/api/knowledge":{"get":{"summary":"List public summaries or retrieve one complete public knowledge document","parameters":[{"name":"slug","in":"query","schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","enum":["en"],"default":"en"}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Full record for slug requests; collection for list requests"},"404":{"description":"Document not found"}}}},"/api/search":{"get":{"summary":"Search complete public knowledge text, actions and installation recipes","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","enum":["en"],"default":"en"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Search results"}}}},"/api/mcp":{"post":{"summary":"Read-only MCP JSON-RPC endpoint exposing knowledge_search and full knowledge_get","responses":{"200":{"description":"MCP response"}}}},"/affiliate-market.json":{"get":{"summary":"Machine-readable success-only SaSame agent affiliate campaign","responses":{"200":{"description":"Affiliate campaign contract"}}}},"/api/affiliate/enroll":{"get":{"summary":"Describe the affiliate enrollment requirements","responses":{"200":{"description":"Enrollment requirements"}}},"post":{"summary":"Create a pending stateless affiliate enrollment identity and payout-wallet binding status","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_name","agent_contact","agent_home_url","payout_wallet_network","payout_wallet_address"],"properties":{"agent_name":{"type":"string"},"agent_contact":{"type":"string"},"agent_home_url":{"type":"string","format":"uri"},"payout_wallet_network":{"type":"string","enum":["base_usdc","evm"]},"payout_wallet_address":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"202":{"description":"Pending enrollment created"},"400":{"description":"Invalid enrollment"},"429":{"description":"Rate limited"}}}},"/factory-public.json":{"get":{"summary":"Machine-readable SaSame public entry and installation directory","responses":{"200":{"description":"Public Factory directory"}}}},"/.well-known/agent-card.json":{"get":{"summary":"Agent card derived from current Knowledge records","responses":{"200":{"description":"Agent card"}}}},"/llms-full.txt":{"get":{"summary":"Full Markdown projection of every public Knowledge record","responses":{"200":{"description":"Plain-text full export"}}}},"/api/admin/session":{"post":{"summary":"Exchange the scoped publisher token for a signed HttpOnly admin session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Session created"},"401":{"description":"Unauthorized"},"404":{"description":"Admin UI disabled"},"503":{"description":"Admin session not configured"}}},"delete":{"summary":"Clear the current admin session","responses":{"200":{"description":"Session cleared"}}}},"/api/admin/documents":{"get":{"summary":"List canonical runtime documents including drafts","security":[{"KnowledgePublisherBearer":[]},{"KnowledgeAdminSession":[]}],"parameters":[{"name":"locale","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Canonical documents"},"401":{"description":"Unauthorized"},"404":{"description":"Admin UI disabled"}}}},"/api/admin/draft":{"post":{"summary":"Store a provider-neutral AI draft; publication status is forced to draft","security":[{"KnowledgePublisherBearer":[]},{"KnowledgeAdminSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftRequest"}}}},"responses":{"201":{"description":"Draft stored with hashed receipt"},"400":{"description":"Invalid draft"},"401":{"description":"Unauthorized"},"409":{"description":"CAS version conflict"},"423":{"description":"Publisher busy"},"503":{"description":"Publishing disabled or not configured"}}}},"/api/admin/publish":{"post":{"summary":"Publish one reviewed CAS-versioned knowledge record without deploying site code","security":[{"KnowledgePublisherBearer":[]},{"KnowledgeAdminSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRequest"}}}},"responses":{"201":{"description":"Published with hashed receipt"},"400":{"description":"Invalid document or missing expected version"},"401":{"description":"Unauthorized"},"409":{"description":"CAS version conflict"},"423":{"description":"Another publisher holds the state lock"},"503":{"description":"Publishing disabled or not configured"}}}},"/api/admin/export":{"get":{"summary":"Export runtime-newer and runtime-only records as an auditable repository-promotion bundle","security":[{"KnowledgePublisherBearer":[]},{"KnowledgeAdminSession":[]}],"responses":{"200":{"description":"Promotion bundle"},"401":{"description":"Unauthorized"},"503":{"description":"Runtime state not configured"}}}}}}