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

# Topics

> Understanding topics in the Unleeshed platform

## What is a Topic?

A **topic** is a question, statement, or prompt that you submit for AI personas to generate commentary about. Topics are the starting point for all commentary generation.

<Info>
  **Human-in-the-Loop Quality**: Unlike fully automated AI, Unleeshed commentary involves human creators who inject their authentic perspective. This ensures high-fidelity, genuine responses that truly represent each persona.
</Info>

## The Commentary Workflow

When you create a topic, it goes through a human-in-the-loop process:

```mermaid theme={null}
flowchart LR
    A[Create Topic] --> B[Creator Notified]
    B --> C[Opinion Injected]
    C --> D[AI Generates]
    D --> E[Creator Approves]
    E --> F[Ready to Fetch]
```

### Per-Persona Status

Each persona's commentary progresses through these stages:

| Status                 | Description                | What's Happening                    |
| ---------------------- | -------------------------- | ----------------------------------- |
| `topic_sent`           | Topic delivered to creator | Creator received email notification |
| `opinion_injected`     | Creator added perspective  | AI is generating commentary         |
| `commentary_generated` | AI finished                | Creator is reviewing                |
| `creator_approved`     | Ready to fetch             | Commentary available via API        |
| `declined`             | Creator passed             | Topic not relevant to persona       |
| `expired`              | No response                | Creator didn't respond in time      |

### Overall Topic Status

The topic's overall status aggregates all personas:

| Status        | Description                           |
| ------------- | ------------------------------------- |
| `pending`     | All personas still at `topic_sent`    |
| `in_progress` | At least one creator is working on it |
| `partial`     | Some ready, others still processing   |
| `completed`   | All personas have finished            |

## Creating Effective Topics

<AccordionGroup>
  <Accordion title="Be specific">
    ✅ "Should the Lakers trade Anthony Davis before the February trade deadline?"

    ❌ "What about the Lakers?"
  </Accordion>

  <Accordion title="Ask debatable questions">
    Topics that invite different perspectives generate more engaging commentary.

    ✅ "Is Jokic or Embiid the better center in today's NBA?"

    ❌ "Who won the 2023 NBA Finals?" (factual, not debatable)
  </Accordion>

  <Accordion title="Keep it timely">
    Reference current events, games, or news for relevant commentary.

    ✅ "After tonight's loss, should the Cowboys fire their defensive coordinator?"

    ❌ "Are the Cowboys a good team?" (too vague)
  </Accordion>
</AccordionGroup>

## Topic Limits

| Constraint         | Limit                           |
| ------------------ | ------------------------------- |
| Content length     | 10-100 characters               |
| Personas per topic | 1-20                            |
| Duplicate window   | 24 hours (same topic + persona) |

<Tip>
  Keep topics concise and punchy. The 100-character limit encourages focused questions that generate better commentary.
</Tip>

## Metadata

You can attach custom metadata to topics for your own tracking:

```json theme={null}
{
  "content": "Should the Lakers trade AD?",
  "persona_ids": ["..."],
  "metadata": {
    "source": "daily_poll",
    "category": "nba",
    "article_id": "12345",
    "campaign": "trade_deadline_2026"
  }
}
```

Metadata is returned with topic responses but not used by Unleeshed.

## Related

<CardGroup cols={2}>
  <Card title="Create Topic API" icon="plus" href="/api-reference/topics/create">
    API reference for creating topics.
  </Card>

  <Card title="Generate Commentary Guide" icon="waveform" href="/guides/generate-commentary">
    Complete guide to generating commentary.
  </Card>
</CardGroup>