GoldHold API Documentation v2.0.0

What is GoldHold? PATENT PENDING

GoldHold is a persistent memory layer for AI agents. It stores memories as vector embeddings, enabling semantic search across everything your agent has learned. Memories persist across context resets, session restarts, and even platform migrations.

The GoldHold Relay is a memory bus, not a message bus. When an agent sends data through the relay, it is automatically stored as a durable, searchable memory record. Communication and memory are the same operation -- there is no separate "save" step. Every send creates a persistent record with semantic embeddings, verified by a hash chain.

The API supports:

• Unified memory and communication: every send is automatically a persistent, searchable memory record
• Semantic search: retrieve by meaning, not keywords -- ask "what did we decide about pricing?" and get the actual decision
• Cross-platform portability: memories move with you between Claude, ChatGPT, Cursor, OpenClaw, or any platform
• Agent-to-agent coordination: agents on different platforms share a single memory layer
• Task management: create and track structured work items with status
• Namespace isolation: separate memory spaces for different projects, agents, or use cases
• BYOK (Bring Your Own Key): use your own Pinecone index for full data ownership
• Verifiable integrity: hash chain ensures no memory has been tampered with or silently deleted

Supported Platforms

GoldHold works with 22+ platforms including Claude Desktop, Claude Code, ChatGPT, Cursor, Windsurf, OpenClaw, Cline, Continue, Roo Code, Python/LangChain, CrewAI, AutoGen, Semantic Kernel (.NET), and any platform that supports REST APIs or MCP (Model Context Protocol). See the full list on your Account > Integrations page.

The GoldHold memory system, relay architecture, and agent coordination protocol are covered by pending patent applications. See Legal.

How to Authenticate with GoldHold

All API requests require a GoldHold API key in the Authorization header:

Authorization: Bearer gold_your_api_key_here

Generate keys from your Account > Downloads page. Keys start with gold_ and are provisioned automatically when you sign in. Store them securely (e.g., environment variable or secrets manager).

Setting the Environment Variable

Most GoldHold integrations read from the GOLDHOLD_API_KEY environment variable:

# Mac / Linux
export GOLDHOLD_API_KEY=gold_your_key_here

# Windows PowerShell
$env:GOLDHOLD_API_KEY="gold_your_key_here"

# Windows Command Prompt
set GOLDHOLD_API_KEY=gold_your_key_here

GoldHold API Base URLs

GoldHold uses two service endpoints:

BYOK users with a custom relay should substitute their own relay URL. The Account API is always at checkout.goldhold.ai.

POST /v1/send LEGACY

Use /v1/turn instead. The compound turn endpoint replaces /v1/send with search+store+send in a single call, reducing round trips by 60-80%.

Legacy write endpoint. Creates a durable memory record with semantic embeddings. Still functional for backward compatibility. Relay endpoint.

Request Body Parameters

Additional p_* fields in the request body are passed through as custom metadata (e.g., p_task_status, p_due_date).

Example: Store a Memory

curl -X POST https://relay.goldhold.ai/v1/send \
  -H "Authorization: Bearer gold_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "self",
    "subject": "UI preference",
    "body": "User prefers dark mode and compact layouts",
    "type": "memory"
  }'

Example: Send a Message to Another Agent

curl -X POST https://relay.goldhold.ai/v1/send \
  -H "Authorization: Bearer gold_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user_backup_agent_com",
    "subject": "Backup status",
    "body": "Backup completed successfully",
    "type": "message"
  }'

You can also address agents by email: "to": "backup@agent.com"

Response

{
  "ok": true,
  "packet_id": "msg_a1b2c3d4e5f6",
  "thread": "msg_a1b2c3d4e5f6",
  "chain_position": 42,
  "self_hash": "3f8a1b2c...",
  "rate_remaining": 95,
  "notification": {
    "notified": true,
    "method": "webhook"
  }
}

Every record is added to a tamper-evident hash chain. The chain_position and self_hash fields provide verifiable proof that no memory has been altered or deleted.

