Getting Started with the Partner API

This guide walks you through submitting your first topic and understanding how commentary generation works.

Prerequisites: You need a Partner account with at least one licensed persona. Don’t have one? Contact sales.

Human-in-the-Loop Quality: Unleeshed generates authentic, high-fidelity commentary through a human-in-the-loop workflow. Creators inject their real perspective before AI generates. This ensures genuine responses but means commentary typically arrives within hours, not seconds.

Step 1: Get Your API Key

Log into Partner Dashboard

Go to app.unleeshed.ai/partner and sign in.

Navigate to API Keys

Click Developer → API Keys in the sidebar.

Create a New Key

Click Create API Key, name it “Quickstart Test”, and select these scopes:

personas:read
topics:submit
topics:read

Copy Your Key

Copy the key immediately — it’s only shown once!

pk_live_abc123...

Store your API key securely. Never expose it in client-side code.

Step 2: Find Your Personas

Let’s see which personas you have access to.

curl -X GET "https://prod.api.unleeshed.ai/partner/v1/personas" \
  -H "X-Api-Key: YOUR_API_KEY"

const response = await fetch('https://prod.api.unleeshed.ai/partner/v1/personas', {
  headers: { 'X-Api-Key': process.env.UNLEESHED_API_KEY }
});

const { data: personas } = await response.json();

console.log('Your licensed personas:');
personas.forEach(p => console.log(`- ${p.name} (${p.id})`));

import requests
import os

response = requests.get(
    "https://prod.api.unleeshed.ai/partner/v1/personas",
    headers={"X-Api-Key": os.environ["UNLEESHED_API_KEY"]}
)

personas = response.json()["data"]

print("Your licensed personas:")
for p in personas:
    print(f"- {p['name']} ({p['id']})")

Response:

{
  "success": true,
  "data": [
    { "id": "pers_abc123", "name": "Coach Mike", "image_url": "https://..." },
    { "id": "pers_xyz789", "name": "Analytics Amy", "image_url": "https://..." }
  ]
}

Save those persona IDs — you’ll need them in the next step.

Step 3: Create a Topic

Now let’s submit a topic for commentary. Pick a hot sports topic (max 100 characters) and send it to your personas.

curl -X POST "https://prod.api.unleeshed.ai/partner/v1/topics" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Should the Lakers trade Anthony Davis before the deadline?",
    "persona_ids": ["pers_abc123", "pers_xyz789"],
    "output_types": ["text"]
  }'

const response = await fetch('https://prod.api.unleeshed.ai/partner/v1/topics', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.UNLEESHED_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: "Should the Lakers trade Anthony Davis before the deadline?",
    persona_ids: ["pers_abc123", "pers_xyz789"],
    output_types: ["text"]
  })
});

const { data } = await response.json();
console.log(`Topic created: ${data.topic_id}`);
console.log(`Personas generating: ${data.personas_sent}`);

import requests

response = requests.post(
    "https://prod.api.unleeshed.ai/partner/v1/topics",
    headers={
        "X-Api-Key": os.environ["UNLEESHED_API_KEY"],
        "Content-Type": "application/json"
    },
    json={
        "content": "Should the Lakers trade Anthony Davis before the deadline?",
        "persona_ids": ["pers_abc123", "pers_xyz789"],
        "output_types": ["text"]
    }
)

data = response.json()["data"]
print(f"Topic created: {data['topic_id']}")
print(f"Personas generating: {data['personas_sent']}")

Response:

{
  "success": true,
  "data": {
    "topic_id": "top_98765",
    "personas_sent": 2,
    "status": "pending"
  }
}

Save the topic_id — you need it to fetch the commentaries.

Step 4: Check Status

Since commentary involves human creators, it takes time. Use the status endpoint to monitor progress.

# Check status - poll periodically until ready
curl -X GET "https://prod.api.unleeshed.ai/partner/v1/topics/top_98765/status" \
  -H "X-Api-Key: YOUR_API_KEY"

async function checkStatus(topicId) {
  const response = await fetch(
    `https://prod.api.unleeshed.ai/partner/v1/topics/${topicId}/status`,
    { headers: { 'X-Api-Key': process.env.UNLEESHED_API_KEY } }
  );
  
  const { data } = await response.json();
  
  console.log(`Overall: ${data.overall_status}`);
  console.log(`Ready: ${data.summary.creator_approved}/${data.summary.total}`);
  
  data.personas.forEach(p => {
    console.log(`  ${p.persona_name}: ${p.status}`);
  });
  
  return data;
}

