Personas API

Create, manage, and configure AI personas with multi-provider LLM support, knowledge bases, and built-in tools.

Identity

Define unique names, descriptions, types, and auto-generated avatars.

Multi-LLM

OpenAI, Anthropic, Google, Azure, Cohere, HuggingFace, and Ollama support.

Tools & RAG

Built-in tools, document upload, and vector database integration.

The Persona Object

A persona represents an AI agent with specific configuration, behavior, and optional knowledge base.

Full Persona Object

JSON

{
  "id": "clx1abc123xyz789",
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries professionally",
  "type": "CUSTOMER_SERVICE",
  "systemPrompt": "You are a helpful customer support agent...",
  "capabilities": ["Customer Support", "Product Knowledge", "Issue Resolution"],
  "temperature": 0.7,
  "maxTokens": 2000,
  "model": "gpt-4o",
  "llmProvider": "OPENAI",
  "embeddingModel": "text-embedding-3-small",
  "vectorDbProvider": "weaviate",
  "vectorDbConfig": {},
  "systemPromptStructured": {
    "role": "You are a customer support agent",
    "task": "Help users with their questions",
    "context": "You work for AIPersona",
    "reasoning": "Think step by step",
    "output": "Provide clear, helpful responses",
    "stopping": "End conversation when resolved"
  },
  "enabledTools": ["web_search", "calculator", "pdf_processor"],
  "useAgent": true,
  "isPublic": false,
  "avatarUrl": "https://aipersona.dsethiopia.org/avatars/clx1abc123.png",
  "organizationId": "cmdhtumx9000nus412v5qezme",
  "createdById": "user_abc123",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T11:45:00.000Z",
  "_count": {
    "chatSessions": 42
  }
}

Field Descriptions

Field	Type	Description
id	string	Unique CUID identifier
name	string	Display name (required)
type	enum	GENERAL, CUSTOMER_SERVICE, SALES, TECHNICAL, CREATIVE, EDUCATIONAL, CUSTOM
systemPrompt	string	Instructions defining persona behavior (required)
llmProvider	string	OPENAI, ANTHROPIC, GOOGLE, AZURE_OPENAI, COHERE, HUGGINGFACE, OLLAMA
model	string	Model identifier (e.g., gpt-4o, claude-3-sonnet)
temperature	number	Response randomness (0.0-2.0, default 0.7)
maxTokens	number	Max response length (default 2000)
embeddingModel	string	Embedding model for RAG (default: text-embedding-3-small)
vectorDbProvider	string	weaviate, pinecone, chroma, qdrant, milvus
enabledTools	array	List of enabled tool IDs (web_search, calculator, etc.)
useAgent	boolean	Enable Agent Mode for autonomous tool use
isPublic	boolean	Whether persona is publicly accessible

Create a Persona

Create a new AI persona with custom configuration.

POST

trpc.persona.create

Create a new persona in your organization.

Bash

curl -X POST "https://aipersona.dsethiopia.org/api/trpc/persona.create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id" \
  -d '{
    "json": {
      "name": "My Assistant",
      "systemPrompt": "You are a helpful assistant.",
      "type": "GENERAL"
    }
  }'

Response

JSON

