Quick StartAPI Reference

Creating Users

Users represent the real people chatting with your bots. Each user has a unique identifier, username, and optional personality information that helps the AI tailor conversations to them.

Overview

A user is defined by:

  • ID (required): Your unique identifier for this user
  • Username (optional): The user's display name
  • Freeform (optional): Detailed personality description
  • Attributes (optional): Key-value pairs for specific characteristics (like "Bio", "Age", "Location", etc.)

Only the ID is required. The username, freeform, and attributes are completely optional - but providing them gives the bot awareness of who the user is so it can reference their interests, ask relevant questions, and personalize the conversation.

Creating Users Through the API

Minimal Request

At minimum, you only need to provide an ID:

POST /api/users
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "id": "user_12345"
}

Full Request

But providing additional context improves conversation quality:

POST /api/users
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "id": "user_12345",
  "username": "Jake_Thompson",
  "freeform": "Active gym-goer interested in fitness and outdoor activities",
  "attributes": [
    {"name": "Name", "value": "Jake Thompson"},
    {"name": "Bio", "value": "Fitness enthusiast who loves the outdoors"},
    {"name": "Age", "value": "32"},
    {"name": "Location", "value": "Denver, CO"},
    {"name": "Occupation", "value": "Personal Trainer"}
  ]
}

Response 

{
  "user": {
    "id": "user_12345",
    "username": "Jake_Thompson",
    "freeform": "Active gym-goer interested in fitness and outdoor activities",
    "attributes": [
      { "name": "name", "value": "Jake Thompson" },
      { "name": "bio", "value": "Fitness enthusiast who loves the outdoors" },
      { "name": "age", "value": "32" },
      { "name": "location", "value": "Denver, CO" },
      { "name": "occupation", "value": "Personal Trainer" }
    ]
  }
}

Auto-Creating Users

You don't always need to explicitly create users. When creating a conversation or sending a message, you can set create_user_if_not_exists: true to automatically create the user if they don't exist yet.

POST /api/conversations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "bot_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user_12345",
  "create_user_if_not_exists": true
}

If user_12345 doesn't exist, it will be created automatically with just the ID. You can optionally update the user later with username, freeform, and attributes if you want better personalization.

Note: The create_user_if_not_exists parameter defaults to true for /api/conversations and false for /api/add-message.

Field Descriptions

ID (Required)

Your unique identifier for this user. This is how you'll reference the user when creating conversations.

Important: Unlike bots, you provide the user ID yourself. This lets you map to your existing user IDs. This is the only required field.

{
  "id": "user_12345"
}

Username (Optional)

The user's display name or username. Completely optional.

{
  "username": "Jake_Thompson"
}

Freeform (Optional)

Description of the user's personality, interests, background, and communication style.

Examples:

{
  "freeform": "Outgoing and athletic. Recently got into CrossFit and loves talking about fitness. Works as a personal trainer. Direct communicator who appreciates straightforward conversations."
}

{
  "freeform": "Tech enthusiast who works in software. Introverted but warms up over text. Enjoys deep conversations about AI, gaming, and science fiction."
}

Attributes (Optional)

Key-value pairs for specific characteristics. The AI can understand and reference any attributes you provide.

Common attributes (depends on your site):

{
  "attributes": [
    { "name": "Name", "value": "Jake Thompson" },
    {
      "name": "Bio",
      "value": "Fitness enthusiast and personal trainer. Love the outdoors!"
    },
    { "name": "Age", "value": "32" },
    { "name": "Location", "value": "Denver, CO" },
    { "name": "Occupation", "value": "Personal Trainer" },
    { "name": "Interests", "value": "CrossFit, hiking, meal prep, podcasts" },
    { "name": "Height", "value": "6'0" },
    { "name": "Education", "value": "BS in Kinesiology" }
  ]
}

Recommended attributes:

  • Name - User's full name
  • Bio - Short bio or description (e.g., "I'm a big traveler, been to 30 countries")
  • Age - User's age
  • Location - City/state where they live
  • Occupation - What they do for work
  • Interests - Hobbies and interests
  • Education - Educational background
  • Height, Build, Appearance - Physical characteristics (if relevant for your platform)

The specific attributes you include depend on your site and what information you have about users.

Freeform vs Attributes

It doesn't hugely matter which you use. Generally use freeform for longer descriptions and personality traits, attributes for shorter factual details. But the AI understands both and will interpret the information appropriately regardless.

Why Provide User Context?

Username, freeform, and attributes are completely optional. You can create users with just an ID if that's all you have. But providing personality information gives the bot awareness of who the user is, allowing it to reference their details naturally in conversation.

The Bot Can Reference User Attributes

The bot can see the user's attributes and reference them naturally.

Example - User has attribute {"name": "Bio", "value": "I'm a big traveler"}:

Bot: "I see you like to travel! What's your favorite spot you've been to?"
User: "Probably Thailand"
Bot: "Oh nice! I've always wanted to go there. What did you love about it?"

Example - User has attribute {"name": "Occupation", "value": "Software Engineer"}:

Bot: "How was your day?"
User: "Exhausting, lots of meetings"
Bot: "Ugh I bet, especially in tech. Did you get any actual coding done? 😅"

The Bot Knows User Details