const status = await checkStatus('top_98765');

def check_status(topic_id):
    response = requests.get(
        f"https://prod.api.unleeshed.ai/partner/v1/topics/{topic_id}/status",
        headers={"X-Api-Key": os.environ["UNLEESHED_API_KEY"]}
    )
    
    data = response.json()["data"]
    
    print(f"Overall: {data['overall_status']}")
    print(f"Ready: {data['summary']['creator_approved']}/{data['summary']['total']}")
    
    for p in data["personas"]:
        print(f"  {p['persona_name']}: {p['status']}")
    
    return data

status = check_status("top_98765")

Example output:

Overall: partial
Ready: 1/2
  Coach Mike: creator_approved
  Analytics Amy: opinion_injected

Timeline: Creators typically respond within 30 minutes to a few hours. Set up periodic polling (every 1-5 minutes) or use webhooks in production.

Step 5: Fetch the Commentary

Once overall_status is partial or completed, fetch the ready commentaries:

curl -X GET "https://prod.api.unleeshed.ai/partner/v1/topics/top_98765/commentaries" \
  -H "X-Api-Key: YOUR_API_KEY"

const response = await fetch(
  `https://prod.api.unleeshed.ai/partner/v1/topics/top_98765/commentaries`,
  { headers: { 'X-Api-Key': process.env.UNLEESHED_API_KEY } }
);

const { data } = await response.json();

console.log(`\nTopic: ${data.content}\n`);

data.commentaries.forEach(c => {
  console.log(`--- ${c.persona.name} ---`);
  console.log(c.content);
  console.log('');
});

response = requests.get(
    f"https://prod.api.unleeshed.ai/partner/v1/topics/top_98765/commentaries",
    headers={"X-Api-Key": os.environ["UNLEESHED_API_KEY"]}
)

data = response.json()["data"]

print(f"\nTopic: {data['content']}\n")

for c in data["commentaries"]:
    print(f"--- {c['persona']['name']} ---")
    print(c["content"])
    print()

The Result:

Topic: Should the Lakers trade Anthony Davis before the deadline?

--- Coach Mike ---
Look, I've been in locker rooms for 30 years, and I can tell you — 
chemistry matters. AD is still one of the most talented big men in 
the game when he's healthy. But that's the thing, isn't it? "When 
he's healthy." You're talking about a franchise that's been to the 
Finals, won a championship with this core. But at some point, you 
gotta ask yourself: are we building around a player or building 
around a medical report?

--- Analytics Amy ---
Let's look at the numbers. Davis has played in just 56% of possible 
games over the past three seasons. However, when active, his impact 
metrics remain elite — top-5 in defensive win shares, +4.2 net rating. 
The question isn't whether AD is good, it's probability-weighted 
value. If you trade him, what's the expected return? Most models 
suggest the Lakers would be selling at a significant discount given 
his injury history and contract.

You’re Set Up!

You’ve completed the integration basics:

Created an API key

With the right scopes for commentary generation

Retrieved your licensed personas

So you know who can generate commentary

Submitted a topic

And selected which personas should respond

Learned to check status

Monitor the human-in-the-loop workflow

Fetched the results

Unique, high-fidelity commentary from each persona

Production Tip: For production integrations, consider implementing webhook callbacks instead of polling. Contact api@unleeshed.ai to discuss webhook setup.

What’s Next?

Display Best Practices

Learn how to beautifully present commentaries in your UI.

Error Handling

Build robust integrations that handle edge cases.

Core Concepts

Deep dive into personas, licensing, and fidelity.

Full API Reference

Explore all available endpoints.

Complete Working Example

Here’s a full integration example using the status endpoint:

const API_KEY = process.env.UNLEESHED_API_KEY;
const BASE_URL = 'https://prod.api.unleeshed.ai/partner/v1';

async function submitTopic(topic) {
  // 1. Get personas
  const personasRes = await fetch(`${BASE_URL}/personas`, {
    headers: { 'X-Api-Key': API_KEY }
  });
  const { data: personas } = await personasRes.json();
  
  console.log(`Found ${personas.length} licensed personas`);
  
  // 2. Create topic (max 100 characters)
  const topicRes = await fetch(`${BASE_URL}/topics`, {
    method: 'POST',
    headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      content: topic,
      persona_ids: personas.map(p => p.id),
      output_types: ['text']
    })
  });
  const { data: topicData } = await topicRes.json();
  
  console.log(`Topic created: ${topicData.topic_id}`);
  return topicData.topic_id;
}

