{"openapi":"3.1.0","info":{"title":"Cogni API","description":"A minimal FastAPI that directly passes user queries to OpenAI, augmented with Cogni memory.","version":"0.1.0"},"paths":{"/healthz":{"get":{"summary":"Health Check","description":"Health check endpoint that validates both API and database connectivity.\n\nTests:\n- Memory bank availability in app state\n- Database connectivity via direct connection test\n\nReturns detailed status for monitoring.","operationId":"health_check_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/refresh":{"post":{"summary":"Refresh Backend Data","description":"Refresh backend data by pulling latest changes from remote Dolt repository.\n\nThis endpoint triggers a Dolt pull operation to synchronize the backend\ndatabase with the latest changes from the remote repository.\n\nReturns:\n    JSON response with pull operation status and details","operationId":"refresh_backend_data_api_v1_refresh_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/chat":{"post":{"tags":["v1/Chat"],"summary":"Stream Chat","operationId":"stream_chat_api_v1_chat_post","parameters":[{"name":"authorization","in":"header","required":true,"schema":{"type":"string","title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteQueryRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/blocks":{"get":{"tags":["v1/Blocks"],"summary":"Get all memory blocks","description":"Retrieves memory blocks currently stored in the system. Can be filtered by block type.","operationId":"get_all_blocks_api_v1_blocks_get","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","title":"Type"}},{"name":"case_insensitive","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Case Insensitive"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MemoryBlock"},"title":"Response Get All Blocks Api V1 Blocks Get"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["v1/Blocks"],"summary":"Create a new memory block","description":"Adds a new memory block to the system using the core creation tool.","operationId":"create_block_api_v1_blocks_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMemoryBlockInput"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryBlock"}}}},"422":{"description":"Validation Error (invalid input data or metadata)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error (failed to save or fetch)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/blocks/{block_id}":{"get":{"tags":["v1/Blocks"],"summary":"Get a specific memory block by ID","description":"Retrieves a specific memory block by its unique identifier.","operationId":"get_block_api_v1_blocks__block_id__get","parameters":[{"name":"block_id","in":"path","required":true,"schema":{"type":"string","title":"Block Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryBlock"}}}},"404":{"description":"Memory block not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/schemas/{block_type}/{version}":{"get":{"tags":["v1/Schemas"],"summary":"Get JSON schema for a block type and version","description":"Returns the JSON schema for the given block type and version.\nIf version is 'latest', resolves to the latest version for the type.\nUses application/schema+json media type.","operationId":"get_schema_api_v1_schemas__block_type___version__get","parameters":[{"name":"block_type","in":"path","required":true,"schema":{"type":"string","title":"Block Type"}},{"name":"version","in":"path","required":true,"schema":{"type":"string","title":"Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/schemas/index.json":{"get":{"tags":["v1/Schemas"],"summary":"Get index of all available block schemas","description":"Returns a list of all available block schemas with their type, version, and URL.","operationId":"get_schema_index_api_v1_schemas_index_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/links":{"get":{"tags":["v1/Links"],"summary":"Get all links","description":"Retrieves all links in the system, with optional filtering by relation type.","operationId":"get_all_links_api_v1_links_get","parameters":[{"name":"relation","in":"query","required":false,"schema":{"anyOf":[{"enum":["related_to","mentions","child_of","parent_of","duplicate_of","part_of","contains","requires","provides","owned_by","owns","subtask_of","depends_on","blocks","is_blocked_by","belongs_to_epic","epic_contains","bug_affects","has_bug","derived_from","supersedes","references","source_of","cited_by"],"type":"string"},{"type":"null"}],"title":"Relation"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BlockLink"},"title":"Response Get All Links Api V1 Links Get"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["v1/Links"],"summary":"Create a new link between blocks","description":"Creates a directed link between two memory blocks with a specified relation type.","operationId":"create_link_api_v1_links_post","parameters":[{"name":"from_id","in":"query","required":true,"schema":{"type":"string","title":"From Id"}},{"name":"to_id","in":"query","required":true,"schema":{"type":"string","title":"To Id"}},{"name":"relation","in":"query","required":true,"schema":{"enum":["related_to","mentions","child_of","parent_of","duplicate_of","part_of","contains","requires","provides","owned_by","owns","subtask_of","depends_on","blocks","is_blocked_by","belongs_to_epic","epic_contains","bug_affects","has_bug","derived_from","supersedes","references","source_of","cited_by"],"type":"string","title":"Relation"}},{"name":"priority","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Priority"}},{"name":"created_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"title":"Link Metadata"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockLink"}}}},"400":{"description":"Bad Request - Invalid parameters or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Concurrency issue or link already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["v1/Links"],"summary":"Delete a link between blocks","description":"Removes a specific link between two memory blocks.","operationId":"delete_link_api_v1_links_delete","parameters":[{"name":"from_id","in":"query","required":true,"schema":{"type":"string","title":"From Id"}},{"name":"to_id","in":"query","required":true,"schema":{"type":"string","title":"To Id"}},{"name":"relation","in":"query","required":true,"schema":{"enum":["related_to","mentions","child_of","parent_of","duplicate_of","part_of","contains","requires","provides","owned_by","owns","subtask_of","depends_on","blocks","is_blocked_by","belongs_to_epic","epic_contains","bug_affects","has_bug","derived_from","supersedes","references","source_of","cited_by"],"type":"string","title":"Relation"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Link Api V1 Links Delete"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Link does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/links/from/{block_id}":{"get":{"tags":["v1/Links"],"summary":"Get links from a block","description":"Retrieves all links originating from a specific block, with optional filtering.","operationId":"get_links_from_api_v1_links_from__block_id__get","parameters":[{"name":"block_id","in":"path","required":true,"schema":{"type":"string","title":"Block Id"}},{"name":"relation","in":"query","required":false,"schema":{"anyOf":[{"enum":["related_to","mentions","child_of","parent_of","duplicate_of","part_of","contains","requires","provides","owned_by","owns","subtask_of","depends_on","blocks","is_blocked_by","belongs_to_epic","epic_contains","bug_affects","has_bug","derived_from","supersedes","references","source_of","cited_by"],"type":"string"},{"type":"null"}],"title":"Relation"}},{"name":"depth","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Depth"}},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BlockLink"},"title":"Response Get Links From Api V1 Links From  Block Id  Get"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/links/to/{block_id}":{"get":{"tags":["v1/Links"],"summary":"Get links to a block","description":"Retrieves all links pointing to a specific block, with optional filtering.","operationId":"get_links_to_api_v1_links_to__block_id__get","parameters":[{"name":"block_id","in":"path","required":true,"schema":{"type":"string","title":"Block Id"}},{"name":"relation","in":"query","required":false,"schema":{"anyOf":[{"enum":["related_to","mentions","child_of","parent_of","duplicate_of","part_of","contains","requires","provides","owned_by","owns","subtask_of","depends_on","blocks","is_blocked_by","belongs_to_epic","epic_contains","bug_affects","has_bug","derived_from","supersedes","references","source_of","cited_by"],"type":"string"},{"type":"null"}],"title":"Relation"}},{"name":"depth","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Depth"}},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BlockLink"},"title":"Response Get Links To Api V1 Links To  Block Id  Get"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/links/block/{block_id}":{"delete":{"tags":["v1/Links"],"summary":"Delete all links for a block","description":"Removes all links involving a specific block (as source or target).","operationId":"delete_links_for_block_api_v1_links_block__block_id__delete","parameters":[{"name":"block_id","in":"path","required":true,"schema":{"type":"string","title":"Block Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Links For Block Api V1 Links Block  Block Id  Delete"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BlockLink":{"properties":{"to_id":{"type":"string","title":"To Id","description":"ID of the target block in the link"},"from_id":{"type":"string","title":"From Id","description":"ID of the source block in the link"},"relation":{"type":"string","enum":["related_to","mentions","child_of","parent_of","duplicate_of","part_of","contains","requires","provides","owned_by","owns","subtask_of","depends_on","blocks","is_blocked_by","belongs_to_epic","epic_contains","bug_affects","has_bug","derived_from","supersedes","references","source_of","cited_by"],"title":"Relation","description":"The type of relationship between the blocks"},"priority":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Priority","description":"Priority of the link (higher numbers = higher priority)","default":0},"link_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Link Metadata","description":"Additional metadata about the link"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"ID of the agent/user who created the link"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the link was created"}},"type":"object","required":["to_id","from_id","relation"],"title":"BlockLink","description":"Defines a directed link between two MemoryBlocks."},"CompleteQueryRequest":{"properties":{"message":{"type":"string","title":"Message","description":"The message content to send to the AI","examples":["What is CogniDAO?"]},"model":{"type":"string","title":"Model","description":"The AI model to use for generation","default":"gpt-3.5-turbo"},"temperature":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Temperature","description":"Controls randomness in the response. Lower is more deterministic.","default":0.7},"system_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Message","description":"Instructions for the AI assistant's behavior","default":"You are a helpful AI assistant."},"message_history":{"anyOf":[{"items":{"$ref":"#/components/schemas/HistoryMessage"},"type":"array"},{"type":"null"}],"title":"Message History","description":"Optional list of previous messages in the conversation"}},"type":"object","required":["message"],"title":"CompleteQueryRequest","description":"Extended schema for a chat request with additional parameters.\nThis can be used for more advanced chat endpoints."},"ConfidenceScore":{"properties":{"human":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Human","description":"Optional human confidence score (0.0 to 1.0)"},"ai":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Ai","description":"Optional AI-generated confidence score (0.0 to 1.0)"}},"type":"object","title":"ConfidenceScore","description":"Represents confidence scores, potentially from human or AI sources."},"CreateMemoryBlockInput":{"properties":{"type":{"type":"string","title":"Type","description":"Type of memory block to create (must be registered in schema registry)"},"text":{"type":"string","title":"Text","description":"Primary content of the memory block"},"state":{"anyOf":[{"type":"string","enum":["draft","published","archived"]},{"type":"null"}],"title":"State","description":"Initial state of the block","default":"draft"},"visibility":{"anyOf":[{"type":"string","enum":["internal","public","restricted"]},{"type":"null"}],"title":"Visibility","description":"Visibility level of the block","default":"internal"},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Tags","description":"Optional tags for filtering and metadata"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Type-specific metadata for the block"},"source_file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File","description":"Optional source file or markdown name"},"confidence":{"anyOf":[{"$ref":"#/components/schemas/ConfidenceScore"},{"type":"null"}],"description":"Optional confidence scores for the block"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Optional identifier for creator (agent name or user ID)","default":"agent"}},"type":"object","required":["type","text"],"title":"CreateMemoryBlockInput","description":"Input model for creating a new memory block."},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"A human-readable error message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code","description":"An optional error code for programmatic handling"}},"type":"object","required":["detail"],"title":"ErrorResponse","description":"Schema for error responses."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HistoryMessage":{"properties":{"role":{"type":"string","enum":["user","assistant","system"],"title":"Role","description":"The role of the message sender."},"content":{"type":"string","title":"Content","description":"The content of the message."}},"type":"object","required":["role","content"],"title":"HistoryMessage","description":"Schema for a single message in the chat history."},"MemoryBlock":{"properties":{"id":{"type":"string","title":"Id","description":"Globally unique ID for this memory block"},"type":{"type":"string","enum":["knowledge","task","project","doc","interaction","log","epic","bug"],"title":"Type","description":"Block type used to determine structure and relationships"},"schema_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Schema Version","description":"Version of the schema this block adheres to (links to node_schemas table)"},"text":{"type":"string","title":"Text","description":"Primary content or description of the block"},"state":{"anyOf":[{"type":"string","enum":["draft","published","archived"]},{"type":"null"}],"title":"State","description":"Current state of the block"},"visibility":{"anyOf":[{"type":"string","enum":["internal","public","restricted"]},{"type":"null"}],"title":"Visibility","description":"Visibility level of the block"},"block_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Block Version","description":"Version number of this block"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"ID of the parent block in the hierarchy (foreign key to memory_blocks.id)"},"has_children":{"type":"boolean","title":"Has Children","description":"Whether this block has child blocks (denormalized for fast lookups)","default":false},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Tags","description":"Optional tags for filtering, theming, or metadata"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Custom metadata based on block type (reconstructed from block_properties)"},"source_file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File","description":"Optional source markdown or file name"},"source_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Uri","description":"Optional source link or Logseq block URI"},"confidence":{"anyOf":[{"$ref":"#/components/schemas/ConfidenceScore"},{"type":"null"}],"description":"Confidence scores for this memory block"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Optional identifier for creator (agent name or user ID)"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO timestamp of block creation"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"ISO timestamp of last update"},"embedding":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Embedding","description":"Optional vector embedding of the block's content"}},"type":"object","required":["type","text"],"title":"MemoryBlock","description":"The primary data structure for representing a unit of memory in the Cogni system experiment.\nAligns with the design specified in project-CogniMemorySystem-POC.json.\nIncludes schema versioning support (Task 2.0).\n\nNOTE: As of Property-Schema Split implementation, metadata is stored in the\nblock_properties table rather than as a JSON field on this model."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}