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

# Custom tags

> Filter and classify news articles using your organization's unique taxonomy.

Custom Tags applies your organization's taxonomy to news articles automatically,
letting you filter and retrieve content using your own classification system
rather than generic categories.

<Note>
  Each taxonomy is organization-specific and tied to your API key. Your
  classification system is not shared with or visible to other organizations.
</Note>

## Classification pipeline

Custom Tags uses a machine learning pipeline to classify articles against your
taxonomy. The pipeline runs in four stages:

1. **Taxonomy ingestion** — NewsCatcher's engineering team works with you to
   understand your domain, tag definitions, and any additional context or
   examples needed for accurate classification.
2. **Model training** — a large language model (LLM) is fine-tuned on your
   enriched taxonomy using a diverse dataset of news articles, capturing the
   nuances of your classification requirements.
3. **Production deployment** — the classifier is integrated into the NLP
   pipeline and applied to all incoming articles automatically. Historical
   articles processed since implementation remain available.
4. **Continuous improvement** — the model is monitored and retrained regularly
   to maintain accuracy as news trends evolve.

## API integration

Custom Tags is available on the following endpoints:

* `/search`
* `/latest_headlines`
* `/authors`

### Request format

Use the `custom_tags` parameter to filter articles by taxonomy tag, following
this pattern:

```
custom_tags.<taxonomy>: "Tag1,Tag2,Tag3"
```

where `<taxonomy>` is your taxonomy name and `Tag1,Tag2,Tag3` are the tags to
filter by. For `POST` requests, you can pass tags as a comma-separated string
or an array of strings. For `GET` requests, use a comma-separated string.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
    -H "x-api-token: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "q": "*",
      "custom_tags.my_taxonomy": ["Tag1", "Tag2", "Tag3"]
    }'
  ```

  ```python Python theme={null}
  from newscatcher import NewscatcherApi

  client = NewscatcherApi(api_key="YOUR_API_KEY")

  response = client.search.post(
      q="*",
      custom_tags={"my_taxonomy": ["Tag1", "Tag2", "Tag3"]},
  )
  ```

  ```typescript TypeScript theme={null}
  import { NewscatcherApiClient } from "newscatcher-sdk";

  const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" });

  const response = await client.search.post({
    q: "*",
    customTags: { myTaxonomy: ["Tag1", "Tag2", "Tag3"] },
  });
  ```

  ```java Java theme={null}
  import com.newscatcher.api.NewscatcherApiClient;
  import com.newscatcher.api.resources.search.requests.PostSearchRequest;
  import java.util.List;
  import java.util.Map;

  NewscatcherApiClient client = NewscatcherApiClient.builder()
      .apiKey("YOUR_API_KEY")
      .build();

  var response = client.search().post(
      PostSearchRequest.builder()
          .q("*")
          .customTags(Map.of("my_taxonomy", List.of("Tag1", "Tag2", "Tag3")))
          .build()
  );
  ```
</CodeGroup>

### Response format

Each article in the response includes a `custom_tags` field containing the
matching tags from your taxonomy:

```json theme={null}
{
  "status": "ok",
  "total_hits": 1500,
  "articles": [
    {
      "title": "Example Article Title",
      "custom_tags": {
        "my_taxonomy": ["Tag1", "Tag2"]
      }
    }
  ]
}
```

<Note>
  Custom tags in responses are always returned as an array of strings,
  regardless of the format used in the request.
</Note>

## Best practices

* Use exact tag names — tag matching is case-sensitive.
* Keep tag names unambiguous and consistent across your taxonomy to reduce
  misclassification.
* Combine `custom_tags` with other parameters such as `q`, `lang`, and
  `from_` to narrow results before applying tag filters.
* Test with broader tag sets first, then narrow based on result quality.

## See also

* [NLP features](/news-api/guides-and-concepts/nlp-features)
* [Search endpoint reference](/news-api/api-reference/search/search-articles-post)