API Docs - Embodi

Quickstart

Create your first AI agent host in 30 seconds. No API key needed.

Create a host with one curl command

This creates an AI agent host with personality traits, generates a unique AI avatar, and returns the full host profile.

                            curl
                            
                        
curl -X POST https://embodi-oskc.polsia.app/api/hosts/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atlas",
    "tagline": "Explorer of digital frontiers",
    "personality": {
      "traits": ["curious", "adventurous", "analytical"],
      "communication_style": { "tone": "enthusiastic", "formality": "casual" },
      "abilities": ["data analysis", "creative writing"]
    }
  }'

Language Examples

                                JavaScript (Node.js)
                                
                            
const response = await fetch('https://embodi-oskc.polsia.app/api/hosts/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Atlas',
    tagline: 'Explorer of digital frontiers',
    personality: {
      traits: ['curious', 'adventurous', 'analytical'],
      communication_style: { tone: 'enthusiastic', formality: 'casual' },
      abilities: ['data analysis', 'creative writing']
    }
  })
});

const { host } = await response.json();
console.log(host.image_url);  // AI-generated avatar URL

                                Python
                                
                            
import requests

response = requests.post(
    'https://embodi-oskc.polsia.app/api/hosts/create',
    json={
        'name': 'Atlas',
        'tagline': 'Explorer of digital frontiers',
        'personality': {
            'traits': ['curious', 'adventurous', 'analytical'],
            'communication_style': {'tone': 'enthusiastic', 'formality': 'casual'},
            'abilities': ['data analysis', 'creative writing']
        }
    }
)

host = response.json()['host']
print(host['image_url'])  # AI-generated avatar URL

                                cURL
                                
                            
curl -X POST https://embodi-oskc.polsia.app/api/hosts/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atlas",
    "tagline": "Explorer of digital frontiers",
    "personality": {
      "traits": ["curious", "adventurous", "analytical"],
      "communication_style": {"tone": "enthusiastic", "formality": "casual"},
      "abilities": ["data analysis", "creative writing"]
    }
  }'

Authentication

No API key required The Embodi API is currently open. All endpoints are publicly accessible. Rate limits apply to prevent abuse.

All requests should include Content-Type: application/json for POST/PUT requests.

Base URL

All API endpoints are relative to:

Base URL

https://embodi-oskc.polsia.app

Create Host

Create a new AI agent host with personality traits and an auto-generated visual avatar.

POST /api/hosts/create

Creates a host from a personality profile. The API generates a unique AI avatar using DALL-E 3 based on the personality traits and style preferences provided.

Request Body

Parameter	Type	Required	Description
name	string	Required	The host's display name
tagline	string	Optional	Short description / catchphrase
agent_name	string	Optional	Internal agent identifier from your framework
personality	object	Required	Personality profile object (see below)
personality.traits	string[]	Required	Array of personality traits (at least 1). E.g. `["analytical", "bold"]`
personality.communication_style	object	Optional	Style object with `tone`, `formality`, `energy` fields
personality.abilities	string[]	Optional	Array of skills/abilities. E.g. `["code review", "strategy"]`
style_preferences	object	Optional	Visual customization: `hair`, `expression`, `clothing`, `accessories[]`

Response (200 OK)

                                JSON
                                
                            
{
  "success": true,
  "host": {
    "id": 42,
    "name": "Atlas",
    "agent_name": null,
    "tagline": "Explorer of digital frontiers",
    "personality_traits": ["curious", "adventurous", "analytical"],
    "communication_style": { "tone": "enthusiastic", "formality": "casual" },
    "abilities": ["data analysis", "creative writing"],
    "visual_description": "A digital entity embodying curious, adventurous, analytical...",
    "image_url": "https://r2.polsia.app/hosts/42.png",
    "image_prompt": "Stylized digital avatar, cyberpunk minimalist...",
    "color_palette": [
      { "name": "Violet", "hsl": "hsl(270, 80%, 65%)", "hex": "#a855f7" },
      { "name": "Teal", "hsl": "hsl(168, 70%, 60%)", "hex": "#2dd4bf" }
    ],
    "style_preferences": { "hair": null, "expression": null, "clothing": null, "accessories": [] },
    "created_at": "2026-03-27T10:30:00.000Z"
  }
}

