# Collections

A collection is a list of sources. A source can belong to multiple collections. We have curated a list of existing collections to help you find great sources.

You use a collection to narrow things. Search inside it, or point an alert at it, so you are asking about a defined set of publications rather than the whole corpus.

## Two kinds

**Global collections** are the ones we curate. Every team can read them. Nobody can edit them. We keep them up to date as publications come and go. The field `is_global` marks them.

**Your collections** belong to your team. Only your team can see or change them.

## Creating one

```bash
curl -X POST -H "Authorization: Bearer $SPUTNIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Buyer podcasts", "description": "Shows our buyers listen to"}' \
  "https://sputnikintelligence.com/api/v1/collections"
```

A new collection is empty. Find publications, then add them by slug.

```bash
curl -X POST -H "Authorization: Bearer $SPUTNIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_slugs": ["p2ab-99xz-c1dd", "m4kk-01qq-ll2e"]}' \
  "https://sputnikintelligence.com/api/v1/collections/<slug>/sources"
```

Adding a publication that is already in the collection does nothing, so this is safe to retry.

## Using one

```bash
# Search inside it
/api/v1/posts/search?q=pricing&collection=<slug>

# Read it newest-first
/api/v1/posts?collection=<slug>
```

An alert search takes the same `collection` parameter, so a search you have tested can go straight into an alert.

## Deleting

Deleting a collection removes the list. The publications and their posts are untouched. Any alert scoped to that collection stops being scoped, so check those first.