Create Topic - Unleeshed Developer Docs

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

const response = await fetch('https://prod.api.unleeshed.ai/partner/v1/topics', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'pk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"]
  })
});

import requests

response = requests.post(
    "https://prod.api.unleeshed.ai/partner/v1/topics",
    headers={
        "X-Api-Key": "pk_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "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"
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "At least one persona_id is required"
  }
}

{
  "success": false,
  "error": {
    "code": "no_valid_personas",
    "message": "None of the requested personas could be sent to",
    "details": [
      { "persona_id": "persona-abc-123", "status": "not_licensed" }
    ]
  }
}

POST

partner

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

const response = await fetch('https://prod.api.unleeshed.ai/partner/v1/topics', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'pk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"]
  })
});

import requests

response = requests.post(
    "https://prod.api.unleeshed.ai/partner/v1/topics",
    headers={
        "X-Api-Key": "pk_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "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"
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "At least one persona_id is required"
  }
}

{
  "success": false,
  "error": {
    "code": "no_valid_personas",
    "message": "None of the requested personas could be sent to",
    "details": [
      { "persona_id": "persona-abc-123", "status": "not_licensed" }
    ]
  }
}

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

string

required

The topic content (question, statement, or prompt). 10-100 characters maximum.

string[]

required

Array of persona UUIDs to send this topic to. Must have active licenses. Use GET /personas to see your licensed personas.

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.

string[]

default:"['text']"

Desired output formats: text, audio, video

object

Custom metadata to attach (returned in responses and webhooks).

Response

string

Unique identifier for the topic. Use this to check status and fetch commentaries.

string

Your content identifier (if provided). Returned in all responses and webhooks for correlation.

string

The topic content.

integer

Number of personas that will generate commentary.

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

string

Always pending on creation.

What Happens Next

After creating a topic, the workflow proceeds:

Topic Sent - Creators are notified via email
Opinion Injected - Creator adds their unique perspective
Commentary Generated - AI generates the commentary
Creator Approved - Creator reviews and approves
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"]
  }'

const response = await fetch('https://prod.api.unleeshed.ai/partner/v1/topics', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'pk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"]
  })
});

import requests

response = requests.post(
    "https://prod.api.unleeshed.ai/partner/v1/topics",
    headers={
        "X-Api-Key": "pk_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "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"
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "At least one persona_id is required"
  }
}

{
  "success": false,
  "error": {
    "code": "no_valid_personas",
    "message": "None of the requested personas could be sent to",
    "details": [
      { "persona_id": "persona-abc-123", "status": "not_licensed" }
    ]
  }
}

​Overview

​Request

​Response

​What Happens Next

Overview

Request

Response

What Happens Next