Skip to main content

​
Tools API

The Tools Library provides agentic capabilities for your AI applications. Add web search, document retrieval (RAG), and conversation memory with a single API.

​
Available Tools

ToolDescriptionAvailability
Web SearchReal-time web search with AI-optimized resultsAll tiers
Documents/RAGUpload and query documents with semantic searchPro+
MemoryPersistent conversation context across sessionsPro+
Search the web in real-time with AI-optimized results.

​
Endpoint

POST https://api.withperf.pro/v1/tools/search

​
Request

curl -X POST https://api.withperf.pro/v1/tools/search \
  -H "Authorization: Bearer pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest developments in AI agents",
    "max_results": 5,
    "search_depth": "basic"
  }'
ParameterTypeDefaultDescription
querystringrequiredSearch query
max_resultsinteger5Maximum results to return (1-10)
search_depthstring”basic”Search depth: basic or advanced
include_domainsstring[]-Only include results from these domains
exclude_domainsstring[]-Exclude results from these domains

​
Response

{
  "results": [
    {
      "title": "AI Agents Are Transforming Software Development",
      "url": "https://example.com/ai-agents-2024",
      "content": "Recent advances in AI agents have enabled autonomous coding, debugging, and deployment...",
      "relevance_score": 0.95
    }
  ],
  "metadata": {
    "provider": "perf",
    "latency_ms": 1234,
    "cost_usd": 0.01
  }
}

​
Pricing

TierCost per Search
Starter$0.015
Pro$0.012
Growth$0.011
Team$0.01

​
Documents / RAG

Upload documents and query them with semantic search. Perfect for building knowledge bases, FAQ bots, and document Q&A.

​
Upload Document

POST https://api.withperf.pro/v1/documents

curl -X POST https://api.withperf.pro/v1/documents \
  -H "Authorization: Bearer pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "company-handbook.pdf",
    "content": "base64-encoded-content-here",
    "content_type": "application/pdf",
    "collection": "hr-docs",
    "metadata": {
      "department": "HR",
      "version": "2024"
    }
  }'
ParameterTypeDescription
filenamestringOriginal filename
contentstringBase64-encoded file content or plain text
content_typestringMIME type (application/pdf, text/plain, text/markdown)
collectionstringCollection name (default: “default”)
metadataobjectCustom metadata for filtering
Response: 
{
  "id": "doc_abc123",
  "filename": "company-handbook.pdf",
  "status": "processing",
  "chunk_count": 0,
  "file_size_bytes": 125000,
  "collection": "hr-docs",
  "created_at": "2024-01-15T10:30:00Z"
}
Document Status:
  • processing - Being chunked and embedded
  • ready - Available for search
  • failed - Processing failed (check error_message)

​
Query Documents

POST https://api.withperf.pro/v1/documents/query

curl -X POST https://api.withperf.pro/v1/documents/query \
  -H "Authorization: Bearer pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the vacation policy?",
    "collection": "hr-docs",
    "top_k": 5,
    "threshold": 0.3
  }'
ParameterTypeDefaultDescription
querystringrequiredSearch query
collectionstring”default”Collection to search
top_kinteger5Maximum results
thresholdnumber0.3Minimum similarity score (0-1)
Response: 
{
  "query": "What is the vacation policy?",
  "results": [
    {
      "chunk_id": "chunk_xyz789",
      "document_id": "doc_abc123",
      "filename": "company-handbook.pdf",
      "content": "Employees receive 20 days of paid vacation per year, accrued monthly...",
      "score": 0.94,
      "chunk_index": 15,
      "metadata": {
        "department": "HR"
      }
    }
  ],
  "metadata": {
    "latency_ms": 234,
    "cost_usd": 0.0001
  }
}

​
List Documents

GET https://api.withperf.pro/v1/documents?collection=hr-docs

​
Delete Document

DELETE https://api.withperf.pro/v1/documents/{documentId}

​
Document Limits by Tier

TierDocumentsStorageCollections
Pro5001 GB10
Growth5,00010 GB50
Team50,000100 GB500
Enterprise500,0001 TB5,000

​
Memory / Context

Persist conversation context across sessions. The AI remembers previous interactions without you managing conversation history.

​
Using Memory with Chat

Add session_id to your chat requests to enable memory: 
curl -X POST https://api.withperf.pro/v1/chat \
  -H "Authorization: Bearer pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hi, my name is Sarah"}
    ],
    "session_id": "user_123_conversation",
    "memory": {
      "enabled": true,
      "include_last_n": 10
    }
  }'
ParameterTypeDescription
session_idstringUnique session identifier
memory.enabledbooleanEnable memory for this request
memory.include_last_nintegerInclude last N messages from memory
Now in a subsequent request: 
curl -X POST https://api.withperf.pro/v1/chat \
  -H "Authorization: Bearer pk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is my name?"}
    ],
    "session_id": "user_123_conversation",
    "memory": {"enabled": true}
  }'
The AI will remember: “Your name is Sarah, as you mentioned earlier.”

​
Memory Management

List Sessions: 
GET https://api.withperf.pro/v1/memory
Get Session: 
GET https://api.withperf.pro/v1/memory/{sessionId}
Clear Session: 
POST https://api.withperf.pro/v1/memory/{sessionId}/clear
Delete Session: 
DELETE https://api.withperf.pro/v1/memory/{sessionId}

​
Memory Limits by Tier

TierMemory TokensSessionsRetention
Pro100,00010030 days
Growth500,0001,00090 days
Team2,000,00010,0001 year
Enterprise10,000,000100,0002 years

​
Auto-Summarization

When a session approaches its token limit, Perf automatically:
  1. Summarizes older messages
  2. Preserves recent messages intact
  3. Continues conversation with summary + recent context
This ensures conversations can continue indefinitely within your tier limits.

​
Combining Tools

Tools work together seamlessly. For example, search the web, store relevant information in documents, and use memory to maintain context: 
# 1. Search for current information
curl -X POST https://api.withperf.pro/v1/tools/search \
  -H "Authorization: Bearer pk_live_abc123" \
  -d '{"query": "latest AI news today"}'

# 2. Chat with memory and context
curl -X POST https://api.withperf.pro/v1/chat \
  -H "Authorization: Bearer pk_live_abc123" \
  -d '{
    "messages": [{"role": "user", "content": "Summarize the AI news I just searched"}],
    "session_id": "research_session",
    "memory": {"enabled": true}
  }'

​
Pricing Summary

ToolPricing Model
Web SearchPer search ($0.01-0.015)
DocumentsPer embedding token
MemoryIncluded in tier

​
Plan Availability

FeatureStarterProGrowthTeamEnterprise
Web SearchYesYesYesYesYes
Documents/RAG-YesYesYesYes
Memory-YesYesYesYes