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

# Content Correlation Guide

> Map Unleeshed commentaries to your content using external_reference

# Content Correlation

This guide explains how to use `external_reference` to map generated commentaries back to your content (e.g., bet lines, articles, game events).

## The Problem

When you create a topic through the API, you receive a `topic_id`. But how do you know which of your content items this commentary belongs to when it's ready?

## The Solution: external\_reference

The `external_reference` field allows you to pass your own content identifier when creating topics. This ID is:

* Stored with every share
* Returned in all API responses
* Included in webhook payloads

## Creating Topics with external\_reference

```bash theme={null}
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": "Dolphins -7 vs. Bears",
    "persona_ids": ["uuid-1", "uuid-2"],
    "external_reference": "bet-line-12345",
    "metadata": {
      "bet_type": "spread",
      "line": -7,
      "game_id": "nfl-week5-mia-chi"
    }
  }'
```

### Validation Rules

| Rule               | Details                                 |
| ------------------ | --------------------------------------- |
| Max length         | 256 characters                          |
| Allowed characters | `a-z`, `A-Z`, `0-9`, `-`, `_`, `.`, `:` |
| Case sensitivity   | Yes - `Bet-123` ≠ `bet-123`             |

## Querying by external\_reference

Retrieve all commentaries for a given reference:

```bash theme={null}
curl https://prod.api.unleeshed.ai/partner/v1/topics/by-reference/bet-line-12345 \
  -H "X-Api-Key: your_api_key"
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "external_reference": "bet-line-12345",
    "topic_id": "uuid",
    "content": "Dolphins -7 vs. Bears",
    "metadata": {
      "bet_type": "spread",
      "line": -7
    },
    "commentaries": [
      {
        "share_id": "uuid",
        "persona_id": "uuid-1",
        "persona_name": "Mike Thompson",
        "status": "completed",
        "commentary": {
          "id": "uuid",
          "content": "The Dolphins...",
          "audio_url": "https://..."
        }
      },
      {
        "share_id": "uuid",
        "persona_id": "uuid-2",
        "persona_name": "Sarah Chen",
        "status": "pending",
        "commentary": null
      }
    ],
    "summary": {
      "total_personas": 2,
      "completed": 1,
      "pending": 1,
      "failed": 0
    }
  }
}
```

## Idempotency

If you create a topic with the same `(external_reference, persona_id)` combination, we return the existing share instead of creating a duplicate:

```json theme={null}
{
  "persona_id": "uuid-1",
  "status": "duplicate",
  "message": "Already shared with external_reference \"bet-line-12345\" (status: pending)",
  "share_id": "existing-share-id"
}
```

This is useful for:

* Retry logic after network failures
* Preventing duplicate commentary requests
* Safely re-running batch jobs

## 1:N Correlation Model

One `external_reference` can have multiple commentaries (one per persona). This supports the common use case of getting multiple analysts' takes on the same bet line.

```
external_reference: "bet-line-12345"
├── Persona 1: Mike Thompson → commentary (completed)
├── Persona 2: Sarah Chen → commentary (pending)
└── Persona 3: Alex Rivera → commentary (completed)
```

## Using with Webhooks

Webhooks include `external_reference` in every payload, making it easy to map callbacks to your content:

```json theme={null}
{
  "type": "creator.approved",
  "data": {
    "external_reference": "bet-line-12345",
    "persona_id": "uuid-1",
    "persona_name": "Mike Thompson",
    "commentary": { ... },
    "metadata": {
      "bet_type": "spread",
      "line": -7
    }
  }
}
```

## metadata Field

Use `metadata` to store additional context that's returned with all responses:

```json theme={null}
{
  "external_reference": "bet-line-12345",
  "metadata": {
    "bet_type": "spread",
    "line": -7,
    "game_id": "nfl-week5-mia-chi",
    "sport": "nfl",
    "priority": "high",
    "internal_campaign_id": "fall-2026-promo"
  }
}
```

The `metadata` field:

* Accepts any valid JSON object
* Has no size limit (but keep it reasonable)
* Is returned in all responses and webhooks
* Is stored with each share

## Complete Integration Flow

```mermaid theme={null}
sequenceDiagram
    participant Partner
    participant Unleeshed
    participant Creator

    Partner->>Unleeshed: POST /topics (external_reference=bet-123)
    Unleeshed-->>Partner: topic_id, external_reference
    
    Note over Unleeshed,Creator: Creator workflow...
    
    Unleeshed->>Partner: Webhook (external_reference=bet-123)
    Partner->>Partner: Match bet-123 to content
    Partner->>Partner: Display commentary on bet page
```

## Best Practices

1. **Use meaningful IDs**: Make references human-readable for debugging
2. **Include metadata**: Store context you'll need when receiving webhooks
3. **Handle duplicates**: Check for `duplicate` status in responses
4. **Query by reference**: Use the by-reference endpoint rather than storing topic\_ids