> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unleeshed.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Topic

> Create a topic and send it to selected personas for commentary generation

## 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.

<Info>
  **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](/api-reference/topics/status) to monitor progress.
</Info>

## Request

<ParamField body="content" type="string" required>
  The topic content (question, statement, or prompt). **10-100 characters maximum.**
</ParamField>

<ParamField body="persona_ids" type="string[]" required>
  Array of persona UUIDs to send this topic to. Must have active licenses. Use [GET /personas](/api-reference/personas/list) to see your licensed personas.
</ParamField>

<ParamField body="external_reference" type="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](/guides/content-correlation) for details.
</ParamField>

<ParamField body="output_types" type="string[]" default="['text']">
  Desired output formats: `text`, `audio`, `video`
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata to attach (returned in responses and webhooks).
</ParamField>

## Response

<ResponseField name="topic_id" type="string">
  Unique identifier for the topic. Use this to check status and fetch commentaries.
</ResponseField>

<ResponseField name="external_reference" type="string">
  Your content identifier (if provided). Returned in all responses and webhooks for correlation.
</ResponseField>

<ResponseField name="content" type="string">
  The topic content.
</ResponseField>

<ResponseField name="personas_sent" type="integer">
  Number of personas that will generate commentary.
</ResponseField>

<ResponseField name="results" type="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
</ResponseField>

<ResponseField name="status" type="string">
  Always `pending` on creation.
</ResponseField>

## 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](/api-reference/commentary/get)

<Tip>
  Use [GET /topics/:id/status](/api-reference/topics/status) to poll for progress without fetching full commentary content.
</Tip>

<RequestExample>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```javascript JavaScript theme={null}
  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"]
    })
  });
  ```

  ```python Python theme={null}
  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"]
      }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "error": {
      "code": "invalid_request",
      "message": "At least one persona_id is required"
    }
  }
  ```

  ```json 403 Not Licensed theme={null}
  {
    "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" }
      ]
    }
  }
  ```
</ResponseExample>