Skip to main content
POST
/
partner
/
v1
/
topics
curl -X POST "https://prod.api.unleeshed.ai/partner/v1/topics" \
  -H "X-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Should the Lakers trade Anthony Davis before the deadline?",
    "persona_ids": ["persona-abc-123", "persona-xyz-789"],
    "external_reference": "bet-line-12345",
    "output_types": ["text"]
  }'

{
  "success": true,
  "data": {
    "topic_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_reference": "bet-line-12345",
    "content": "Should the Lakers trade Anthony Davis before the deadline?",
    "personas_sent": 2,
    "results": [
      { "persona_id": "persona-abc-123", "status": "sent" },
      { "persona_id": "persona-xyz-789", "status": "sent" }
    ],
    "status": "pending",
    "created_at": "2026-01-30T15:30:00Z"
  }
}

​
Overview

Creating a topic initiates the commentary generation workflow. The topic is sent to your selected licensed personas, and their creators are notified to generate commentary.
Human-in-the-Loop: Commentary generation involves human creators who inject their unique perspective. This ensures high-fidelity, authentic responses but means generation is not instant. Use the Status endpoint to monitor progress.

​
Request

​
content
string
required
The topic content (question, statement, or prompt). 10-100 characters maximum.
​
persona_ids
string[]
required
Array of persona UUIDs to send this topic to. Must have active licenses. Use GET /personas to see your licensed personas.
​
external_reference
string
Your content identifier for correlation (e.g., bet line ID, article slug). Max 256 characters, alphanumeric plus -_.: only. Case-sensitive. See Content Correlation Guide for details.
​
output_types
string[]
default:"['text']"
Desired output formats: text, audio, video
​
metadata
object
Custom metadata to attach (returned in responses and webhooks).

​
Response

​
topic_id
string
Unique identifier for the topic. Use this to check status and fetch commentaries.
​
external_reference
string
Your content identifier (if provided). Returned in all responses and webhooks for correlation.
​
content
string
The topic content.
​
personas_sent
integer
Number of personas that will generate commentary.
​
results
array
Per-persona status:
  • sent - Successfully sent to creator for commentary
  • not_licensed - No active license for this persona
  • duplicate - Already sent within 24 hours
​
status
string
Always pending on creation.

​
What Happens Next

After creating a topic, the workflow proceeds:
  1. Topic Sent - Creators are notified via email
  2. Opinion Injected - Creator adds their unique perspective
  3. Commentary Generated - AI generates the commentary
  4. Creator Approved - Creator reviews and approves
  5. Ready to Fetch - Use GET /topics/:id/commentaries
Use GET /topics/:id/status to poll for progress without fetching full commentary content.
curl -X POST "https://prod.api.unleeshed.ai/partner/v1/topics" \
  -H "X-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Should the Lakers trade Anthony Davis before the deadline?",
    "persona_ids": ["persona-abc-123", "persona-xyz-789"],
    "external_reference": "bet-line-12345",
    "output_types": ["text"]
  }'

{
  "success": true,
  "data": {
    "topic_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_reference": "bet-line-12345",
    "content": "Should the Lakers trade Anthony Davis before the deadline?",
    "personas_sent": 2,
    "results": [
      { "persona_id": "persona-abc-123", "status": "sent" },
      { "persona_id": "persona-xyz-789", "status": "sent" }
    ],
    "status": "pending",
    "created_at": "2026-01-30T15:30:00Z"
  }
}