API Documentation - Digital Twin Creator

🔐 Authentication

All API requests require authentication using API keys. You can generate API keys from your profile dashboard.

🔑 Getting Your API Key (Step by Step)

Sign up or log in to your account at knowforge.com
Go to your Profile → API Keys
Click "Generate New API Key"
Copy your API key (starts with sk-)
Keep it secure - you won't see it again!

Using API Keys

Include your API key in the request headers using one of these methods:

# Using Authorization header (recommended)
Authorization: Bearer sk-your-api-key-here

# Using X-API-Key header
X-API-Key: sk-your-api-key-here
                

🔑 API Key Format

API keys start with sk- followed by a 32-character random string. Example: sk-abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

⚠️ Important Security Notes

Never share your API key publicly
Keep your API key secure and rotate it regularly
Each API call costs 1 credit from your account
You start with 500 free credits

⚡ Rate Limits

To ensure fair usage and system stability, the following rate limits apply:

Requests per minute

1,000

Requests per hour

10,000

Requests per day

⚠️ Rate Limit Exceeded

When you exceed rate limits, you'll receive a 429 Too Many Requests response. Wait for the rate limit window to reset before making more requests.

⚠️ Error Handling

Here are the most common errors you might encounter and how to fix them:

Error Code	Error Message	What It Means	How to Fix
401	Invalid API key	Your API key is incorrect or missing	Check your API key and make sure it starts with "sk-"
402	Insufficient credits	You've run out of credits	Buy more credits or wait for your free credits to reset
404	Agent not found	The agent ID doesn't exist	Check your agent ID or create a new agent
429	Too many requests	You're making requests too quickly	Wait a moment and try again
500	Internal server error	Something went wrong on our end	Try again in a few minutes

🔧 Debugging Tips

Always check your API key format (should start with "sk-")
Make sure your JSON is valid (use a JSON validator)
Check that all required fields are included
Verify your agent ID exists before using it
Monitor your credit balance in your dashboard

🎯 Beginner's Guide

New to APIs? No problem! This guide will walk you through creating your first AI agent step by step.

📋 What You'll Learn

How to get your API key
How to create your first AI agent
How to chat with your agent
How to generate speech

Step 1: Get Your API Key

# 1. Go to https://knowforge.com and sign up/login
# 2. Go to Profile → API Keys
# 3. Click "Generate New API Key"
# 4. Copy your key (starts with sk-)
# Example: sk-abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
                

Step 2: Create Your First AI Agent

curl -X POST "https://knowforge.com/api/v1/agents/api-key" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First AI Assistant",
    "system_prompt": "You are a helpful and friendly AI assistant."
  }'
                

Step 3: Chat with Your Agent

curl -X POST "https://knowforge.com/api/v1/agents/YOUR_AGENT_ID/chat/api-key" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello! How are you?"
  }'
                

Step 4: Check Your Credit Balance

curl -X GET "https://knowforge.com/api/v1/credits/balance" \
  -H "Authorization: Bearer sk-your-api-key-here"
                

💡 Pro Tips

Each API call costs 1 credit (you get 500 free credits)
Keep your API key secure - never share it publicly
Use conversation_history to maintain context in long chats
Check your credit balance regularly to avoid running out
Test with simple messages first, then get creative!

🚀 API Endpoints

🤖 Digital Twin Management

Create and manage your AI agents (digital twins) using these endpoints.

💡 Quick Start

1. Create an agent → 2. List your agents → 3. Chat with your agent → 4. Check credits → 5. Generate speech

POST /api/v1/agents/api-key

Create a new AI agent using API key authentication

Parameter	Type	Required	Description
name	string	Required	Name of your AI agent
llm_provider	string	Optional	AI provider: "gemini" or "openai" (default: "gemini")
llm_model	string	Optional	AI model: "gemini-2.0-flash-001", "gpt-4", etc. (default: "gemini-2.0-flash-001")
voice	string	Optional	Voice: "alloy", "coral", "echo", "fable", "onyx", "nova" (default: "alloy")
language	string	Optional	Language code: "en", "es", "fr", etc. (default: "en")
system_prompt	string	Optional	Personality and behavior instructions
first_message	string	Optional	Agent's first greeting message

curl -X POST "https://knowforge.com/api/v1/agents/api-key" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Assistant",
    "llm_provider": "gemini",
    "llm_model": "gemini-2.0-flash-001",
    "voice": "alloy",
    "language": "en",
    "system_prompt": "You are a helpful and friendly AI assistant.",
    "first_message": "Hello! How can I help you today?"
  }'
                    

✅ Response

{
  "id": "abc123-def456-ghi789",
  "name": "My AI Assistant",
  "llm_provider": "gemini",
  "llm_model": "gemini-2.0-flash-001",
  "voice": "alloy",
  "language": "en",
  "created_at": "2024-01-15T10:30:00Z",
  "message": "Agent created successfully"
}
                        

GET /api/v1/agents/api-key

List all your AI agents

curl -X GET "https://knowforge.com/api/v1/agents/api-key" \
  -H "Authorization: Bearer sk-your-api-key-here"
                    

✅ Response