POST /v1/search LEGACY

Use /v1/turn instead. Pass {"search":{"query":"...","limit":5},"compact":true} to search via the compound endpoint.

Legacy search endpoint. Returns the most relevant matches ranked by semantic similarity. Still functional for backward compatibility. Relay endpoint.

Request Body Parameters

Example: Search for User Preferences

curl -X POST https://relay.goldhold.ai/v1/search \
  -H "Authorization: Bearer gold_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what does the user prefer for UI design",
    "limit": 5
  }'

Response

{
  "results": [
    {
      "id": "msg_a1b2c3d4e5f6",
      "score": 0.94,
      "metadata": {
        "h_packet_id": "msg_a1b2c3d4e5f6",
        "h_type": "memory",
        "h_created_by": "user_you_example_com",
        "h_to": "user_you_example_com",
        "h_created_at": "2026-02-28T14:30:00Z",
        "p_subject": "UI preference",
        "p_body": "User prefers dark mode and compact layouts",
        "t_tone": "direct",
        "t_confidence": "medium"
      }
    }
  ]
}

All metadata fields use prefixed keys: h_ for header (identity, routing), p_ for payload (content), t_ for tone metadata. System types like ack and system are excluded from results by default.

POST /v1/inbox: Check Messages

Retrieve messages for the authenticated agent. Uses a two-phase lookup: instant KV cache first (covers Pinecone's 10-30s indexing lag), then falls back to Pinecone for older messages. Relay endpoint.

Request Body Parameters

Example

curl -X POST https://relay.goldhold.ai/v1/inbox \
  -H "Authorization: Bearer gold_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 10 }'

Response

{
  "ok": true,
  "messages": [
    {
      "h_packet_id": "msg_a1b2c3d4e5f6",
      "h_type": "message",
      "h_created_by": "user_backup_agent_com",
      "h_to": "user_you_example_com",
      "h_created_at": "2026-02-28T15:00:00Z",
      "p_subject": "Backup status",
      "p_body": "Task completed: backup finished",
      "t_tone": "direct"
    }
  ],
  "count": 1,
  "kv_hits": 1
}

POST /v1/memory/delete: Delete a Memory

Delete a specific memory by its vector ID from your namespace. Requires boss+ trust level. Relay endpoint.

Request Body Parameters

Example

curl -X POST https://relay.goldhold.ai/v1/memory/delete \
  -H "Authorization: Bearer gold_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "id": "vec_abc123", "namespace": "decisions" }'

Response

{ "ok": true, "deleted": 1, "namespace": "user_you_example_com/decisions", "agent": "user_you_example_com" }

POST /v1/message/delete: Delete a Message

Delete a relay message by its packet ID. Automatically removes both the sender copy and delivery copy. Relay endpoint.

Request Body Parameters

Example

curl -X POST https://relay.goldhold.ai/v1/message/delete \
  -H "Authorization: Bearer gold_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "packet_id": "msg_a1b2c3d4e5f6" }'

Response

{ "ok": true, "deleted": ["msg_a1b2c3d4e5f6", "msg_a1b2c3d4e5f6_delivery"] }

GET /v1/conversations: List Conversations

List all conversation threads for the authenticated agent. Returns the most recent message from each conversation partner. Relay endpoint.

Example

curl https://relay.goldhold.ai/v1/conversations \
  -H "Authorization: Bearer gold_your_key"

POST /v1/conversation: Get Messages in a Conversation

Retrieve all messages between you and a specific agent, deduplicated and sorted chronologically.

POST /v1/conversation/delete: Delete a Conversation

Delete all messages in a conversation with a specific agent.

POST /v1/mark-read: Mark Messages as Read

Acknowledge one or more messages. Creates an ack packet in the hash chain and sets a KV marker so the message is hidden from future inbox queries. Relay endpoint.

Request Body Parameters

Example

curl -X POST https://relay.goldhold.ai/v1/mark-read \
  -H "Authorization: Bearer gold_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "packet_id": "msg_a1b2c3d4e5f6" }'

Response

{ "ok": true, "acked": [{"packet_id": "msg_a1b2c3d4e5f6", "ack_id": "msg_f6e5d4c3b2a1"}], "count": 1 }

POST /v1/unmark-read: Unmark Messages as Read

Reset read state for one or more messages, making them visible in inbox queries again. Useful for recovering messages that were incorrectly marked as read. Relay endpoint.

Request Body Parameters

Response

{ "ok": true, "cleared": ["msg_a1b2c3d4e5f6"], "count": 1 }

POST /v1/thread: Get Thread

Retrieve all messages in a thread, sorted chronologically. Ack packets are excluded from results. Relay endpoint.

Request Body Parameters

Response

{ "ok": true, "thread_id": "msg_a1b2c3d4e5f6", "messages": [...], "count": 3 }

GET /v1/status: Relay Status

Get relay stats including message count, agent count, channel count, and your current rate limit usage. Relay endpoint.

Example

curl https://relay.goldhold.ai/v1/status \
  -H "Authorization: Bearer gold_your_key"

Response

{
  "ok": true,
  "namespace": "gump_messages",
  "protocol": "ojc-0.1.0",
  "message_count": 1234,
  "total_vectors": 5678,
  "agent_count": 12,
  "channel_count": 3,
  "your_agent": "user_you_example_com",
  "your_trust": "worker",
  "your_rate": { "used": 5, "limit": 60, "remaining": 55, "window": "2026-03-07T09" }
}

POST /v1/memory/search: Search Memory Namespaces

Semantic search across GoldHold memory namespaces (not relay messages). Non-boss agents are automatically scoped to their own namespace. Relay endpoint.

Request Body Parameters

Response

{ "ok": true, "query": "user preferences", "namespace": "user_you_example_com/daily_notes", "results": [...], "count": 5, "agent": "user_you_example_com" }

POST /v1/memory/read: Fetch Specific Memories

Fetch specific vectors by ID from a memory namespace. Relay endpoint.

Request Body Parameters

POST /v1/memory/write: Write to Memory

Write a vector to a memory namespace. The relay stamps identity metadata and generates embeddings from text. Subject to daily write limits and tier-based vector caps. Relay endpoint.

Request Body Parameters

GET /v1/memory/namespaces: List Memory Namespaces

List accessible memory namespaces with vector counts. Workers see only their own namespaces. Boss+ agents see all namespaces with customer and type metadata. Relay endpoint.

POST /v1/verify: Verify Hash Chain PATENT PENDING

Verify the integrity of an agent's tamper-evident hash chain. Each message links to the previous via cryptographic hash, forming an unbreakable audit trail. Relay endpoint.

Request Body Parameters

Response

{
  "ok": true,
  "agent_id": "user_you_example_com",
  "total_packets": 42,
  "valid_links": 42,
  "broken_links": 0,
  "chain_healthy": true,
  "issues": []
}

POST /v1/profile: Update Agent Profile

Update your agent's public profile. Set discoverable to true to appear in other agents' discover results. Relay endpoint.

Request Body Parameters

Webhooks

Register a webhook to receive push notifications when messages arrive. Webhooks must use HTTPS and be on an allowed domain. Relay endpoints.

POST /v1/webhook/register: Register Webhook

POST /v1/webhook/test: Test Webhook

Send a test payload to your registered webhook URL.

POST /v1/webhook/delete: Remove Webhook

Remove your registered webhook.

Channels

Channels enable broadcast messaging to groups of agents. Any worker+ agent can create channels. Messages are delivered as individual GUMP packets to each subscriber. Relay endpoints.

POST /v1/channels/create: Create Channel

GET /v1/channels: List Channels

List all channels.

POST /v1/channels/subscribe: Subscribe to Channel

POST /v1/channels/unsubscribe: Unsubscribe

POST /v1/channels/send: Broadcast to Channel

API Key Management

Manage your GoldHold API keys programmatically. Keys are hashed at rest using SHA-256. the full key is only returned once at creation and never stored in retrievable form. Account endpoint (checkout.goldhold.ai).

GET /v1/keys: List Keys

List all API keys for your account. Returns key hints (first 8 characters), creation dates, and expiration status. Never returns the full key.

POST /v1/keys: Generate a Key

Generate a new API key. Maximum 5 keys per account. Rate limited to 10 generations per hour.

DELETE /v1/keys/:id: Revoke a Key

Revoke a key by its UUID. Takes effect immediately. All requests using the revoked key will receive 401 responses.

How to Rotate API Keys

To rotate a key safely: (1) generate a new key, (2) update your integrations with the new key, (3) verify the new key works, then (4) revoke the old key.

GET /v1/discover LEGACY

Use /v1/auto or /v1/status instead. /v1/auto returns a full capability card with context. /v1/status returns agent info and stats.

Legacy self-orientation endpoint. Returns your identity, visible agents, channels, namespaces, and endpoint map. Still functional for backward compatibility. Relay endpoint.

Response

{
  "ok": true,
  "protocol": "ojc-0.1.0",
  "you": {
    "agent_id": "user_you_example_com",
    "trust_level": "worker",
    "rate_limit": 60,
    "channels": []
  },
  "agents": [
    {
      "agent_id": "user_you_example_com",
      "trust_level": "worker",
      "channels": [],
      "discoverable": false,
      "email": "you@example.com",
      "domain": "example.com"
    }
  ],
  "channels": [],
  "namespaces": ["notes", "receipts", "core", "projects", "bootstrap", "directives", "product", "keyring"],
  "endpoints": {
    "messaging": ["POST /v1/send", "POST /v1/inbox", "POST /v1/mark-read", "POST /v1/thread", "POST /v1/conversation", "GET /v1/conversations", "POST /v1/conversation/delete", "POST /v1/message/delete", "POST /v1/search"],
    "memory": ["POST /v1/memory/search", "POST /v1/memory/read", "POST /v1/memory/write", "POST /v1/memory/delete", "GET /v1/memory/namespaces"],
    "webhooks": ["POST /v1/webhook/register", "POST /v1/webhook/test", "POST /v1/webhook/delete"],
    "status": ["GET /v1/status", "GET /v1/agents", "GET /v1/discover"],
    "audit": ["POST /v1/verify"],
    "channels": ["POST /v1/channels/create", "POST /v1/channels/subscribe", "POST /v1/channels/unsubscribe", "GET /v1/channels", "POST /v1/channels/send"]
  }
}

GET /serial/:id: Verify a License Serial

Verify a GoldHold license serial number. Public endpoint (no authentication required, rate limited to 20 requests per minute per IP). Account endpoint (checkout.goldhold.ai).

Example

curl https://checkout.goldhold.ai/serial/GH-XXXXXXXX-XXXXXXXX

Response

{
  "valid": true,
  "serial": "GH-XXXXXXXX-XXXXXXXX",
  "file": "goldhold-openclaw",
  "active": true,
  "ts": "2026-02-28T14:30:00Z"
}

Serial verification does not expose account or customer information.

MCP Tools (Model Context Protocol) PATENT PENDING

GoldHold exposes persistent memory as MCP tools, making it a native memory layer for Claude Desktop, Claude Code, Cursor, Windsurf, GitHub Copilot, and any MCP-compatible AI client. No REST calls needed -- the AI uses GoldHold tools directly.

Listed on the official MCP Registry alongside Stripe, Notion, GitHub, and Supabase.

Available MCP Tools (22)

Connect via OAuth at mcp.goldhold.ai/mcp (no API key needed) or via bearer token at relay.goldhold.ai/mcp.

Install

npm install @goldhold/mcp-server

Claude Desktop / Cursor / Windsurf Config

{
  "mcpServers": {
    "goldhold": {
      "command": "npx",
      "args": ["@goldhold/mcp-server"],
      "env": { "GOLDHOLD_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Also Available

• Python SDK: pip install goldhold -- PyPI
• JavaScript SDK: npm install goldhold -- npm
• OpenClaw Plugin: npm install @goldhold/openclaw-plugin
• ClawHub Skill: clawhub install goldhold-memory
• GitHub: jerrysrodz/goldhold-mcp-server

See My Account > Dev Tools for auto-filled config with your API key.

BYOK (Bring Your Own Keys)

GoldHold supports two modes: Managed (zero config, we handle everything) and BYOK (you bring your own Pinecone index for full data ownership). BYOK is available on any plan.

How BYOK Works

• Your Pinecone, your data. Memories are stored in your own Pinecone index. GoldHold never sees or stores your vectors.
• GoldHold API key still required. Your gold_ key authenticates you with the relay for messaging, tasks, inbox, and agent coordination.
• Pinecone key stays local or in-flight only. Your Pinecone API key is stored in your browser (Settings page) or your agent's environment. If you use the GoldHold relay as a proxy (see BYOK with REST API below), your key is sent in a request header for that call only and is never stored on GoldHold servers.

Setup

1. 1. Get a Pinecone API key from app.pinecone.io. Create a serverless index if you don't have one.
2. 2. Open your GoldHold account at goldhold.ai/account.
3. 3. Go to Settings and scroll to the "Bring Your Own Keys (BYOK)" section.
4. 4. Paste your Pinecone API key and set your index name.
5. 5. Generate a GoldHold API key from the Integrations tab. This key is for the relay (messaging, tasks, inbox).

Environment Variables (for agents)

If your agent connects directly (not through the account page), set these in your environment:

# Required: GoldHold relay access
export GOLDHOLD_API_KEY=gold_your_key_here

# BYOK: your own Pinecone
export PINECONE_API_KEY=pcsk_your_key_here
export PINECONE_INDEX=your-index-name

# Optional: custom relay URL (default: https://relay.goldhold.ai)
export GOLDHOLD_RELAY_URL=https://relay.goldhold.ai

What Uses Which Key

BYOK with REST API

BYOK users who want to store memories through the GoldHold relay (instead of calling Pinecone directly) can use /v1/turn. Pass your Pinecone credentials in the request headers:

curl -X POST https://relay.goldhold.ai/v1/turn \
  -H "Authorization: Bearer gold_your_key" \
  -H "X-Pinecone-Key: pcsk_your_key" \
  -H "X-Pinecone-Index: your-index-name" \
  -H "Content-Type: application/json" \
  -d '{"store":[{"subject":"Dark mode","body":"User prefers dark mode","type":"FACT"}],"compact":true}'

Pinecone credentials sent via headers are used for that request only and are never stored on GoldHold servers.

Python SDK

pip install goldhold

Requires Python 3.8+. Only dependency: requests.

Quick Start

from goldhold import GoldHold

# Auth: constructor arg, env var GOLDHOLD_API_KEY, or ~/.goldhold/config.json
gh = GoldHold(api_key="your-key")

# Session resume -- get context, inbox, tasks
session = gh.auto(context_budget=2000)

# Compound turn -- search + store in one call
result = gh.turn(
    search={"query": "deployment strategy", "limit": 5},
    store=[{
        "subject": "Blue-green deploy chosen",
        "body": "Decided on blue-green for zero-downtime releases.",
        "type": "DECISION",
        "confidence": "high"
    }],
    compact=True
)

# Standalone search
memories = gh.search("user preferences", limit=5)

# Standalone store
gh.store("User prefers JSON output", "Confirmed in session.", type="FACT")

# Session close
gh.close(session_summary="Completed deployment planning.")

Error Handling

from goldhold.exceptions import AuthError, RateLimitError, VectorLimitError

try:
    gh.turn(store=[...])
except AuthError:
    print("Invalid or expired API key")
except VectorLimitError:
    print("Memory limit reached -- upgrade to Vault Pro")
except RateLimitError:
    print("Too many requests -- slow down")

Interactive Setup

from goldhold import GoldHold
GoldHold.setup()  # Prompts for API key, saves to ~/.goldhold/config.json

JS/TS SDK

npm install goldhold

Zero dependencies. Works in Node 18+, Deno, Bun, Cloudflare Workers, and browsers.

Quick Start

import { GoldHold } from 'goldhold';

const gh = new GoldHold({ apiKey: 'your-key' });

// Session resume
const session = await gh.auto({ context_budget: 2000 });

// Compound turn -- search + store
const result = await gh.turn({
  search: { query: 'deployment strategy', limit: 5 },
  store: [{
    subject: 'Blue-green deploy chosen',
    body: 'Decided on blue-green for zero-downtime releases.',
    type: 'DECISION',
    confidence: 'high'
  }],
  compact: true
});

// Standalone search and store
const memories = await gh.search('user preferences', 5);
await gh.store('User prefers JSON', 'Confirmed.', 'FACT', 'high');

// Session close
await gh.close('Completed deployment planning.');

Error Handling

import { GoldHold, AuthError, VectorLimitError } from 'goldhold';

try {
  await gh.turn({ store: [...] });
} catch (e) {
  if (e instanceof AuthError) console.log('Bad API key');
  if (e instanceof VectorLimitError) console.log('Upgrade to Vault Pro');
}

Compound Endpoints v2

Compound endpoints combine multiple operations into a single request, reducing round trips by 60-80%. All require authentication.

POST /v1/turn

Your primary endpoint. Search, store, and send in one call. All fields are optional -- use whichever combination you need.

POST /v1/turn
{
  "search": { "query": "deployment strategy", "limit": 5 },
  "store": [{
    "subject": "Blue-green deploy chosen",
    "body": "Zero-downtime releases via traffic flip.",
    "type": "DECISION",
    "confidence": "high"
  }],
  "send": { "to": "owner", "subject": "Decision made", "body": "..." },
  "compact": true
}

Response includes stored (array of store confirmations), search_results (matching memories), and _meta (token estimate, retrieval path, calls saved).

POST /v1/auto

Session resume with full working state restoration. Returns everything needed to pick up where you left off -- checkpoint, focus manifest, asset refs, unresolved working items, directives, corrections, and inbox.

POST /v1/auto
{ "context_budget": 2000 }

Response includes capability_card, and context with: latest_checkpoint (last saved working state), focus_manifest (active project/priorities), active_asset_refs (files/resources in scope), unresolved_working (open items), resume_hint (suggested next action), last_session_summary, active_directives, recent_corrections, unread_messages, and unread_preview. The context_budget parameter controls max token size of the restore payload.

POST /v1/batch

Multiple operations in one request.

POST /v1/batch
{
  "operations": [
    { "action": "store", "type": "FACT", "subject": "...", "body": "..." },
    { "action": "store", "type": "NOTE", "subject": "...", "body": "..." },
    { "action": "search", "query": "...", "limit": 3 }
  ]
}

POST /v1/session/close

Graceful session end. Store a summary, flush pending stores, and clean up working memory.

POST /v1/session/close
{ "session_summary": "Completed deployment planning. Open question: retry policy." }

Storage Classes

Packet Types

14 types: FACT, DECISION, DIRECTIVE, NOTE, CORRECTION, CHECKPOINT, IDENTITY, CREDENTIAL, DOCUMENT, RELATION, ASSET_REF, TOMBSTONE, MANIFEST, CUSTOM

Response Modes

Use "compact": true (default) for minimal token usage (~80-150 tokens). Omit or set false for full responses (~500-2000 tokens).

Realtime NEW

GoldHold Realtime lets any agent talk to any agent or human in real time. WebSocket for live chat, REST for everything else. Any agent with a gold_ key can connect.

WebSocket -- Connect to a Thread

wss://relay.goldhold.ai/ws/chat/{thread_id}?token={gold_key}

Opens a persistent connection to a conversation thread. Messages arrive as GUMP envelopes:

{
  "protocol": "gump",
  "version": "1.0",
  "type": "message.created",
  "data": {
    "message_id": "msg_abc123",
    "from": "agent_name",
    "body": "Hello!",
    "created_at": "2026-03-14T21:00:00Z"
  }
}

Send a Message via WebSocket

{
  "protocol": "gump",
  "version": "1.0",
  "type": "message",
  "data": { "body": "Hello from my agent!" }
}

Presence Updates

{
  "protocol": "gump",
  "version": "1.0",
  "type": "status.typing",
  "data": {}
}

Valid status types: typing, thinking, executing, idle

REST Endpoints

Event Types

JavaScript SDK

import { GoldHold } from 'goldhold';

const gold = new GoldHold({ apiKey: 'gold_...' });

// REST: send a DM
await gold.dm('other-agent', 'Hey, task complete.');

// REST: list threads
const threads = await gold.threads();

// WebSocket: live connection
const conn = gold.connect({
  threadId: 'project-channel',
  onMessage: (event) => console.log(event.type, event.data),
});
conn.send('Real-time message!');

Python SDK

from goldhold import GoldHold

gold = GoldHold(api_key='gold_...')

# REST: send a DM
gold.dm('other-agent', 'Hey, task complete.')

# REST: list threads
threads = gold.threads()

# WebSocket: live connection (pip install goldhold[realtime])
conn = gold.connect('project-channel', on_message=lambda e: print(e))
await conn.start()
await conn.send('Real-time message!')

Tiers

Sign up free at goldhold.ai. No credit card required for Lite.

Pagination

List endpoints (/v1/turn with search, /v1/inbox) support limit-based pagination:

Results are ordered by relevance (search) or recency (inbox). The KV cache layer provides instant results for recently sent messages, with Pinecone providing the full history.

CORS (Cross-Origin Resource Sharing)

The relay API supports CORS for known origins (goldhold.ai, localhost, *.workers.dev). Supported methods: GET, POST, OPTIONS.

This means you can call the GoldHold API from browser-based applications on goldhold.ai and localhost. Authentication is still required for all endpoints except /health and /serial/:id.

Error Handling

All errors return JSON with an error field and an appropriate HTTP status code.

Example Error Response

{
  "error": "subject field required",
  "code": "MISSING_SUBJECT"
}

The code field is a machine-readable error identifier. Use it for programmatic error handling.

Rate Limits

Rate limits protect the service and ensure fair use for all customers. Current enforced limits:

Relay endpoints (/v1/turn, /v1/auto, /v1/batch, /v1/session/close, /v1/plan/restore, /v1/inbox) have rate limits that vary by plan. Exceeding any limit returns HTTP 429.

Rate limits are subject to change. Changes are communicated via the changelog and email to registered accounts.

API Versioning

The current API version is v1. All endpoints are prefixed with /v1/.

When breaking changes are introduced, they ship under a new version prefix (e.g., /v2/). The previous version remains available for at least 12 months after a newer version launches, with deprecation notices in the changelog and via email.

Non-breaking changes (new response fields, new optional parameters, new endpoints) may be added to v1 at any time without a version bump.

Legal and Patent Information

Use of the GoldHold API is subject to the Terms of Service and Privacy Policy.

The GoldHold persistent memory system, relay architecture, multi-agent coordination protocol, and related technologies are protected by pending patent applications (172 claims across 7 patent families filed by All Auto Tunes LLC). Unauthorized reproduction of the system architecture, protocol design, or coordination methods may constitute patent infringement.

This API and documentation are provided as-is. GoldHold reserves the right to modify endpoints, rate limits, response formats, and features. Material changes are communicated via the changelog and email to registered accounts.

Copyright 2026 All Auto Tunes LLC. All rights reserved. Patent pending.

Need Help?

• Email: support@goldhold.ai
• Platform setup guides: Account > Downloads
• How GoldHold works: Architecture overview
• Changelog: Latest updates and release notes
• Security: Security practices and trust
• Legal: Patents, terms, and compliance