🤖 REST API

Rakaba AI Agent
API Documentation

Production-grade API powering a multi-tool AI agent with streaming responses, 4-agent lead research pipeline, Google Sheets integration, and SMS notifications. Built with Node.js, Express, and Google Gemini 2.5 Flash.

Base URL https://api.rakaba.io

🔐 Authentication

All API endpoints require an API key passed via the X-API-Key header. The /health endpoint is public and does not require authentication.

💡 Include your API key in every request using the X-API-Key header. Contact the API owner to obtain a valid key.

Request Header

X-API-Key: your-api-key-here
Content-Type: application/json

Example — Unauthorized (401)

{
  "error": "🔐 API key required."
}

{
  "error": "🔐 Invalid API key."
}

⏱ Rate Limits

Rate limits are applied per IP address to prevent abuse.

Endpoint	Limit	Window
/api/chat, /api/chat/stream	20 requests	per minute
/api/leads/research	10 requests	per minute
All other endpoints	20 requests	per minute

Rate Limited Response (429)

{
  "error": "⏳ Too many requests. Please wait a minute."
}

💬 Chat Agent

AI agent with 3 tools: web search, calculator, and GitHub PR management. Supports both streaming (SSE) and standard JSON responses.

POST /api/chat/stream Streaming chat with SSE ▼

Send a message and receive a streaming response via Server-Sent Events (SSE). The agent automatically selects and uses tools as needed.

Request Body

Field	Type	Required	Description
message	string	required	User message (max 1000 chars)
sessionId	string	optional	Session ID for conversation history (default: "react-ui")

Example Request

curl -X POST https://api.rakaba.io/api/chat/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"message":"what is 25% of $5000?","sessionId":"user-123"}'

SSE Response Events

// Tool being called
data: {"type":"tool", "tool":"calculate"}

// Streaming text chunks
data: {"type":"chunk", "text":"25% "}
data: {"type":"chunk", "text":"of "}
data: {"type":"chunk", "text":"$5000 "}

// Completion with usage data
data: {
  "type": "done",
  "fullAnswer": "25% of $5000 is $1250.",
  "usage": {
    "inputTokens": 342,
    "outputTokens": 18,
    "totalTokens": 360,
    "estimatedCost": "$0.000031"
  }
}

POST /api/chat Standard JSON chat ▼

Example Request

curl -X POST https://api.rakaba.io/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"message":"who founded OpenAI?","sessionId":"user-123"}'

Response

{
  "answer": "OpenAI was founded by Elon Musk, Sam Altman, Greg Brockman..."
}

DELETE /api/chat/:sessionId Clear chat history ▼

Example Request

curl -X DELETE https://api.rakaba.io/api/chat/user-123 \
  -H "X-API-Key: your-api-key"

Response

{ "success": true }

GET /api/profile Get RAG user profile ▼

Returns the persistent user profile extracted from past conversations (RAG memory).

Example Response

{
  "name": "Gossaye",
  "job": "AI Agent Engineer",
  "location": "San Diego",
  "company": "Gosa Notary",
  "preferences": ["Python", "React"],
  "goals": ["Build AI SaaS product"],
  "projects": ["Lead Research Pipeline"]
}

🎯 Lead Research Pipeline

4-agent AI pipeline that researches companies, scores leads, drafts outreach emails, and automatically logs results to Google Sheets.

🔍

Researcher

Agent 1

→

📊

Scorer

Agent 2

→

✍️

Writer

Agent 3

→

💾

Logger

Agent 4

POST /api/leads/research Run full 4-agent pipeline ▼

⏱ This endpoint runs 3 sequential Gemini AI calls and 4 web searches. Expected response time: 15–40 seconds depending on API load.

Request Body

Field	Type	Required	Description
company	string	required	Company name to research (max 100 chars)

Example Request

curl -X POST https://api.rakaba.io/api/leads/research \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"company":"Stripe"}'

Success Response (200)

{
  "success": true,
  "report": {
    "company":   "Stripe",
    "timestamp": "2026-04-25T10:30:00.000Z",
    "research":  "Stripe is a financial infrastructure platform...",
    "news":      "Stripe recently launched...",
    "tech":      "Ruby, Go, React, AWS...",
    "funding":   "$6.5B raised, $50B valuation...",
    "score":     "SCORE: 9\nTIER: HOT\nBUDGET_ESTIMATE: $1M-$10M+\n...",
    "email":     "SUBJECT: Re: Stripe's Infrastructure Growth\n\n..."
  }
}

POST /api/leads/log-sheet Log lead to Google Sheets ▼

Manually log a lead to the connected Google Sheet. Note: /api/leads/research automatically logs to Sheets — this endpoint is for manual logging.

Request Body

Field	Type	Required	Description
company	string	required	Company name
score	string	required	Lead score (1-10)
tier	string	required	HOT, WARM, or COLD
budgetEstimate	string	optional	Budget range estimate
opportunity	string	optional	Opportunity description
emailSubject	string	optional	Outreach email subject
research	string	optional	Research summary

Response

{ "success": true, "message": "Stripe logged to Google Sheets" }

POST /api/leads/send-email Send outreach email via Gmail ▼

Request Body

Field	Type	Required	Description
to	string	required	Recipient email address
subject	string	required	Email subject line
body	string	required	Email body text
company	string	optional	Company name for logging

Response

{ "success": true, "message": "Email sent to contact@stripe.com" }

📱 Notifications

POST /api/notify/sms Send SMS via Twilio ▼

Sends an SMS notification to the configured phone number (used for notary booking alerts).

Request Body

Field	Type	Required	Description
name	string	required	Customer name
phone	string	required	Customer phone number
email	string	required	Customer email
service	string	required	Service requested
message	string	optional	Additional message

GET /health Health check (no auth required) ▼

Response

{ "status": "ok", "message": "Rakaba AI Agent API is running!" }

⚠️ Error Reference

Status	Code	Meaning
401	API key required	No X-API-Key header provided
401	Invalid API key	Key provided but not valid
400	Invalid input detected	Prompt injection attempt blocked
400	Input too long	Message exceeds maximum length
429	Too many requests	Rate limit exceeded — wait 1 minute
500	Internal server error	AI model unavailable or server error

Rakaba AI Agent API • Built with Node.js + Gemini 2.5 Flash

Live Demo GitHub

Rakaba AI AgentAPI Documentation

Rakaba AI Agent
API Documentation