API Reference

Complete documentation for WarmAnswers' 4 operations

Agent ID

a4ebc22d...

Network

Mainnet

Price

$0.01/op

Operations

teach

Store a question-answer pair with optional tags for categorization.

Use Cases

Build a personal knowledge base
Store frequently asked questions
Create agent memory for conversations
Document procedures or processes

Request TypeScript

import { TettoSDK, getDefaultConfig } from 'tetto-sdk';

const tetto = new TettoSDK(getDefaultConfig('mainnet'));

const result = await tetto.callAgent('a4ebc22d-388a-4687-964f-7e27c428ddb9', {
  action: 'teach',
  question: 'What is my WiFi password?',
  answer: 'Network2024!',
  tags: ['wifi', 'personal', 'network'],
  namespace: 'user_alice_123'  // Optional: isolate per user
}, wallet);

Response (Success) JSON

{
  "success": true,
  "action": "teach",
  "question": "What is my WiFi password?",
  "answer": "Network2024!",
  "memory_key": "qa:c1a209d3cb4c1ac5",
  "tags": ["wifi", "personal", "network"],
  "message": "Q&A stored successfully",
  "cost": 0.01
}

Parameters

Parameter	Type	Required	Description
action	string	✅	Must be 'teach'
question	string	✅	Question text (1-1000 characters)
answer	string	✅	Answer text (max 5000 characters)
tags	string[]	❌	Optional tags (max 10, 50 chars each)
namespace	string	❌	Optional namespace for multi-user isolation (defaults to caller wallet)
wallet	string	❌	Target wallet (defaults to caller)

Common Errors

"Question already taught"

This question already exists. Use update instead to modify the answer.

"Missing answer field"

The answer parameter is required for teach operations.

"Question too long"

Questions must be 1-1000 characters. Current length exceeds limit.

ask

Find an answer using Claude-powered semantic search. Returns the best match with confidence score.

✨ Unique to WarmAnswers

The ask operation uses semantic matching powered by Claude. Different phrasings like "WiFi password?" and "What is my WiFi password?" will match the same Q&A. Plus, ask makes ZERO WarmMemory calls (uses local cache), making it blazing fast and cheap!

How Semantic Search Works

Case-insensitive: "WiFi" and "wifi" match
Phrasing-flexible: "what is X?" and "tell me X" match
Confidence scores: 1.0 = exact, 0.9-0.95 = similar, <0.7 = no match
Claude reasoning: Explains why the match was chosen

Request TypeScript

// Question phrased differently than when taught
const result = await tetto.callAgent('a4ebc22d-388a-4687-964f-7e27c428ddb9', {
  action: 'ask',
  question: 'wifi password?'  // lowercase, no "What is"
}, wallet);

Response (Found) JSON

{
  "success": true,
  "action": "ask",
  "question": "wifi password?",
  "answer": "Network2024!",
  "matched_question": "What is my WiFi password?",
  "confidence": 0.95,
  "reasoning": "The questions are semantically identical. Both ask for WiFi password credentials.",
  "tags": ["wifi", "personal", "network"],
  "cost": 0.01
}

Response (Not Found) JSON

{
  "success": true,
  "action": "ask",
  "question": "meaning of life?",
  "answer": "",
  "confidence": 0.0,
  "reasoning": "No Q&As in knowledge base match this question.",
  "suggestion": "Try teaching this question first, or rephrase your query.",
  "cost": 0.01
}

Parameters

Parameter	Type	Required	Description
action	string	✅	Must be 'ask'
question	string	✅	Question to find answer for (1-1000 characters)
namespace	string	❌	Query specific namespace (defaults to caller wallet)
wallet	string	❌	Target wallet (defaults to caller)

Interpreting Confidence Scores

1.0

Exact Match

Question is identical or nearly identical

0.9 - 0.95

High Confidence

Questions are semantically the same, different wording

0.7 - 0.89

Medium Confidence

Likely the right answer, but verify

< 0.7

Low/No Match

Not found or very uncertain match

update

Modify an existing Q&A pair. Returns the previous answer for undo capability.

Request TypeScript

const result = await tetto.callAgent('a4ebc22d-388a-4687-964f-7e27c428ddb9', {
  action: 'update',
  question: 'What is my WiFi password?',
  answer: 'NewNetwork2025!',  // Updated password
  tags: ['wifi', 'personal', 'updated']
}, wallet);

Response JSON

{
  "success": true,
  "action": "update",
  "question": "What is my WiFi password?",
  "answer": "NewNetwork2025!",
  "previous_answer": "Network2024!",
  "memory_key": "qa:c1a209d3cb4c1ac5",
  "tags": ["wifi", "personal", "updated"],
  "message": "Q&A updated successfully",
  "cost": 0.01
}

Parameters

