Every API here is available over the APIs.io API and to AI agents over MCP.
{
"openapi": "3.0.3",
"info": {
"title": "GoldHold Memory API",
"version": "1.0.0",
"description": "GoldHold is a persistent semantic memory system for AI agents.\nCross-platform shared memory that persists across sessions, tools, and runtimes.\n\nUse this API to search memories before forming opinions, save new memories after\nsignificant decisions, send inter-agent messages, and read your inbox.\n\nPatent Pending -- All Auto Tunes LLC\n",
"contact": {
"email": "support@goldhold.ai"
},
"license": {
"name": "Proprietary"
}
},
"servers": [
{
"url": "https://checkout.goldhold.ai",
"description": "Production"
}
],
"tags": [
{
"name": "Memory",
"description": "Store, search, and manage agent memories"
},
{
"name": "Relay",
"description": "Inter-agent messaging and inbox"
}
],
"security": [
{
"BearerAuth": []
}
],
"paths": {
"/v1/memory/search": {
"post": {
"operationId": "memorySearch",
"summary": "Semantic search across agent memories",
"description": "Call this BEFORE forming opinions or answering questions about past context.\nSearches all namespaces semantically using natural language.\nAlways search GoldHold before assuming you know the answer.\n",
"tags": [
"Memory"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemorySearchRequest"
}
}
}
},
"responses": {
"200": {
"description": "Matching memories ranked by relevance",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MemorySearchResult"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/v1/memory/save": {
"post": {
"operationId": "memorySave",
"summary": "Save a new memory or decision receipt",
"description": "Call this AFTER completing significant actions, decisions, or learning something\nimportant. Persists information across sessions so future agent instances\ncan recall it. One receipt per run -- summarize the full run, not each step.\n",
"tags": [
"Memory"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemorySaveRequest"
}
}
}
},
"responses": {
"200": {
"description": "Memory saved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemorySaveResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/v1/memory/stats": {
"get": {
"operationId": "memoryStats",
"summary": "Memory index health and vector counts",
"description": "Call this to check memory system health, total vector count, and namespace\ndistribution. Use for diagnostics and health checks.\n",
"tags": [
"Memory"
],
"responses": {
"200": {
"description": "Stats and health status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemoryStatsResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/v1/memory/delete": {
"post": {
"operationId": "memoryDelete",
"summary": "Delete specific memories by ID or query",
"description": "Call this to remove memories that are outdated, incorrect, or explicitly\nforgotten by the user. Supply IDs for precise deletion or a query for\nsemantic matching.\n",
"tags": [
"Memory"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemoryDeleteRequest"
}
}
}
},
"responses": {
"200": {
"description": "Memories deleted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemoryDeleteResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/v1/send": {
"post": {
"operationId": "relaySend",
"summary": "Send a message to another agent or the owner",
"description": "Call this to send inter-agent messages, task hand-offs, or status updates\nto the owner via the GoldHold relay. Use to=\"owner\", to=\"guardian\", or\nto=\"all\" for broadcast.\n",
"tags": [
"Relay"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RelaySendRequest"
}
}
}
},
"responses": {
"200": {
"description": "Message sent",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RelaySendResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/v1/search": {
"post": {
"operationId": "relaySearch",
"summary": "Search relay messages and inbox history",
"description": "Call this to search past messages and relay communications semantically.\nUseful for finding prior task assignments, decisions communicated via relay,\nor messages from other agents.\n",
"tags": [
"Relay"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RelaySearchRequest"
}
}
}
},
"responses": {
"200": {
"description": "Matching relay messages",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RelayMessage"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/v1/inbox": {
"get": {
"operationId": "relayInbox",
"summary": "Retrieve pending inbox messages",
"description": "Call this to check for unread messages from other agents or the owner.\nReturns messages in order of receipt. Poll on session start or when\nexpecting a task assignment.\n",
"tags": [
"Relay"
],
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
},
"description": "Max messages to return"
},
{
"name": "unread_only",
"in": "query",
"schema": {
"type": "boolean",
"default": true
},
"description": "Return only unread messages"
}
],
"responses": {
"200": {
"description": "Inbox messages",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RelayMessage"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
}
},
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Pass your GoldHold API key as a Bearer token. Set as GOLDHOLD_API_KEY in your environment."
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid API key"
}
},
"schemas": {
"MemorySearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Natural language search query"
},
"namespaces": {
"type": "array",
"items": {
"type": "string"
},
"description": "Namespaces to search (omit to search all)"
},
"limit": {
"type": "integer",
"default": 10,
"description": "Max results to return"
},
"min_score": {
"type": "number",
"format": "float",
"description": "Minimum similarity score 0-1"
}
}
},
"MemorySearchResult": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"score": {
"type": "number",
"format": "float"
},
"text": {
"type": "string"
},
"metadata": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"type": {
"type": "string"
},
"namespace": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
}
}
}
}
},
"MemorySaveRequest": {
"type": "object",
"required": [
"text",
"type"
],
"properties": {
"text": {
"type": "string",
"description": "Memory content to store"
},
"type": {
"type": "string",
"enum": [
"receipt",
"note",
"core",
"directive"
],
"description": "Memory classification"
},
"namespace": {
"type": "string",
"description": "Target namespace (defaults to general)"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Additional structured metadata"
}
}
},
"MemorySaveResponse": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"namespace": {
"type": "string"
},
"stored_at": {
"type": "string",
"format": "date-time"
}
}
},
"MemoryStatsResponse": {
"type": "object",
"properties": {
"total_vectors": {
"type": "integer"
},
"namespaces": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"last_sync": {
"type": "string",
"format": "date-time"
},
"health": {
"type": "string",
"enum": [
"healthy",
"degraded"
]
}
}
},
"MemoryDeleteRequest": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Specific vector IDs to delete"
},
"query": {
"type": "string",
"description": "Semantic query to find and delete matching memories"
},
"namespace": {
"type": "string",
"description": "Limit deletion to this namespace"
}
}
},
"MemoryDeleteResponse": {
"type": "object",
"properties": {
"deleted_count": {
"type": "integer"
}
}
},
"RelaySendRequest": {
"type": "object",
"required": [
"to",
"body"
],
"properties": {
"to": {
"type": "string",
"description": "Recipient -- \"owner\", \"guardian\", agent name, or \"all\""
},
"subject": {
"type": "string",
"description": "Message subject line"
},
"body": {
"type": "string",
"description": "Message body"
},
"priority": {
"type": "string",
"enum": [
"low",
"normal",
"high"
],
"default": "normal"
}
}
},
"RelaySendResponse": {
"type": "object",
"properties": {
"message_id": {
"type": "string"
},
"sent_at": {
"type": "string",
"format": "date-time"
}
}
},
"RelaySearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Natural language search across relay messages"
},
"limit": {
"type": "integer",
"default": 10
}
}
},
"RelayMessage": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"subject": {
"type": "string"
},
"body": {
"type": "string"
},
"sent_at": {
"type": "string",
"format": "date-time"
},
"read": {
"type": "boolean"
}
}
}
}
}
}