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

# Sources

> Retrieve aggregated source domains cited in AI responses.

Sources are the domains that AI providers cite when answering tracked prompts. This endpoint aggregates citation data at the domain level across all prompts in a project.

## List sources

```
GET /projects/{project_id}/sources
```

Returns source domains with citation counts, paginated and sorted by `reference_count` descending.

### Path parameters

| Param        | Type          | Description    |
| ------------ | ------------- | -------------- |
| `project_id` | string (UUID) | The project ID |

### Query parameters

| Param           | Type    | Default | Description                       |
| --------------- | ------- | ------- | --------------------------------- |
| `page`          | integer | `1`     | Page number (starts at 1)         |
| `page_size`     | integer | `50`    | Results per page (min 1, max 100) |
| `duration_days` | integer | `7`     | Days to look back                 |
| `date_from`     | string  | --      | Start date (`YYYY-MM-DD`)         |
| `date_to`       | string  | --      | End date (`YYYY-MM-DD`)           |
| `providers`     | string  | --      | Comma-separated provider filter   |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/sources?page=1&page_size=50&duration_days=7" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/sources", params={"page": 1, "page_size": 50, "duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/sources?page=1&page_size=50&duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "source_id": "s1t2u3v4-...",
      "domain": "techcrunch.com",
      "category": 1,
      "reference_count": 127
    },
    {
      "source_id": "w5x6y7z8-...",
      "domain": "forbes.com",
      "category": 1,
      "reference_count": 89
    }
  ]
}
```

### SourceDomainResponse fields

| Field             | Type          | Nullable | Description                                          |
| ----------------- | ------------- | -------- | ---------------------------------------------------- |
| `source_id`       | string (UUID) | No       | Source ID                                            |
| `domain`          | string        | No       | Domain name                                          |
| `category`        | integer       | No       | Domain category ID                                   |
| `reference_count` | integer       | No       | Total citations across all prompts in the date range |

<Note>
  The `data` field is a flat array (not wrapped in an object) for this endpoint. Pagination does not include a `total` count -- fetch pages until an empty array is returned.
</Note>

***

## Get source detail

```http theme={null}
GET /projects/{project_id}/sources/{domain}/detail
```

Returns citation statistics, top cited URLs, and prompts that cited one source domain.

### Query parameters

| Param           | Type    | Default | Description                                     |
| --------------- | ------- | ------- | ----------------------------------------------- |
| `duration_days` | integer | `7`     | Lookback window when explicit dates are omitted |
| `date_from`     | string  | --      | Start date (`YYYY-MM-DD`)                       |
| `date_to`       | string  | --      | End date (`YYYY-MM-DD`)                         |
| `providers`     | string  | --      | Comma-separated provider filter                 |
| `page`          | integer | `1`     | Page for both URL and prompt lists              |
| `page_size`     | integer | `20`    | Items per list, maximum 100                     |

```bash theme={null}
curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/sources/techcrunch.com/detail?duration_days=30" \
  -H "X-API-Key: tk_live_..."
```

The response includes `stats`, a paginated `urls` object, and a paginated `prompts` object. Each paginated object contains `page`, `page_size`, `total`, and `items`.

***

## List source chats

```http theme={null}
GET /projects/{project_id}/sources/{domain}/chats
```

Returns AI responses that cited the requested domain.

### Query parameters

| Param           | Type    | Default | Description                                     |
| --------------- | ------- | ------- | ----------------------------------------------- |
| `duration_days` | integer | `7`     | Lookback window when explicit dates are omitted |
| `date_from`     | string  | --      | Start date (`YYYY-MM-DD`)                       |
| `date_to`       | string  | --      | End date (`YYYY-MM-DD`)                         |
| `providers`     | string  | --      | Comma-separated provider filter                 |
| `page`          | integer | `1`     | Page number                                     |
| `page_size`     | integer | `10`    | Results per page, maximum 50                    |

```bash theme={null}
curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/sources/techcrunch.com/chats?providers=chatgpt&page=1&page_size=10" \
  -H "X-API-Key: tk_live_..."
```

Each chat item includes the provider, model, prompt, preview, full response content, detected brand and sentiment data, and references.