{
  "agents": [
    {
      "id": "abc123-def456-ghi789",
      "name": "My AI Assistant",
      "llm_provider": "gemini",
      "llm_model": "gemini-2.0-flash-001",
      "voice": "alloy",
      "language": "en",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
                        

GET /api/v1/agents/{agent_id}/api-key

Get details of a specific AI agent

curl -X GET "https://knowforge.com/api/v1/agents/abc123-def456-ghi789/api-key" \
  -H "Authorization: Bearer sk-your-api-key-here"
                    

✅ Response

{
  "status": "success",
  "id": "abc123-def456-ghi789",
  "name": "My AI Assistant",
  "llm_provider": "gemini",
  "llm_model": "gemini-2.0-flash-001",
  "voice": "alloy",
  "language": "en",
  "system_prompt": "You are a helpful and friendly AI assistant.",
  "first_message": "Hello! How can I help you today?",
  "created_at": "2024-01-15T10:30:00Z"
}
                        

💰 Credit Management

Check your credit balance and usage information.

GET /api/v1/credits/balance

Get your current credit balance and account information

curl -X GET "https://knowforge.com/api/v1/credits/balance" \
  -H "Authorization: Bearer sk-your-api-key-here"
                    

✅ Response

{
  "status": "success",
  "user_id": "user_123",
  "email": "user@example.com",
  "credits": 498,
  "tier_name": "free",
  "last_updated": "2024-08-27T11:57:32Z"
}
                        

💬 Chat with AI Agents

POST /api/v1/agents/{agent_id}/chat/api-key

Send a text message to your AI agent

Parameter	Type	Required	Description
message	string	Required	Your message to the AI agent
conversation_history	array	Optional	Previous messages in the conversation

curl -X POST "https://knowforge.com/api/v1/agents/abc123-def456-ghi789/chat/api-key" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello! How are you today?",
    "conversation_history": [
      {
        "role": "user",
        "content": "Hi there!"
      },
      {
        "role": "assistant", 
        "content": "Hello! I'm doing great, thanks for asking!"
      }
    ]
  }'
                    

✅ Response

{
  "status": "success",
  "response": "I'm doing wonderful! Thank you for asking. How can I help you today?",
  "agent_id": "abc123-def456-ghi789",
  "message": "Hello! How are you today?",
  "conversation_history": [...]
}
                        

POST /api/v1/agents/{agent_id}/speak

Get speech synthesis for a message

Parameter	Type	Required	Description
text	string	Required	Text to convert to speech
voice	string	Optional	Voice to use (default: agent's voice)

curl -X POST "https://knowforge.com/api/v1/agents/your-agent-id/speak" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello! This is a test message.",
    "voice": "coral"
  }'
                    

API Key Management

POST /api/v1/api-keys/generate

Generate a new API key

Parameter	Type	Required	Description
name	string	Required	Name for the API key

curl -X POST "https://knowforge.com/api/v1/api-keys/generate" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key"
  }'
                    

GET /api/v1/api-keys/list

List all your API keys

curl -X GET "https://knowforge.com/api/v1/api-keys/list" \
  -H "Authorization: Bearer your-jwt-token"
                    

GET /api/v1/api-keys/usage/{api_key_id}

Get usage statistics for an API key

curl -X GET "https://knowforge.com/api/v1/api-keys/usage/your-api-key-id?days=30" \
  -H "Authorization: Bearer your-jwt-token"
                    

💰 Cost Calculation

API usage is tracked and costs are calculated based on the AI model used and the number of tokens processed.

Model Pricing (per 1K tokens)

Model	Cost per 1K tokens	Provider
GPT-4	$0.030	OpenAI
GPT-3.5 Turbo	$0.002	OpenAI
GPT-5	$0.0189	OpenAI
GPT-5 Mini	$0.0038	OpenAI
GPT-5 Nano	$0.0008	OpenAI
Gemini 2.0 Flash 001	$0.0014	Google
Gemini 2.0 Flash Lite	$0.0010	Google
Gemini 2.5 Flash Lite	$0.0014	Google
Gemini 2.5 Flash	$0.0021	Google

Text-to-Speech Pricing

Speech synthesis costs $0.015 per 1,000 characters processed.

📊 Usage Tracking

All API calls are automatically tracked with detailed analytics including:

Number of API calls
Tokens used
Cost in USD
Response times
Endpoint usage breakdown

📋 Response Format

All API responses follow a consistent JSON format:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "tokens_used": 150,
  "cost_usd": 0.0045,
  "model": "gpt-4"
}
                

Error Response

{
  "success": false,
  "error": "Error message here",
  "error_code": "ERROR_CODE"
}
                

Common Error Codes

Code	Description
401	Unauthorized - Invalid or missing API key
429	Too Many Requests - Rate limit exceeded
404	Not Found - Resource not found
500	Internal Server Error - Server error

🔗 Embed Widget

Easily embed voice agents into your website with our JavaScript widget:

Quick Start

Configuration Options

Attribute	Description	Options	Default
data-agent-id	Your agent's unique ID	String	Required
data-theme	Widget appearance theme	floating, minimal, dark, light	floating
data-position	Widget position on page	bottom-right, bottom-left, top-right, top-left	bottom-right
data-size	Widget size	small, medium, large	medium

Advanced Example

💡 Tips

Make sure your agent is active before embedding
Test the widget in different browsers
Consider mobile responsiveness
Monitor usage through your dashboard