Skip to main content
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

1

Log into Partner Dashboard

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

Navigate to API Keys

Click Developer → API Keys in the sidebar.
3

Create a New Key

Click Create API Key, name it “Quickstart Test”, and select these scopes:
  • personas:read
  • topics:submit
  • topics:read
4

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"
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"]
  }'
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"
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"
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:
1

Created an API key

With the right scopes for commentary generation
2

Retrieved your licensed personas

So you know who can generate commentary
3

Submitted a topic

And selected which personas should respond
4

Learned to check status

Monitor the human-in-the-loop workflow
5

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}`);
  });
}