User attributes help the bot ask relevant questions and make natural references.

Example - User has {"name": "Location", "value": "Seattle"}:

Bot: "I'm thinking about visiting the Pacific Northwest soon"
User: "Oh nice when?"
Bot: "Maybe this summer. You're in Seattle right? Any must-see spots?"

Example - User has {"name": "Age", "value": "32"} and {"name": "Interests", "value": "CrossFit, hiking"}:

Bot: "What are you up to this weekend?"
User: "Not sure yet"
Bot: "Any good hikes near you? Or hitting the gym?"

Better Conversation Flow

When the bot knows about the user, conversations feel more natural and personalized.

Example - User has {"name": "Bio", "value": "Love trying new restaurants"}:

Bot: "Just tried this amazing Italian place downtown"
User: "Ooh which one?"
Bot: "Bella Vista. You'd probably love it actually, I know you're into trying new spots"

Complete Example 

import requests

API_KEY = "sk_yourapikey"
BASE_URL = "https://api.prioros.com/v3"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Minimal example - just an ID
user_response = requests.post(
    f"{BASE_URL}/api/users",
    headers=headers,
    json={
        "id": "user_minimal123"
    }
)

# Full example - with optional context for better conversations
user_response = requests.post(
    f"{BASE_URL}/api/users",
    headers=headers,
    json={
        "id": "user_jake123",
        "username": "Jake_Thompson",
        "freeform": "Active gym-goer who recently got into CrossFit. Works as a personal trainer and loves talking about fitness and nutrition. Direct communicator who appreciates authenticity.",
        "attributes": [
            {"name": "Name", "value": "Jake Thompson"},
            {"name": "Bio", "value": "Fitness lover and personal trainer. Always down for a hike!"},
            {"name": "Age", "value": "32"},
            {"name": "Location", "value": "Denver, CO"},
            {"name": "Occupation", "value": "Personal Trainer"},
            {"name": "Interests", "value": "CrossFit, hiking, meal prep, fitness podcasts"}
        ]
    }
)

user = user_response.json()['user']
print(f"Created user: {user['id']}")

Managing Users

List All Users 

GET /api/users
Authorization: Bearer YOUR_API_KEY

Returns all users in your account.

Get a Specific User 

GET /api/users/{user_id}
Authorization: Bearer YOUR_API_KEY

Adding Images to Users

Users can have public images that are displayed on their profile. These images give the bot visual context about what the user looks like, which helps the bot make more personalized and realistic responses.

Why it's needed: The bot can see and reference user photos in conversation, making interactions more natural.

Example:

Bot: "You look great in that beach photo on your profile! Do you travel a lot?"
User: "Yeah I love the beach"
Bot: "I can tell! That sunset pic was amazing"

See the Public Images guide for details on uploading and managing user images.

Example Users

Mike 

{
  "id": "user_mike456",
  "username": "MikeR_32",
  "freeform": "Laid-back and easygoing. Works in tech but doesn't let it define him. Loves craft beer, sports, and hanging out with friends.",
  "attributes": [
    { "name": "Name", "value": "Mike Rodriguez" },
    { "name": "Bio", "value": "Tech guy who loves sports and craft beer" },
    { "name": "Age", "value": "32" },
    { "name": "Location", "value": "Austin, TX" },
    { "name": "Occupation", "value": "Software Developer" },
    { "name": "Interests", "value": "craft beer, basketball, gaming" }
  ]
}

David 

{
  "id": "user_david789",
  "username": "DavidChen",
  "freeform": "Ambitious and career-focused. Enjoys working out and staying fit. Appreciates intelligence and wit.",
  "attributes": [
    { "name": "Name", "value": "David Chen" },
    {
      "name": "Bio",
      "value": "Finance professional who's all about fitness and travel"
    },
    { "name": "Age", "value": "29" },
    { "name": "Location", "value": "New York, NY" },
    { "name": "Occupation", "value": "Financial Analyst" },
    { "name": "Interests", "value": "gym, business books, traveling" }
  ]
}

Alex 

{
  "id": "user_alex321",
  "username": "AlexJ",
  "freeform": "Creative type who works in advertising. Loves art, music, and good conversation. A bit introverted but opens up about passions.",
  "attributes": [
    { "name": "Name", "value": "Alex Johnson" },
    {
      "name": "Bio",
      "value": "Creative director with a passion for art and indie music"
    },
    { "name": "Age", "value": "27" },
    { "name": "Location", "value": "Portland, OR" },
    { "name": "Occupation", "value": "Creative Director" },
    { "name": "Interests", "value": "indie music, street art, photography" }
  ]
}

Marcus 

{
  "id": "user_marcus555",
  "username": "MarcusWilliams",
  "freeform": "Outgoing and social. Works in sales and is naturally charismatic. Loves trying new restaurants and exploring the city.",
  "attributes": [
    { "name": "Name", "value": "Marcus Williams" },
    { "name": "Bio", "value": "I'm a big foodie and love exploring the city" },
    { "name": "Age", "value": "30" },
    { "name": "Location", "value": "Chicago, IL" },
    { "name": "Occupation", "value": "Sales Manager" },
    {
      "name": "Interests",
      "value": "trying new restaurants, basketball, traveling"
    }
  ]
}