async function checkTopicStatus(topicId) {
  // Use lightweight status endpoint for polling
  const statusRes = await fetch(`${BASE_URL}/topics/${topicId}/status`, {
    headers: { 'X-Api-Key': API_KEY }
  });
  const { data: status } = await statusRes.json();
  
  console.log(`Status: ${status.overall_status}`);
  console.log(`Ready: ${status.summary.creator_approved}/${status.summary.total}`);
  
  status.personas.forEach(p => {
    console.log(`  ${p.persona_name}: ${p.status}`);
  });
  
  return status;
}

async function getCommentaries(topicId) {
  const commRes = await fetch(`${BASE_URL}/topics/${topicId}/commentaries`, {
    headers: { 'X-Api-Key': API_KEY }
  });
  const { data: result } = await commRes.json();
  return result.commentaries;
}

// Usage example
const topicId = await submitTopic("Should the Lakers trade AD?");

// Check status periodically (in production, use webhooks or scheduled jobs)
const status = await checkTopicStatus(topicId);

// When status.overall_status is 'partial' or 'completed', fetch commentaries
if (status.overall_status === 'partial' || status.overall_status === 'completed') {
  const commentaries = await getCommentaries(topicId);
  commentaries.forEach(c => {
    console.log(`\n${c.persona.name}:\n${c.content}`);
  });
}

import os
import requests

API_KEY = os.environ["UNLEESHED_API_KEY"]
BASE_URL = "https://prod.api.unleeshed.ai/partner/v1"

def submit_topic(topic):
    headers = {"X-Api-Key": API_KEY}
    
    # 1. Get personas
    personas = requests.get(f"{BASE_URL}/personas", headers=headers).json()["data"]
    print(f"Found {len(personas)} licensed personas")
    
    # 2. Create topic (max 100 characters)
    topic_data = requests.post(
        f"{BASE_URL}/topics",
        headers={**headers, "Content-Type": "application/json"},
        json={
            "content": topic,
            "persona_ids": [p["id"] for p in personas],
            "output_types": ["text"]
        }
    ).json()["data"]
    
    print(f"Topic created: {topic_data['topic_id']}")
    return topic_data["topic_id"]

def check_topic_status(topic_id):
    # Use lightweight status endpoint for polling
    status = requests.get(
        f"{BASE_URL}/topics/{topic_id}/status", 
        headers={"X-Api-Key": API_KEY}
    ).json()["data"]
    
    print(f"Status: {status['overall_status']}")
    print(f"Ready: {status['summary']['creator_approved']}/{status['summary']['total']}")
    
    for p in status["personas"]:
        print(f"  {p['persona_name']}: {p['status']}")
    
    return status

def get_commentaries(topic_id):
    result = requests.get(
        f"{BASE_URL}/topics/{topic_id}/commentaries",
        headers={"X-Api-Key": API_KEY}
    ).json()["data"]
    return result["commentaries"]

# Usage example
if __name__ == "__main__":
    topic_id = submit_topic("Should the Lakers trade AD?")
    
    # Check status periodically (in production, use webhooks or scheduled jobs)
    status = check_topic_status(topic_id)
    
    # When status is 'partial' or 'completed', fetch commentaries
    if status["overall_status"] in ["partial", "completed"]:
        commentaries = get_commentaries(topic_id)
        for c in commentaries:
            print(f"\n{c['persona']['name']}:\n{c['content']}")

Get Started

Core Concepts

Guides

Resources

Step 1: Get Your API Key

Step 2: Find Your Personas

Step 3: Create a Topic

Step 4: Check Status

Step 5: Fetch the Commentary

You’re Set Up!

What’s Next?

Display Best Practices

Error Handling

Core Concepts

Full API Reference

Complete Working Example

​Step 1: Get Your API Key

​Step 2: Find Your Personas

​Step 3: Create a Topic

​Step 4: Check Status

​Step 5: Fetch the Commentary

​You’re Set Up!

​What’s Next?

Display Best Practices

Error Handling

Core Concepts

Full API Reference

​Complete Working Example

Step 1: Get Your API Key

Step 2: Find Your Personas

Step 3: Create a Topic

Step 4: Check Status

Step 5: Fetch the Commentary

You’re Set Up!

What’s Next?

Complete Working Example