{ "openapi": "3.1.1", "info": { "title": "Alvia API", "description": "The Alvia API. Reference: https://alvia.ai/docs", "version": "v1" }, "servers": [ { "url": "https://api.alvia.ai" } ], "paths": { "/v1/memories": { "post": { "tags": ["Memories"], "description": "Stores one memory. With infer enabled the text is read as a passage and every durable fact in it becomes its own memory. Accepted asynchronously. The memory and each fact count against the account's monthly write allowance: a write is refused once the allowance is used up, and facts past it are discarded. A write is also refused, and facts that would form new memories are discarded, once the account holds its plan's limit of stored memories. A write resent while an identical one is still forming is accepted and counts against neither the write allowance nor the stored-memory limit. When identical writes are sent before the first is answered, one is stored and the others can be refused.", "operationId": "Memories_Create", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMemoryRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Payload Too Large", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "415": { "description": "Unsupported Media Type", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] }, "get": { "tags": ["Memories"], "operationId": "Memories_List", "parameters": [ { "name": "limit", "in": "query", "schema": { "maximum": 20, "minimum": 1, "pattern": "^-?(?:0|[1-9]\\d*)$", "type": ["integer", "string"], "format": "int32" } }, { "name": "starting_after", "in": "query", "schema": { "maxLength": 128, "minLength": 0, "type": "string" } }, { "name": "ending_before", "in": "query", "schema": { "maxLength": 128, "minLength": 0, "type": "string" } }, { "name": "organization_id", "in": "query", "schema": { "maxLength": 128, "minLength": 0, "type": "string" } }, { "name": "user_id", "in": "query", "schema": { "maxLength": 128, "minLength": 0, "type": "string" } }, { "name": "application_id", "in": "query", "schema": { "maxLength": 128, "minLength": 0, "type": "string" } }, { "name": "agent_id", "in": "query", "schema": { "maxLength": 128, "minLength": 0, "type": "string" } }, { "name": "team_id", "in": "query", "schema": { "maxLength": 128, "minLength": 0, "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponseOfMemoryResponse" } } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/v1/memories/import": { "post": { "tags": ["Memories"], "description": "Imports one conversation as an ordered list of chat turns and forms memories from it. Accepted asynchronously; the memories appear once formation completes. A conversation and the facts formed from it count against the account's monthly write allowance: an import is refused once the allowance is used up, and the part of a conversation past it, and the facts past it, are discarded. An import is also refused, and facts that would form new memories are discarded, once the account holds its plan's limit of stored memories. An import resent while every part of it is still forming is accepted and counts against neither the write allowance nor the stored-memory limit. When identical imports are sent before the first is answered, one is stored and the others can be refused.", "operationId": "Memories_Import", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportConversationRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Payload Too Large", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "415": { "description": "Unsupported Media Type", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/v1/memories/{memory_id}": { "get": { "tags": ["Memories"], "operationId": "Memories_GetById", "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P" } ], "responses": { "200": { "description": "OK", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryResponse" } } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] }, "delete": { "tags": ["Memories"], "description": "Forgets the memory. Its text, versions, relationships and feedback stay stored until the project is deleted.", "operationId": "Memories_Forget", "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P" } ], "responses": { "202": { "description": "Accepted", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/v1/memories/{memory_id}/inspect": { "get": { "tags": ["Memories"], "description": "Returns one active memory with its version history and its relationships to active memories. A forgotten or missing memory is 404. Each call counts the reads it costs against the account's monthly read allowance, a miss included, and is refused when fewer reads are left than it costs. The `Alvia-Usage` response header shows the reads the call used.", "operationId": "Memories_Inspect", "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P" } ], "responses": { "200": { "description": "OK", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryInspectResponse" } } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/v1/memories/search": { "post": { "tags": ["Memories"], "operationId": "Memories_Search", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMemoriesRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponseOfMemoryResponse" } } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Payload Too Large", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "415": { "description": "Unsupported Media Type", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/v1/memories/recall": { "post": { "tags": ["Memories"], "description": "Returns the single best memory for the query. A miss is 200 with status not_found, never 404. 404 means the selected project was not found. Each call counts the reads it costs against the account's monthly read allowance, a miss included, and is refused when fewer reads are left than it costs. The `Alvia-Usage` response header shows the reads the call used.", "operationId": "Memories_Recall", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMemoriesRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryResponse" } } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Payload Too Large", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "415": { "description": "Unsupported Media Type", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/v1/memories/context": { "post": { "tags": ["Memories"], "description": "Returns short context synthesized from the memory that best matches the query and the memories related to it. 404 when no context is available. Each call counts the reads it costs against the account's monthly read allowance, a miss included, and is refused when fewer reads are left than it costs. The `Alvia-Usage` response header shows the reads the call used.", "operationId": "Memories_Context", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMemoriesRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextResponse" } } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Payload Too Large", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "415": { "description": "Unsupported Media Type", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/v1/memories/{memory_id}/feedback": { "put": { "tags": ["Memories"], "operationId": "Memories_Feedback", "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mem_01K6Z1M4TB7D9E2F5G8H3J6K0P" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" } } }, "required": true }, "responses": { "204": { "description": "No Content", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } } }, "400": { "description": "Bad Request", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Payload Too Large", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "415": { "description": "Unsupported Media Type", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "Gateway Timeout", "headers": { "Server-Timing": { "$ref": "#/components/headers/Server-Timing" }, "Alvia-Usage": { "$ref": "#/components/headers/Alvia-Usage" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "schemas": { "CreateMemoryRequest": { "required": ["content"], "type": "object", "properties": { "content": { "maxLength": 32000, "minLength": 1, "type": "string" }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeRequest" } ] }, "infer": { "type": "boolean", "description": "Optional. Default true: the content is split into atomic memories. Set false to store the content as a single memory; its wording may still be normalized." }, "occurred_at": { "type": ["null", "string"], "description": "Optional ISO-8601 date-time when the content was stated or observed, if different from now. The memory keeps this time and its offset, and reads return it as occurred_at. A memory the content revises keeps its own time when that time is later. Must not be in the future, though a clock up to five minutes fast is accepted, and a date with no time may be today's date in any time zone. Omit to use the submission time. The offset sets the calendar day that relative phrases such as \"yesterday\" resolve on; send the local time with its offset when the content uses them. No offset means UTC. The stored text can follow a relative date with the dates it names on that day, as in \"yesterday (May 7, 2023)\" or \"last summer (June through August 2025)\". A memory of an event, plan, decision, task, issue, or measurement whose text names no date ends with the day it was stated, as in \"(stated May 8, 2023)\".", "format": "date-time" } }, "additionalProperties": false }, "ScopeRequest": { "type": "object", "properties": { "organization_id": { "maxLength": 128, "minLength": 0, "type": ["null", "string"] }, "user_id": { "maxLength": 128, "minLength": 0, "type": ["null", "string"] }, "application_id": { "maxLength": 128, "minLength": 0, "type": ["null", "string"] }, "agent_id": { "maxLength": 128, "minLength": 0, "type": ["null", "string"] }, "team_id": { "maxLength": 128, "minLength": 0, "type": ["null", "string"] } }, "additionalProperties": false }, "ProblemDetails": { "required": ["code"], "type": "object", "properties": { "type": { "type": ["null", "string"] }, "title": { "type": ["null", "string"] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": ["null", "integer", "string"], "format": "int32" }, "detail": { "type": ["null", "string"] }, "instance": { "type": ["null", "string"] }, "code": { "type": "string", "description": "A stable, machine-readable code for the error. The error reference lists every code." } } }, "ListResponseOfMemoryResponse": { "required": ["object", "data", "has_more", "url"], "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryResponse" } }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "additionalProperties": false }, "MemoryResponse": { "required": ["status"], "type": "object", "properties": { "status": { "$ref": "#/components/schemas/MemoryRecallStatus" }, "memory_id": { "type": ["null", "string"] }, "content": { "type": ["null", "string"] }, "category": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Category" } ] }, "is_favorited": { "type": ["null", "boolean"] }, "sentiment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Sentiment" } ] }, "occurred_at": { "type": ["null", "string"], "description": "When the memory's content was stated or observed, in the offset it was sent with: the occurred_at sent with the content, else the time it was submitted. A statement that revises the memory moves this to its own time, never back to an earlier one. A date the content itself names stays in the content.", "format": "date-time" }, "ranked_score": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": ["null", "number", "string"], "description": "Relevance of this memory to the query. Higher is better. Comparable between the items of one response, not between responses.", "format": "double" }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MemoryScope" } ] }, "entities": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EntitySalienceMap" } ] } }, "additionalProperties": false }, "MemoryRecallStatus": { "enum": ["active", "not_found"] }, "Category": { "enum": [ "identity", "preference", "goal", "commitment", "decision", "constraint", "relationship", "work", "knowledge", "skill", "resource", "event", "metric", "issue" ] }, "Sentiment": { "enum": ["neutral", "positive", "negative"] }, "MemoryScope": { "type": "object", "properties": { "organization_id": { "type": ["null", "string"] }, "user_id": { "type": ["null", "string"] }, "application_id": { "type": ["null", "string"] }, "agent_id": { "type": ["null", "string"] }, "team_id": { "type": ["null", "string"] } } }, "EntitySalienceMap": { "type": "object", "additionalProperties": { "type": "number" } }, "ImportConversationRequest": { "required": ["messages", "occurred_at"], "type": "object", "properties": { "messages": { "maxItems": 500, "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/ImportMessage" } }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeRequest" } ] }, "occurred_at": { "type": "string", "description": "Required ISO-8601 date-time of the conversation. Each memory formed from it keeps this time and its offset, and reads return it as occurred_at. A memory it revises keeps its own time when that time is later. Must not be in the future, though a clock up to five minutes fast is accepted, and a date with no time may be today's date in any time zone. The offset sets the calendar day that relative phrases such as \"yesterday\" resolve on; send the local time with its offset when the content uses them. No offset means UTC. The stored text can follow a relative date with the dates it names on that day, as in \"yesterday (May 7, 2023)\" or \"last summer (June through August 2025)\". A memory of an event, plan, decision, task, issue, or measurement whose text names no date ends with the day it was stated, as in \"(stated May 8, 2023)\".", "format": "date-time" } }, "additionalProperties": false }, "ImportMessage": { "required": ["role", "content"], "type": "object", "properties": { "role": { "$ref": "#/components/schemas/MessageRole" }, "content": { "maxLength": 16000, "minLength": 1, "type": "string" }, "speaker": { "maxLength": 128, "minLength": 1, "pattern": "^\\S[^\\p{Zl}\\p{Zp}\\p{Cc}]*$", "type": ["null", "string"] } }, "additionalProperties": false }, "MessageRole": { "enum": ["system", "developer", "user", "assistant", "tool"] }, "MemoryInspectResponse": { "required": [ "memory_id", "scope", "occurred_at", "is_favorited", "sentiment", "head_version", "versions", "relationships" ], "type": "object", "properties": { "memory_id": { "type": "string" }, "scope": { "$ref": "#/components/schemas/MemoryScope" }, "occurred_at": { "type": "string", "description": "When the memory's content was stated or observed, in the offset it was sent with: the occurred_at sent with the content, else the time it was submitted. A statement that revises the memory moves this to its own time, never back to an earlier one. A date the content itself names stays in the content.", "format": "date-time" }, "is_favorited": { "type": "boolean" }, "sentiment": { "$ref": "#/components/schemas/Sentiment" }, "head_version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": ["integer", "string"], "format": "int32" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryVersionView" }, "description": "The memory's newest versions, up to 100, newest first." }, "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRelationshipView" }, "description": "The memory's newest relationships to active memories, up to 20, newest first." } }, "additionalProperties": false }, "MemoryVersionView": { "required": [ "version", "content", "category", "entities", "occurred_at", "created_at", "outcome" ], "type": "object", "properties": { "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": ["integer", "string"], "format": "int32" }, "content": { "type": "string" }, "category": { "$ref": "#/components/schemas/Category" }, "entities": { "$ref": "#/components/schemas/EntitySalienceMap" }, "occurred_at": { "type": "string", "description": "The memory's occurred_at as of this version, in the offset it was sent with. A revision keeps the previous version's time when that time is later.", "format": "date-time" }, "created_at": { "type": "string", "description": "When this version was recorded.", "format": "date-time" }, "outcome": { "$ref": "#/components/schemas/ClassifyOutcome" }, "explanation": { "type": ["null", "string"] } }, "additionalProperties": false }, "ClassifyOutcome": { "enum": ["novel", "related", "duplicate", "supersession", "contradiction", "refinement"] }, "MemoryRelationshipView": { "required": ["target_id", "edge_type", "created_at"], "type": "object", "properties": { "target_id": { "type": "string" }, "edge_type": { "$ref": "#/components/schemas/EdgeRelationshipType" }, "created_at": { "type": "string", "description": "When this relationship was recorded.", "format": "date-time" } }, "additionalProperties": false }, "EdgeRelationshipType": { "enum": ["related", "contradiction"] }, "SearchMemoriesRequest": { "required": ["query"], "type": "object", "properties": { "query": { "maxLength": 1000, "minLength": 1, "type": "string" }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScopeRequest" } ] }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": ["null", "integer", "string"], "description": "Result count for search. Ignored by recall and context. Default 25, maximum 50; out-of-range values clamp.", "format": "int32" }, "occurred_after": { "type": ["null", "string"], "description": "Optional ISO-8601 lower bound: only memories whose occurred_at is at or after this instant. No offset means UTC.", "format": "date-time" }, "occurred_before": { "type": ["null", "string"], "description": "Optional ISO-8601 exclusive upper bound: only memories whose occurred_at is before this instant. No offset means UTC.", "format": "date-time" } }, "additionalProperties": false }, "ContextResponse": { "required": ["context"], "type": "object", "properties": { "context": { "type": "string" } }, "additionalProperties": false }, "FeedbackRequest": { "required": ["is_favorited", "sentiment"], "type": "object", "properties": { "is_favorited": { "type": "boolean" }, "sentiment": { "$ref": "#/components/schemas/Sentiment" } }, "additionalProperties": false } }, "headers": { "Server-Timing": { "description": "The time the API spent on the request, in milliseconds, as `app;dur=`: from when the API receives the request to when it starts the response. It includes the time to receive the request body, excludes sending the response, and is not a latency guarantee.", "schema": { "type": "string" } }, "Alvia-Usage": { "description": "The reads and writes this request used, as `reads=, writes=`. A completed read uses the reads its operation costs; a failed read uses none. Writes count the submissions accepted for storage: one per memory written, and one per part of an imported conversation. Facts drawn from the content later count in the usage report, not here. A refused or failed request reports what it used.", "schema": { "type": "string" } } }, "securitySchemes": { "ApiKey": { "type": "http", "description": "Alvia API key (sk-mem-…). Pass in the Authorization: Bearer sk-mem-… header.", "scheme": "bearer" } } }, "tags": [ { "name": "Memories" } ], "security": [ { "ApiKey": [] } ] }