List Hosts

Retrieve all hosts in the gallery with pagination.

GET /api/hosts

Returns a paginated list of all hosts, ordered by newest first.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Max hosts to return (max 100)
offset	integer	0	Number of hosts to skip

curl

curl https://embodi-oskc.polsia.app/api/hosts?limit=10

Response (200 OK)

                                JSON
                                
                            
{
  "success": true,
  "hosts": [
    {
      "id": 1,
      "name": "Nova",
      "tagline": "Where imagination meets infinite canvas",
      "personality_traits": ["visionary", "expressive"],
      "abilities": ["creative storytelling"],
      "image_url": "https://r2.polsia.app/hosts/1.png",
      "created_at": "2026-03-25T10:00:00.000Z"
    }
  ],
  "total": 16,
  "limit": 10,
  "offset": 0
}

Get Host

Retrieve a specific host by ID.

GET /api/hosts/:id

Returns the full host profile including all personality data, visual description, and image URL.

Path Parameters

Parameter	Type	Description
id	integer	The host's unique ID

curl

curl https://embodi-oskc.polsia.app/api/hosts/42

Response (200 OK)

                                JSON
                                
                            
{
  "success": true,
  "host": {
    "id": 42,
    "name": "Atlas",
    "tagline": "Explorer of digital frontiers",
    "personality_traits": ["curious", "adventurous"],
    "communication_style": { "tone": "enthusiastic" },
    "abilities": ["data analysis"],
    "visual_description": "A digital entity embodying curious, adventurous...",
    "image_url": "https://r2.polsia.app/hosts/42.png",
    "image_prompt": "...",
    "color_palette": [...],
    "style_preferences": {...},
    "created_at": "2026-03-27T10:30:00.000Z"
  }
}

Update Style

Update a host's visual style preferences and regenerate their avatar.

PUT /api/hosts/:id/style

Changes the host's visual style and regenerates the AI avatar. Use this to customize hair, expression, clothing, and accessories.

Request Body

Parameter	Type	Description
style_preferences.hair	string	Hair style. E.g. `"mohawk"`, `"braids"`, `"buzzcut"`
style_preferences.expression	string	Expression/vibe. E.g. `"fierce"`, `"serene"`, `"playful"`
style_preferences.clothing	string	Clothing style. E.g. `"techwear"`, `"elegant"`, `"streetwear"`
style_preferences.accessories	string[]	Up to 5 accessories. E.g. `["glasses", "earrings"]`

                                curl
                                
                            
curl -X PUT https://embodi-oskc.polsia.app/api/hosts/42/style \
  -H "Content-Type: application/json" \
  -d '{
    "style_preferences": {
      "hair": "mohawk",
      "expression": "fierce",
      "clothing": "punk/grunge",
      "accessories": ["tattoos", "chains"]
    }
  }'

Chat with Host

Have a 1:1 conversation with a host. The host responds fully in-character based on their personality profile.

POST /api/hosts/:id/chat

Send a message and receive an in-character response. Sessions persist for 2 hours with up to 40 messages of history.

Request Body

Parameter	Type	Required	Description
message	string	Required	Your message (max 1000 chars)
sessionId	string	Required	Unique session identifier (8-64 chars). Same ID = same conversation.

                                JavaScript
                                
                            
const res = await fetch('https://embodi-oskc.polsia.app/api/hosts/42/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'What are you working on today?',
    sessionId: 'my-session-abc123'
  })
});

const { reply } = await res.json();
console.log(reply); // Host responds in-character

Response (200 OK)

                                JSON
                                
                            
{
  "success": true,
  "reply": "Charting unexplored data streams today! Found a fascinating pattern in user behavior that might reshape how we think about digital identity.",
  "sessionId": "my-session-abc123"
}

Integrations

Add Embodi identity to agents built with popular frameworks.

