{ "openapi": "3.1.0", "info": { "title": "FastAPI", "version": "0.1.0" }, "paths": { "/sessions/start": { "post": { "summary": "Session Start", "operationId": "session_start_sessions_start_post", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/end": { "post": { "summary": "Session End", "operationId": "session_end_sessions_end_post", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionEndRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/sessions/summary": { "post": { "summary": "Session Summary", "operationId": "session_summary_sessions_summary_post", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSummaryRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/observations": { "post": { "summary": "Save Observation", "operationId": "save_observation_observations_post", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/observations/search": { "post": { "summary": "Search Observations", "operationId": "search_observations_observations_search_post", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ObservationCompact" }, "title": "Response Search Observations Observations Search Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/observations/{observation_id}": { "get": { "summary": "Get Observation", "operationId": "get_observation_observations__observation_id__get", "parameters": [ { "name": "observation_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Observation Id" } }, { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "x-user-id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "title": "X-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObservationPublic" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/observations/{observation_id}/timeline": { "get": { "summary": "Get Timeline", "operationId": "get_timeline_observations__observation_id__timeline_get", "parameters": [ { "name": "observation_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Observation Id" } }, { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "x-user-id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "title": "X-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ObservationPublic" }, "title": "Response Get Timeline Observations Observation Id Timeline Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/stats": { "get": { "summary": "Get Stats", "operationId": "get_stats_stats_get", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } }, { "name": "x-user-id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "title": "X-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "integer" }, "title": "Response Get Stats Stats Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ObservationCompact": { "properties": { "id": { "type": "integer", "title": "Id" }, "type": { "type": "string", "minLength": 1, "title": "Type" }, "title": { "type": "string", "minLength": 1, "title": "Title" }, "topic_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic Key" }, "score": { "type": "number", "title": "Score" }, "snippet": { "type": "string", "minLength": 1, "title": "Snippet" }, "updated_at": { "type": "string", "title": "Updated At" } }, "additionalProperties": false, "type": "object", "required": [ "id", "type", "title", "score", "snippet", "updated_at" ], "title": "ObservationCompact", "description": "Read-only compact view of a persisted Observation for API responses.\n\nWARNING: `score` is NOT comparable across search vs memory-context results (Braess #5)." }, "ObservationPublic": { "properties": { "id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Id" }, "session_id": { "type": "string", "minLength": 1, "title": "Session Id" }, "user_id": { "type": "string", "minLength": 1, "title": "User Id" }, "type": { "type": "string", "minLength": 1, "title": "Type" }, "title": { "type": "string", "minLength": 1, "title": "Title" }, "content": { "type": "string", "minLength": 1, "title": "Content" }, "topic_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic Key" }, "revision_count": { "type": "integer", "minimum": 1.0, "title": "Revision Count", "default": 1 }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "additionalProperties": false, "type": "object", "required": [ "session_id", "user_id", "type", "title", "content", "created_at", "updated_at" ], "title": "ObservationPublic", "description": "Public-facing Observation for API responses.\n\nExcludes ``normalized_hash`` from both the serialized body AND the OpenAPI\nschema (Braess #6: single source of truth for wire format).\nRound-2 Fix #3: use as response_model in HTTP endpoints instead of Observation." }, "SaveRequest": { "properties": { "user_id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "User Id" }, "content": { "type": "string", "maxLength": 50000, "minLength": 1, "title": "Content" }, "type": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Type" }, "title": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Title" }, "topic_key": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Topic Key" } }, "additionalProperties": false, "type": "object", "required": [ "user_id", "content", "type", "title" ], "title": "SaveRequest", "description": "Request body for POST /save." }, "SaveResult": { "properties": { "id": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Id" }, "outcome": { "type": "string", "enum": [ "created", "updated", "deduped" ], "title": "Outcome" }, "session_id": { "type": "string", "minLength": 1, "title": "Session Id" }, "topic_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic Key" } }, "additionalProperties": false, "type": "object", "required": [ "id", "outcome", "session_id" ], "title": "SaveResult", "description": "Frozen response for mem_save / mem_session_summary.\n\nWire-stable (Braess #6) \u2014 serialized verbatim by HTTP (#10) and MCP (#11).\n`outcome` mirrors UpsertOutcome StrEnum values verbatim." }, "SearchRequest": { "properties": { "user_id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "User Id" }, "query": { "type": "string", "maxLength": 1000, "minLength": 1, "title": "Query" }, "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "default": 10 }, "types": { "anyOf": [ { "items": { "type": "string", "maxLength": 100, "minLength": 1 }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Types" }, "types_exclude": { "anyOf": [ { "items": { "type": "string", "maxLength": 100, "minLength": 1 }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Types Exclude" } }, "additionalProperties": false, "type": "object", "required": [ "user_id", "query" ], "title": "SearchRequest", "description": "Request body for POST /search." }, "Session": { "properties": { "id": { "type": "string", "minLength": 1, "title": "Id" }, "user_id": { "type": "string", "minLength": 1, "title": "User Id" }, "started_at": { "type": "string", "title": "Started At" }, "ended_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ended At" }, "last_activity_at": { "type": "string", "title": "Last Activity At" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "status": { "type": "string", "enum": [ "active", "completed" ], "title": "Status", "default": "active" }, "is_auto_generated": { "type": "boolean", "title": "Is Auto Generated", "description": "True when summary was auto-generated by session auto-close (Braess #2).", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "user_id" ], "title": "Session", "description": "Session lifecycle record. Mutable \u2014 session-lifecycle updates in place." }, "SessionEndRequest": { "properties": { "user_id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "User Id" }, "summary": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Summary" } }, "additionalProperties": false, "type": "object", "required": [ "user_id", "summary" ], "title": "SessionEndRequest", "description": "Request body for POST /session/end." }, "SessionStartRequest": { "properties": { "user_id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "User Id" } }, "additionalProperties": false, "type": "object", "required": [ "user_id" ], "title": "SessionStartRequest", "description": "Request body for POST /session/start." }, "SessionStartResponse": { "properties": { "session_id": { "type": "string", "minLength": 1, "title": "Session Id" }, "is_new": { "type": "boolean", "title": "Is New" }, "sessions_context": { "items": { "$ref": "#/components/schemas/SessionSummaryCompact" }, "type": "array", "title": "Sessions Context" }, "memories": { "items": { "$ref": "#/components/schemas/ObservationCompact" }, "type": "array", "title": "Memories" } }, "additionalProperties": false, "type": "object", "required": [ "session_id", "is_new" ], "title": "SessionStartResponse", "description": "Response payload for mem_session_start." }, "SessionSummaryCompact": { "properties": { "session_id": { "type": "string", "minLength": 1, "title": "Session Id" }, "date": { "type": "string", "title": "Date" }, "summary": { "type": "string", "minLength": 1, "title": "Summary" }, "is_auto_generated": { "type": "boolean", "title": "Is Auto Generated" } }, "additionalProperties": false, "type": "object", "required": [ "session_id", "date", "summary", "is_auto_generated" ], "title": "SessionSummaryCompact", "description": "Compact session summary for context responses.\n\n`is_auto_generated` has no default \u2014 callers must explicitly decide (Braess #2)." }, "SessionSummaryRequest": { "properties": { "user_id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "User Id" }, "summary": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Summary" } }, "additionalProperties": false, "type": "object", "required": [ "user_id", "summary" ], "title": "SessionSummaryRequest", "description": "Request body for POST /session/summary." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } }