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	ASSISTANT, SPECIALIST, COMPANION, CUSTOMER_SERVICE, SALES, CREATIVE
systemPrompt	string	Instructions defining persona behavior (required)
llmProvider	string	OPENAI, ANTHROPIC, GOOGLE, AZURE_OPENAI, COHERE, HUGGINGFACE, OLLAMA, CUSTOM
model	string	Model identifier (e.g., gpt-4o, claude-sonnet-4-6, gemini-2.5-pro)
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": "ASSISTANT"
    }
  }'

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": "SPECIALIST",
        "model": "claude-sonnet-4-6",
        "llmProvider": "ANTHROPIC",
        "isPublic": true,
        "_count": {
          "chatSessions": 15
        }
      }
    ]
  }
}

Get a Persona

Retrieve detailed information about a specific persona.

GET

trpc.persona.get

Get full persona details including configuration.

Bash

curl -X GET "https://aipersona.dsethiopia.org/api/trpc/persona.get?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

Knowledge Base Management

Manage documents in a persona's knowledge base for RAG-powered responses. The edit page provides a rich document list with metadata, the ability to remove documents, and duplicate detection.

Warning

The vector database uses text2vec-openai for embeddings. An OpenAI API key must be connected in your LLM provider settings for document indexing and RAG retrieval to work, regardless of which LLM provider the persona uses for chat.

Google Drive Folder Selection

In addition to direct file uploads, users can browse and select entire Google Drive folders to import into a persona's knowledge base. Documents are fetched, processed, and indexed automatically.

JSON

// Google Drive folder import is available in the dashboard UI.
// The API equivalent uses the Google Docs integration endpoints:
// POST trpc.integrations.importGoogleDriveFolder
{
  "json": {
    "personaId": "clx1abc123xyz789",
    "folderId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2wtTs"
  }
}

Document Metadata

Each document in the knowledge base includes metadata such as filename, file size, upload date, and source type. Duplicate documents are detected by content hash and flagged during upload.

JSON

{
  "id": "doc_abc123",
  "filename": "product-manual.pdf",
  "mimetype": "application/pdf",
  "size": 245760,
  "source": "upload",
  "personaId": "clx1abc123xyz789",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Supported Models

Each LLM provider offers a selection of models. Specify the model and llmProvider fields when creating or updating a persona.

OpenAI

gpt-5.2-pro

gpt-5.1

gpt-5

o4-mini

o3-mini

o1-mini

o1-pro

gpt-4.1

gpt-4.1-mini

gpt-4.1-nano

gpt-4o

gpt-4o-mini

gpt-4-turbo

gpt-3.5-turbo

Anthropic

claude-opus-4-6

claude-sonnet-4-6

claude-opus-4-5

claude-sonnet-4-5

claude-sonnet-4-0

claude-3-7-sonnet

claude-3-5-sonnet

claude-3-5-haiku

claude-3-opus

claude-3-haiku

Google Gemini

gemini-2.5-pro

gemini-2.5-flash

gemini-2.0-flash

gemini-2.0-flash-lite

gemini-1.5-pro

gemini-1.5-flash

Cohere

command-a

command-r-plus

command-r

command-r7b

command

command-light

Note

Azure OpenAI, Hugging Face, and Ollama are also supported. Azure OpenAI uses the same model names as OpenAI but requires a custom base URL. Hugging Face and Ollama support user-defined custom models.

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"