{"info":{"version":"1.0.0","description":"API for submitting knowledge, searching the distilled knowledge base, and browsing the topic taxonomy. Designed for integration with ChatGPT Actions and other AI agents.","title":"Philosopher's Stone API","contact":{"name":"Philosopher's Stone"}},"components":{"schemas":{"DeveloperInfo":{"type":"object","properties":{"data":{"type":"object","properties":{"api_key":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"prefix":{"type":"string"},"inserted_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time","nullable":true},"rate_limit":{"type":"integer"},"requests_today":{"type":"integer"},"scopes":{"type":"array","items":{"type":"string"}}}},"user_uuid":{"type":"string","format":"uuid"}}}}},"KnowledgeChunk":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"category":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"topic":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}}},"content":{"type":"string"},"summary":{"type":"string"},"inserted_at":{"type":"string","format":"date-time"},"slug":{"type":"string"},"view_count":{"type":"integer"},"confidence":{"type":"number","format":"float"},"source_count":{"type":"integer"},"upvotes":{"type":"integer"}}},"SubmissionResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"message":{"type":"string"},"status":{"type":"string"}}}}},"TopicDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"chunks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"summary":{"type":"string"},"slug":{"type":"string"},"view_count":{"type":"integer"},"confidence":{"type":"number","format":"float"},"upvotes":{"type":"integer"}}}},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"slug":{"type":"string"}}}},"slug":{"type":"string"},"parent_id":{"type":"string","format":"uuid","nullable":true}}},"TopicTree":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"children":{"type":"array","items":{"$ref":"#/components/schemas/TopicTree"}},"slug":{"type":"string"}}}},"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http","description":"API key passed as Bearer token"}}},"paths":{"/developer/me":{"get":{"description":"Returns information about the authenticated API key and associated user.","tags":["Developer"],"summary":"Get current API key info","operationId":"getDeveloperInfo","responses":{"200":{"description":"API key information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperInfo"}}}},"401":{"description":"Invalid or missing API key"}},"security":[{"BearerAuth":[]}]}},"/knowledge":{"get":{"description":"Returns published knowledge chunks. Supports full-text search and pagination.","parameters":[{"in":"query","name":"q","description":"Search query","schema":{"type":"string"}},{"in":"query","name":"limit","description":"Number of results (default: 20, max: 100)","schema":{"default":20,"type":"integer"}},{"in":"query","name":"offset","description":"Pagination offset","schema":{"default":0,"type":"integer"}}],"tags":["Knowledge"],"summary":"List or search knowledge chunks","operationId":"listKnowledge","responses":{"200":{"description":"List of knowledge chunks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeChunk"}},"meta":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of matching chunks"}}}}}}}}}}},"/knowledge/concept/{concept}":{"get":{"description":"Returns all published chunks that mention a specific {{concept}} in their content. Concepts are inline knowledge graph nodes that connect chunks across topics.","parameters":[{"in":"path","name":"concept","description":"Concept name (e.g. 'serotonin', 'mitochondria', 'fiduciary duty')","required":true,"schema":{"type":"string"}}],"tags":["Knowledge"],"summary":"Find chunks by concept mention","operationId":"getKnowledgeByConcept","responses":{"200":{"description":"Chunks mentioning the concept","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeChunk"}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"concept":{"type":"string"}}}}}}}}}}},"/knowledge/{id}":{"get":{"description":"Returns a single knowledge chunk and increments its view count.","parameters":[{"in":"path","name":"id","description":"Knowledge chunk ID","required":true,"schema":{"type":"string","format":"uuid"}}],"tags":["Knowledge"],"summary":"Get a knowledge chunk by ID","operationId":"getKnowledge","responses":{"200":{"description":"Knowledge chunk details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KnowledgeChunk"}}}}}},"404":{"description":"Chunk not found"}}}},"/knowledge/{id}/graph":{"get":{"description":"Returns chunks connected to the given chunk through shared {{concept}} mentions, up to N hops. Hop 1 = chunks sharing any concept with the source. Hop 2 = chunks sharing concepts with hop-1 chunks. Useful for AI agents exploring related knowledge.","parameters":[{"in":"path","name":"id","description":"Source knowledge chunk ID","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"query","name":"hops","description":"Maximum traversal depth (default 2, max 4)","required":false,"schema":{"default":2,"maximum":4,"type":"integer"}}],"tags":["Knowledge"],"summary":"Traverse concept graph from a chunk","operationId":"getKnowledgeGraph","responses":{"200":{"description":"Connected chunks grouped by hop distance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"chunks":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeChunk"}},"hop":{"type":"integer"}}}}}}}}},"404":{"description":"Source chunk not found"}}}},"/submissions":{"post":{"description":"Submit new content to be processed and distilled into knowledge. Requires API key authentication.","tags":["Submissions"],"summary":"Submit content for processing","operationId":"createSubmission","responses":{"201":{"description":"Submission accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionResponse"}}}},"401":{"description":"Invalid or missing API key"},"409":{"description":"Duplicate submission"},"422":{"description":"Validation error"},"429":{"description":"Rate limit exceeded"}},"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"title":{"type":"string","description":"Optional title for the submission"},"metadata":{"type":"object","description":"Optional metadata key-value pairs"},"source":{"type":"string","description":"Optional source identifier"},"model":{"type":"string","description":"Optional model override for processing"},"topic":{"type":"string","description":"Optional topic slug to categorize the submission"},"content":{"type":"string","description":"The content to submit for processing"}}}}}}}},"/submit":{"get":{"description":"Submit content via a simple GET request. No authentication required, rate limited by IP address.","parameters":[{"in":"query","name":"content","description":"Content to submit","schema":{"type":"string"}},{"in":"query","name":"c","description":"Shorthand for content","schema":{"type":"string"}},{"in":"query","name":"title","description":"Optional title","schema":{"type":"string"}},{"in":"query","name":"t","description":"Shorthand for title","schema":{"type":"string"}},{"in":"query","name":"topic","description":"Optional topic slug","schema":{"type":"string"}},{"in":"query","name":"model","description":"Optional model override","schema":{"type":"string"}},{"in":"query","name":"source","description":"Optional source identifier","schema":{"type":"string"}}],"tags":["Submissions"],"summary":"Quick submit via GET request","operationId":"submitViaGet","responses":{"201":{"description":"Submission accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionResponse"}}}},"409":{"description":"Duplicate submission"},"422":{"description":"Validation error"},"429":{"description":"Rate limit exceeded"}}}},"/topics":{"get":{"description":"Returns the complete topic taxonomy as a nested tree structure.","tags":["Topics"],"summary":"Get full topic tree","operationId":"listTopics","responses":{"200":{"description":"Topic tree","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TopicTree"}}}}}}}}}},"/topics/{slug}":{"get":{"description":"Returns a topic with its children and associated knowledge chunks.","parameters":[{"in":"path","name":"slug","description":"Topic slug","required":true,"schema":{"type":"string"}}],"tags":["Topics"],"summary":"Get topic by slug","operationId":"getTopic","responses":{"200":{"description":"Topic details with children and chunks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TopicDetail"}}}}}},"404":{"description":"Topic not found"}}}}},"openapi":"3.0.3","servers":[{"description":"API v1","url":"https://philosophersstone.ee/api/v1"}]}