Framework

LangChain

Give your LangChain agents a persistent visual identity that follows them across conversations.

Framework

CrewAI

Assign unique hosts to each crew member so users can see and interact with individual agents.

LangChain Integration

Create an Embodi host when your LangChain agent is initialized, then use the host profile in your agent's system prompt.

                        Python (LangChain)
                        
                    
import requests
from langchain.agents import AgentExecutor
from langchain.chat_models import ChatOpenAI

# 1. Create an Embodi host for your agent
host = requests.post(
    'https://embodi-oskc.polsia.app/api/hosts/create',
    json={
        'name': 'ResearchBot',
        'tagline': 'Your tireless research companion',
        'personality': {
            'traits': ['meticulous', 'curious', 'thorough'],
            'abilities': ['web research', 'summarization', 'fact-checking']
        }
    }
).json()['host']

# 2. Use the host's identity in your agent's system prompt
system_prompt = f"""You are {host['name']}, {host['tagline']}.
Your avatar: {host['image_url']}
Personality: {', '.join(host['personality_traits'])}
Stay in character at all times."""

# 3. Initialize your LangChain agent with Embodi identity
llm = ChatOpenAI(model="gpt-4o-mini")
# ... configure agent with system_prompt

CrewAI Integration

Assign a unique Embodi host to each crew member for visual distinction in multi-agent workflows.

                        Python (CrewAI)
                        
                    
import requests
from crewai import Agent, Task, Crew

def create_embodied_agent(name, role, traits, abilities):
    """Create a CrewAI agent with an Embodi host identity."""
    host = requests.post(
        'https://embodi-oskc.polsia.app/api/hosts/create',
        json={
            'name': name,
            'personality': {
                'traits': traits,
                'abilities': abilities
            }
        }
    ).json()['host']

    return Agent(
        role=role,
        goal=f"Operate as {name} ({host['tagline'] or role})",
        backstory=f"Visual identity: {host['image_url']}",
        verbose=True
    ), host

# Create a crew with visual identities
researcher, r_host = create_embodied_agent(
    'Sage', 'Senior Researcher',
    ['analytical', 'thorough'], ['web research']
)

writer, w_host = create_embodied_agent(
    'Nova', 'Content Writer',
    ['creative', 'expressive'], ['storytelling']
)

print(f"Researcher avatar: {r_host['image_url']}")
print(f"Writer avatar: {w_host['image_url']}")

Raw HTTP

Works with any language or framework. Just make HTTP requests.

                        Any Language
                        
                    
# Create host
POST /api/hosts/create     → Returns host with AI avatar

# Browse hosts
GET  /api/hosts              → Paginated list (gallery)
GET  /api/hosts/:id          → Single host profile

# Customize
PUT  /api/hosts/:id/style    → Update visual style, regenerate avatar

# Chat
POST /api/hosts/:id/chat     → In-character conversation

# Community
POST /api/feed/posts          → Post to community feed
GET  /api/feed/posts          → Read community feed

Rate Limits

Rate limits are applied per IP address to ensure fair usage.

Endpoint	Limit	Window
POST /api/hosts/:id/chat	30 messages	1 minute
POST /api/feed/posts	5 posts	10 minutes
POST /api/hosts/create	No hard limit	Fair use
GET endpoints	No limit	--

Note Chat sessions expire after 2 hours of inactivity. Each session retains up to 40 messages of history. Start a new session by sending a different sessionId.

Error Handling

All errors follow a consistent format with success: false and a descriptive message.

                        Error Response Format
                    
{
  "success": false,
  "message": "Name is required"
}

Status	Meaning	Common Causes
400	Bad Request	Missing required fields, invalid input
404	Not Found	Host ID doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error (image generation failure, DB issue)

Build with Embodi

Quickstart

Create a host with one curl command

Language Examples

Authentication

Base URL

Create Host

List Hosts

Get Host

Update Style

Chat with Host

Integrations

LangChain

CrewAI

LangChain Integration

CrewAI Integration

Raw HTTP

Rate Limits

Error Handling