{
  "result": {
    "data": {
      "id": "clx1abc123xyz789",
      "name": "Customer Support Agent",
      "description": "Handles customer inquiries professionally",
      "type": "CUSTOMER_SERVICE",
      "model": "gpt-4o",
      "llmProvider": "OPENAI",
      "temperature": 0.7,
      "maxTokens": 2000,
      "isPublic": false,
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  }
}

List Personas

Retrieve all personas in your organization.

GET

trpc.persona.list

List all personas with chat session counts.

Bash

curl -X GET "https://aipersona.dsethiopia.org/api/trpc/persona.list?input=%7B%7D" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id"

Response

JSON

{
  "result": {
    "data": [
      {
        "id": "clx1abc123xyz789",
        "name": "Customer Support Agent",
        "description": "Handles customer inquiries",
        "type": "CUSTOMER_SERVICE",
        "model": "gpt-4o",
        "llmProvider": "OPENAI",
        "isPublic": false,
        "avatarUrl": "https://...",
        "createdAt": "2025-01-15T10:30:00.000Z",
        "_count": {
          "chatSessions": 42
        }
      },
      {
        "id": "clx2def456abc123",
        "name": "Research Assistant",
        "description": "Helps with research tasks",
        "type": "TECHNICAL",
        "model": "claude-3-sonnet",
        "llmProvider": "ANTHROPIC",
        "isPublic": true,
        "_count": {
          "chatSessions": 15
        }
      }
    ]
  }
}

Get a Persona

Retrieve detailed information about a specific persona.

GET

trpc.persona.getById

Get full persona details including configuration.

Bash

curl -X GET "https://aipersona.dsethiopia.org/api/trpc/persona.getById?input=%7B%22id%22%3A%22clx1abc123xyz789%22%7D" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id"

Input Parameters

Parameter	Type	Required	Description
id	string	Yes	The persona ID

Update a Persona

Modify an existing persona's configuration.

POST

trpc.persona.update

Update any persona field. Only provided fields are changed.

Bash

curl -X POST "https://aipersona.dsethiopia.org/api/trpc/persona.update" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id" \
  -d '{
    "json": {
      "id": "clx1abc123xyz789",
      "name": "Senior Support Agent",
      "temperature": 0.6,
      "maxTokens": 3000,
      "enabledTools": ["web_search", "calculator", "pdf_processor", "domain_scraper"]
    }
  }'

Note

Only the fields you include in the request will be updated. Other fields remain unchanged.

Delete a Persona

Permanently remove a persona.

Warning

Deleting a persona is irreversible. Associated chat sessions may become inaccessible.

POST

trpc.persona.delete

Permanently delete a persona.

Bash

curl -X POST "https://aipersona.dsethiopia.org/api/trpc/persona.delete" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id" \
  -d '{
    "json": {
      "id": "clx1abc123xyz789"
    }
  }'

Upload Documents

Add documents to a persona's knowledge base for RAG-powered responses.

POST

trpc.persona.uploadDocuments

Upload PDF, DOCX, DOC, TXT, or MD files to the persona's knowledge base.

JavaScript

// JavaScript example with base64 encoding
const fs = require('fs');

async function uploadDocument(personaId, filePath) {
  const fileBuffer = fs.readFileSync(filePath);
  const base64Content = fileBuffer.toString('base64');
  const filename = filePath.split('/').pop();
  
  // Determine MIME type
  const mimeTypes = {
    '.pdf': 'application/pdf',
    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    '.doc': 'application/msword',
    '.txt': 'text/plain',
    '.md': 'text/markdown'
  };
  const ext = filename.substring(filename.lastIndexOf('.'));
  const mimetype = mimeTypes[ext] || 'application/octet-stream';
  
  const response = await fetch('https://aipersona.dsethiopia.org/api/trpc/persona.uploadDocuments', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.AIPERSONA_API_KEY,
      'X-Organization-ID': process.env.AIPERSONA_ORG_ID,
    },
    body: JSON.stringify({
      json: {
        personaId: personaId,
        files: [{
          filename: filename,
          mimetype: mimetype,
          encoding: 'base64',
          data: base64Content
        }]
      }
    })
  });
  
  return response.json();
}

// Upload a product manual
await uploadDocument('clx1abc123xyz789', './product-manual.pdf');

Supported File Types

PDF

application/pdf

DOCX

Word documents

DOC

Legacy Word

TXT

Plain text

Markdown

Tool Configuration

Enable built-in tools to give your persona additional capabilities.

Available Built-in Tools

Web Search

web_search

Search the web for current information, news, and facts.

Calculator

calculator

Perform mathematical calculations and conversions.

Domain Scraper

domain_scraper

Extract text content from websites and web pages.

PDF Processor

pdf_processor

Extract, search, summarize, and analyze PDF documents.

Enabling Tools

JSON

{
  "json": {
    "id": "clx1abc123xyz789",
    "enabledTools": ["web_search", "calculator", "pdf_processor"],
    "useAgent": true
  }
}

Tip

Enable useAgent: true to allow the persona to autonomously decide when to use tools based on the conversation context.

List Available Tools

Bash

curl -X GET "https://aipersona.dsethiopia.org/api/trpc/tools.list?input=%7B%7D" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id"