{ "openapi": "3.1.0", "info": { "title": "StudioMeyer Memory REST API", "version": "3.45.0", "description": "Tenant Memory data API. This specification covers search, learning, decisions, entities, account information, export, backfill and public API discovery. Signup, import, billing, admin, license and OAuth flows and MCP JSON-RPC are not described here. Bearer keys provide the operations available to the account; separate read/write OAuth permissions are not implemented. Send JSON bodies of at most 1 MiB. Use the exact documented paths without appended query parameters." }, "servers": [ { "url": "https://memory.studiomeyer.io" } ], "externalDocs": { "description": "Public REST endpoint inventory", "url": "https://memory.studiomeyer.io/api" }, "x-api-version": "3.0.0", "x-coverage": { "complete": false, "excluded": [ "signup", "import", "billing", "admin", "licenses", "OAuth", "MCP JSON-RPC" ] }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "memory" ] } ], "paths": { "/api": { "get": { "operationId": "getMemoryApiInventory", "summary": "Read the public API inventory", "security": [], "responses": { "200": { "description": "REST endpoint inventory and product manifest.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "apiVersion": { "type": "string" }, "product": { "type": "object", "additionalProperties": true }, "auth": { "type": "string" }, "endpoints": { "type": "object", "additionalProperties": true } }, "required": [ "name", "version", "apiVersion", "product", "auth", "endpoints" ] } } } } } } }, "/api/search": { "post": { "operationId": "searchMemory", "summary": "Search the authenticated account memory", "description": "Free accounts use unified search without paid agentic search or reranking. Paid accounts use agentic search unless agentic is false. Exact tags match all requested tags on learning, decision and skill records. An empty or whitespace-only query is allowed only with tags. Tags must be non-blank and contain no NUL characters. Tagged requests require limit from 1 to 100 and rerankTopK from 3 to 20 when supplied. Search normally reinforces retrieved memories. readOnly=true or trackUsage=false suppresses these incidental writes only when tags are supplied; these options are not OAuth access permissions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchInput" } } } }, "responses": { "200": { "description": "Matching memories and optional retrieval metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Invalid input or secret detected in submitted content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account email is unverified or the tenant is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily API quota or stored-data limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/learn": { "post": { "operationId": "learnMemory", "summary": "Store a learning", "description": "Exact duplicates return NOOP. A duplicate correction may update an existing learning. New distinct content returns ADDED.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningInput" } } } }, "responses": { "200": { "description": "Duplicate or updated learning.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LearningNoop" }, { "$ref": "#/components/schemas/LearningUpdated" } ] } } } }, "201": { "description": "New learning stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningAdded" } } } }, "400": { "description": "Invalid input or secret detected in submitted content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account email is unverified or the tenant is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily API quota or stored-data limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/decide": { "post": { "operationId": "decideMemory", "summary": "Record a decision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionInput" } } } }, "responses": { "201": { "description": "Decision recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "id": { "type": "string" } }, "required": [ "success", "id" ] } } } }, "400": { "description": "Invalid input or secret detected in submitted content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account email is unverified or the tenant is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily API quota or stored-data limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/entity": { "post": { "operationId": "createMemoryEntity", "summary": "Create or reuse an entity and add observations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityInput" } } } }, "responses": { "201": { "description": "Entity and number of added observations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResponse" } } } }, "400": { "description": "Invalid input or secret detected in submitted content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account email is unverified or the tenant is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily API quota or stored-data limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/account": { "get": { "operationId": "getMemoryAccount", "summary": "Read account information and limits", "responses": { "200": { "description": "Authenticated account information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "Missing, invalid or expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account email is unverified or the tenant is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/export": { "get": { "operationId": "exportMemory", "summary": "Read a bounded Markdown memory snapshot", "description": "Returns a summary snapshot using a fixed internal limit of 100: up to 500 entities, 1,000 non-archived learnings, 300 recent decisions, 10 top skills and 10 recent sessions. Shows at most five current observations per entity and truncates observation text, learning text, decision text and session summaries. No pagination or client-configurable limit is supported. This response is not a complete or lossless data export.", "responses": { "200": { "description": "Bounded, summarized Markdown snapshot.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account email is unverified or the tenant is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/backfill": { "post": { "operationId": "backfillMemoryEmbeddings", "summary": "Backfill missing embeddings", "description": "No request body is required. Generates embeddings for stored learnings, decisions and observations.", "responses": { "200": { "description": "Numbers of processed records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "learnings": { "type": "integer" }, "decisions": { "type": "integer" }, "observations": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "success", "learnings", "decisions", "observations", "total" ] } } } }, "400": { "description": "Invalid input or secret detected in submitted content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired Bearer key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account email is unverified or the tenant is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily API quota or stored-data limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Tenant API key in the Authorization header." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.1 authorization code with PKCE (S256). The memory scope grants full account access; separate read/write permissions are not implemented.", "flows": { "authorizationCode": { "authorizationUrl": "https://memory.studiomeyer.io/authorize", "tokenUrl": "https://memory.studiomeyer.io/token", "scopes": { "memory": "Full access to the authenticated account memory operations." } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "code": { "type": "string" }, "plan": { "type": "string" }, "upgrade": { "type": "string" }, "observation": { "type": "string" } }, "required": [ "error" ] }, "SearchInput": { "type": "object", "properties": { "query": { "type": "string" }, "project": { "type": "string" }, "agentId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf16-code-units": 200, "description": "Non-blank exact tag, no NUL characters. Maximum 200 UTF-16 code units as enforced by the server; astral characters such as emoji count as two units. JSON Schema maxLength counts Unicode characters and cannot enforce this additional JavaScript length bound by itself.", "allOf": [ { "pattern": "\\S" }, { "pattern": "^[^\\u0000]*$" } ] }, "minItems": 1, "maxItems": 20 }, "limit": { "type": "integer" }, "types": { "type": "array", "items": { "type": "string", "enum": [ "decision", "learning", "session", "skill", "evolution", "entity" ] } }, "recencyWeight": { "type": "number" }, "memoryType": { "type": "string", "enum": [ "episodic", "semantic", "all" ] }, "agentic": { "type": "boolean" }, "rerank": { "type": "boolean" }, "rerankTopK": { "type": "integer" }, "asOf": { "type": "string", "format": "date-time" }, "dateRangeStart": { "type": "string", "description": "ISO date or date-time; used together with dateRangeEnd." }, "dateRangeEnd": { "type": "string", "description": "ISO date or date-time. Date-only values include the full UTC day." }, "expand": { "type": "boolean" }, "noiseFilter": { "type": "boolean" }, "includeArchived": { "type": "boolean" }, "includeEphemeral": { "type": "boolean" }, "readOnly": { "type": "boolean" }, "trackUsage": { "type": "boolean" } }, "required": [ "query" ], "allOf": [ { "if": { "required": [ "tags" ] }, "then": { "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "rerankTopK": { "type": "integer", "minimum": 3, "maximum": 20 } } }, "else": { "properties": { "query": { "type": "string", "pattern": "\\S" } } } } ] }, "SearchResponse": { "type": "object", "properties": { "success": { "const": true }, "count": { "type": "integer" }, "abstain": { "type": "boolean" }, "answerConfidence": { "type": "number" }, "abstainNote": { "type": "string" }, "rerankProvider": { "type": "string" }, "rerankMs": { "type": "number" }, "tagFilter": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "match": { "const": "all" }, "supportedTypes": { "type": "array", "items": { "type": "string", "enum": [ "learning", "decision", "skill" ] } } }, "required": [ "tags", "match", "supportedTypes" ] }, "queryExpansion": { "type": "object", "properties": { "subQueries": { "type": "array", "items": { "type": "string" } }, "isListQuery": { "type": "boolean" }, "isTemporalComputation": { "type": "boolean" }, "expandedKeywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "subQueries", "isListQuery", "isTemporalComputation", "expandedKeywords" ] }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } }, "required": [ "success", "count", "abstain", "results" ] }, "SearchResult": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "decision", "learning", "session", "skill", "evolution", "entity" ] }, "id": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "content": { "type": "string" }, "category": { "type": "string" }, "project": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "relevance": { "type": "number" }, "recency": { "type": "number" }, "rank": { "type": "number" }, "matchMethod": { "type": "string" }, "confidence": { "type": "number" }, "verified": { "type": "boolean" }, "rrfScore": { "type": "number" }, "importanceScore": { "type": "number" }, "lifecycleState": { "type": "string" }, "agentId": { "type": "string" }, "validFrom": { "type": "string", "format": "date-time" }, "validTo": { "type": [ "string", "null" ], "format": "date-time" }, "ingestedAt": { "type": "string", "format": "date-time" }, "superseded": { "type": "boolean" }, "memoryType": { "type": "string", "enum": [ "episodic", "semantic" ] }, "explanation": { "type": "object", "additionalProperties": true } }, "required": [ "type", "id", "date", "content", "relevance", "recency", "rank", "matchMethod" ] }, "LearningInput": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "pattern", "mistake", "insight", "research", "architecture", "infrastructure", "tool", "workflow", "performance", "security" ] }, "content": { "type": "string", "minLength": 1 }, "project": { "type": "string" }, "agentId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "number" }, "source": { "type": "string" }, "memoryType": { "type": "string", "enum": [ "episodic", "semantic" ] }, "date": { "type": "string", "description": "Optional event date for backfills. Invalid or future dates fall back to the current time." } }, "required": [ "category", "content" ] }, "LearningNoop": { "type": "object", "properties": { "success": { "const": true }, "action": { "const": "NOOP" }, "existingId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "success", "action", "existingId", "message" ] }, "LearningUpdated": { "type": "object", "properties": { "success": { "const": true }, "action": { "const": "UPDATED" }, "id": { "type": "string" } }, "required": [ "success", "action", "id" ] }, "LearningAdded": { "type": "object", "properties": { "success": { "const": true }, "action": { "const": "ADDED" }, "id": { "type": "string" }, "category": { "type": "string" }, "content": { "type": "string" }, "project": { "type": [ "string", "null" ] }, "memoryType": { "type": "string", "enum": [ "episodic", "semantic" ] }, "agentId": { "type": "string" }, "similarTo": { "type": "string" }, "similarity": { "type": "number" }, "similarNotice": { "type": "string" } }, "required": [ "success", "action", "id", "category", "content", "project", "memoryType" ] }, "DecisionInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "decision": { "type": "string", "minLength": 1 }, "reasoning": { "type": "string", "minLength": 1 }, "alternatives": { "type": "string" }, "project": { "type": "string" }, "agentId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "number" } }, "required": [ "title", "decision", "reasoning" ] }, "EntityInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "entityType": { "type": "string", "minLength": 1 }, "observations": { "type": "array", "items": { "type": "string" } }, "project": { "type": "string" }, "validFrom": { "type": "string", "format": "date-time" }, "fast": { "type": "boolean" }, "fastSkipEmbedding": { "type": "boolean" } }, "required": [ "name", "entityType" ] }, "EntityResponse": { "type": "object", "properties": { "success": { "const": true }, "id": { "type": "string" }, "name": { "type": "string" }, "entityType": { "type": "string" }, "created": { "type": "boolean" }, "observationsAdded": { "type": "integer" } }, "required": [ "success", "id", "name", "entityType", "created", "observationsAdded" ] }, "Account": { "type": "object", "properties": { "email": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "pro", "team" ] }, "paid": { "type": "boolean" }, "planSource": { "type": "string" }, "appsumoTier": { "type": "integer" }, "active": { "type": "boolean" }, "limits": { "type": "object", "properties": { "learnings": { "type": [ "integer", "string" ] }, "entities": { "type": [ "integer", "string" ] }, "observations": { "type": [ "integer", "string" ] }, "apiCallsPerDay": { "type": [ "integer", "string" ] }, "apiKeys": { "type": "integer" }, "agentScoping": { "type": "boolean" }, "reranking": { "type": "string" } }, "required": [ "learnings", "entities", "observations", "apiCallsPerDay", "apiKeys", "agentScoping", "reranking" ] } }, "required": [ "email", "plan", "paid", "planSource", "active", "limits" ] } } } }