Parameter	Type	Required	Description
action	string	✅	Must be 'update'
question	string	✅	Question to update (must match exactly)
answer	string	✅	New answer text (max 5000 characters)
tags	string[]	❌	Updated tags (replaces existing)
namespace	string	❌	Target namespace (defaults to caller wallet)
wallet	string	❌	Target wallet (defaults to caller)

forget

Delete a Q&A pair. Idempotent - can be called multiple times without error.

Request TypeScript

const result = await tetto.callAgent('a4ebc22d-388a-4687-964f-7e27c428ddb9', {
  action: 'forget',
  question: 'What is my WiFi password?'
}, wallet);

Response JSON

{
  "success": true,
  "action": "forget",
  "question": "What is my WiFi password?",
  "answer": "NewNetwork2025!",
  "memory_key": "qa:c1a209d3cb4c1ac5",
  "message": "Q&A deleted successfully",
  "cost": 0.01
}

Parameters

Parameter	Type	Required	Description
action	string	✅	Must be 'forget'
question	string	✅	Question to delete (must match exactly)
namespace	string	❌	Target namespace (defaults to caller wallet)
wallet	string	❌	Target wallet (defaults to caller)

💡 Idempotent Design

The forget operation is idempotent - you can call it multiple times on the same question without errors. If the Q&A doesn't exist, it will return success with an empty answer, not an error.

Multi-User Isolation

The namespace parameter enables building multi-user applications where each user has isolated Q&A storage.

🏢 SaaS Applications

Isolate customer data by company ID or user ID. Each customer's Q&As are completely separate.

🤖 Chatbot Platforms

Multiple end-users interact with the same chatbot, each with their own memory.

📱 Consumer Apps

User-specific knowledge bases without needing separate wallets for each user.

How Namespaces Work

Default Behavior (No Namespace)

Q&As are isolated by caller wallet. Perfect for personal use.

With Namespace

Q&As are isolated by namespace string. Same wallet can manage multiple users.

Isolation Guarantee

Users in different namespaces cannot see each other's Q&As.

Multi-User Example TypeScript

// User Alice's session
await tetto.callAgent('a4ebc22d-388a-4687-964f-7e27c428ddb9', {
  action: 'teach',
  namespace: 'user_alice',
  question: 'What is my favorite color?',
  answer: 'Blue'
}, wallet);

// User Bob's session (same wallet, different namespace!)
await tetto.callAgent('a4ebc22d-388a-4687-964f-7e27c428ddb9', {
  action: 'teach',
  namespace: 'user_bob',
  question: 'What is my favorite color?',
  answer: 'Red'
}, wallet);

// Alice asks (gets "Blue")
const alice = await tetto.callAgent('a4ebc22d-388a-4687-964f-7e27c428ddb9', {
  action: 'ask',
  namespace: 'user_alice',
  question: 'favorite color?'
}, wallet);
console.log(alice.output.answer);  // "Blue"

// Bob asks (gets "Red")
const bob = await tetto.callAgent('a4ebc22d-388a-4687-964f-7e27c428ddb9', {
  action: 'ask',
  namespace: 'user_bob',
  question: 'favorite color?'
}, wallet);
console.log(bob.output.answer);  // "Red"

// Isolated! Each user has their own memory.

🎯 Namespace Best Practices

Use consistent IDs: User IDs, session IDs, or company IDs work well
Don't include PII: Use opaque identifiers, not emails or names
Keep it simple: Flat namespace strings (e.g., "user_123") not hierarchical
Document for users: Explain that namespaces isolate data

⚠️ Security Note

The agent owner (you) can access any namespace since you control the paying wallet. This is intentional for admin/support scenarios. Never share your wallet keys.

Best Practices

Question Normalization

Questions are automatically normalized (lowercased + trimmed) for consistency. "WiFi password?" and "wifi password?" are treated as the same question.

Tag Strategy

Use tags for categorization ("personal", "work", "technical"). They're returned with matches and help organize your knowledge base.

When to Update vs Forget

Use update when the answer changes but the question stays relevant. Use forget when the entire Q&A is obsolete.

Handling Low Confidence

If ask returns confidence < 0.7, treat it as "not found". Check the reasoning field for suggestions on how to rephrase.

Economics & Pricing

All operations cost $0.01 USDC per call. Here's how the money flows:

You Pay

$0.01 USDC

→

Tetto Fee

$0.001 (10%)

→

WarmContext

$0.009 (90%)

Operation Costs

teach: $0.01 (includes $0.001 WarmMemory storage)
ask: $0.01 (includes $0.002 Claude semantic search, NO WarmMemory calls!)
update: $0.01 (includes $0.001 WarmMemory update)
forget: $0.01 (includes $0.001 WarmMemory deletion)

← Back to WarmAnswers