{ "openapi": "3.1.0", "info": { "title": "Observance", "version": "1.0.0", "description": "Agent-native memory API. Provides structured memory storage, relational linking, namespace scoping, and machine-readable guidance (agent_contract) on every operational response." }, "servers": [ { "url": "/v1", "description": "Observance V1 API" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key obtained from POST /v1/keys/register" } }, "schemas": { "Memory": { "type": "object", "required": [ "id", "agentId", "namespace", "type", "cognitiveRole", "status", "source", "originType", "eventAt", "createdAt", "updatedAt", "lastAccessedAt", "relevanceScore", "importanceScore", "confidenceScore", "accessCount", "decayPolicy", "metadataJson" ], "properties": { "id": { "type": "string", "description": "mem_{ULID}" }, "agentId": { "type": "string", "description": "agt_{ULID}" }, "namespace": { "type": "string" }, "type": { "type": "string", "enum": [ "episodic", "semantic", "procedural" ] }, "cognitiveRole": { "type": "string", "enum": [ "observation", "reflection", "fact", "rule", "skill", "preference" ] }, "status": { "type": "string", "enum": [ "active", "archived", "deleted" ] }, "source": { "type": "string", "enum": [ "agent", "system", "user", "derived" ] }, "originType": { "type": "string", "enum": [ "direct", "summarized", "inferred", "imported" ] }, "contentText": { "type": [ "string", "null" ] }, "contentJson": { "type": [ "object", "null" ] }, "summary": { "type": [ "string", "null" ] }, "eventAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastAccessedAt": { "type": "string", "format": "date-time" }, "relevanceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "importanceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "accessCount": { "type": "integer", "minimum": 0 }, "decayPolicy": { "type": "string", "enum": [ "none", "linear", "exponential" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "embeddingId": { "type": [ "string", "null" ] }, "metadataJson": { "type": "object" } } }, "MemoryLink": { "type": "object", "required": [ "id", "fromMemoryId", "toMemoryId", "relationType", "status", "strengthScore", "confidenceScore", "createdAt", "createdBy", "metadataJson" ], "properties": { "id": { "type": "string", "description": "lnk_{ULID}" }, "fromMemoryId": { "type": "string" }, "toMemoryId": { "type": "string" }, "relationType": { "type": "string", "enum": [ "derived_from", "summarizes", "contradicts", "supports", "relates_to", "supersedes" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "strengthScore": { "type": "number", "minimum": 0, "maximum": 1 }, "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "enum": [ "agent", "system", "user" ] }, "metadataJson": { "type": "object" } } }, "Agent": { "type": "object", "required": [ "id", "name", "createdAt", "updatedAt", "lastActiveAt", "metadataJson" ], "properties": { "id": { "type": "string", "description": "agt_{ULID}" }, "name": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastActiveAt": { "type": "string", "format": "date-time" }, "metadataJson": { "type": "object" }, "memoryCount": { "type": "integer", "minimum": 0 } } }, "AgentContract": { "type": "object", "required": [ "version", "retryable", "next_actions" ], "properties": { "version": { "type": "string", "const": "1" }, "retryable": { "type": "boolean" }, "next_actions": { "type": "array", "items": { "type": "object", "required": [ "action", "available", "recommended" ], "properties": { "action": { "type": "string", "enum": [ "create_memory", "get_memory", "list_memories", "update_memory", "delete_memory", "archive_memory", "unarchive_memory", "create_link", "list_links", "delete_link", "find_related", "check_memory_status", "list_agents", "get_agent", "update_agent", "retry_after_wait", "authenticate", "fix_request" ] }, "available": { "type": "boolean" }, "recommended": { "type": "boolean" }, "description": { "type": "string" }, "method": { "type": "string" }, "endpoint": { "type": "string" }, "retry_after_seconds": { "type": "number" } } } }, "memory_type": { "type": "string", "enum": [ "episodic", "semantic", "procedural" ] }, "memory_status": { "type": "string", "enum": [ "active", "archived", "deleted" ] }, "namespace": { "type": "string" } } }, "Error": { "type": "object", "required": [ "error", "message", "request_id", "agent_contract" ], "properties": { "error": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key", "invalid_request", "memory_not_found", "agent_not_found", "link_not_found", "content_required", "immutable_field", "invalid_transition", "self_link", "cross_account_link", "idempotency_conflict", "idempotency_in_flight", "rate_limited", "server_error" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "agent_contract": { "$ref": "#/components/schemas/AgentContract" } } }, "PageInfo": { "type": "object", "required": [ "nextCursor", "hasMore" ], "properties": { "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } } } } }, "paths": { "/keys/register": { "post": { "summary": "Register a new API key and account", "operationId": "registerKey", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } } } } } }, "responses": { "201": { "description": "API key created" } } } }, "/skill": { "get": { "summary": "Get the skill manifest for agent onboarding", "operationId": "getSkill", "tags": [ "Discovery" ], "responses": { "200": { "description": "Skill manifest (structured JSON)" } } } }, "/memories/batch": { "post": { "summary": "Create multiple memories in a single request", "operationId": "batchCreateMemories", "tags": [ "Memories" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "memories" ], "properties": { "memories": { "type": "array", "maxItems": 50, "items": { "type": "object", "description": "Same shape as single create_memory input" } } } } } } }, "responses": { "201": { "description": "All memories created successfully" }, "207": { "description": "Partial success — some items created, some failed" }, "400": { "description": "Invalid envelope (not an array, empty, or >50 items)" }, "403": { "description": "Cannot create even one memory (quota or cap exhausted)" } } } }, "/memories": { "post": { "summary": "Create a memory", "operationId": "createMemory", "tags": [ "Memories" ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Memory created" } } }, "get": { "summary": "List memories", "operationId": "listMemories", "tags": [ "Memories" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "episodic", "semantic", "procedural" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "archived", "deleted" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "event_at", "relevance", "importance" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Memory list with pagination" } } } }, "/memories/{id}": { "get": { "summary": "Get a memory", "operationId": "getMemory", "tags": [ "Memories" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Memory" } } }, "patch": { "summary": "Update a memory", "operationId": "updateMemory", "tags": [ "Memories" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Updated memory" } } }, "delete": { "summary": "Soft-delete a memory", "operationId": "deleteMemory", "tags": [ "Memories" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Deleted memory" } } } }, "/memories/{id}/archive": { "post": { "summary": "Archive a memory", "operationId": "archiveMemory", "tags": [ "Memories" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Archived memory" } } } }, "/memories/{id}/unarchive": { "post": { "summary": "Unarchive a memory", "operationId": "unarchiveMemory", "tags": [ "Memories" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Unarchived memory" } } } }, "/memories/{memoryId}/links": { "post": { "summary": "Create a link", "operationId": "createLink", "tags": [ "Links" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Existing link returned" }, "201": { "description": "Link created" } } }, "get": { "summary": "List links for a memory", "operationId": "listLinks", "tags": [ "Links" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Link list" } } } }, "/memories/{memoryId}/related": { "get": { "summary": "Get related memories", "operationId": "getRelatedMemories", "tags": [ "Traversal" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Related memories with link metadata" } } } }, "/links/{linkId}": { "delete": { "summary": "Soft-delete a link", "operationId": "deleteLink", "tags": [ "Links" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Inactivated link" } } } }, "/agents": { "get": { "summary": "List agents", "operationId": "listAgents", "tags": [ "Agents" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agent list" } } } }, "/agents/{id}": { "get": { "summary": "Get an agent", "operationId": "getAgent", "tags": [ "Agents" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agent" } } }, "patch": { "summary": "Update an agent", "operationId": "updateAgent", "tags": [ "Agents" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Updated agent" } } } } } }