---
title: "Create topic"
method: POST
path: "/topics"
tags: ["Topics"]
---

# Create topic

`POST /topics`

## Request

- Base URL: `https://api.youscan.io/api/external`
- URL: `https://api.youscan.io/api/external/topics`
- Auth: one of:
  - API key in header `X-API-KEY`
  - API key in query parameter `apiKey`
- TypeScript: <https://skmtc.dev/youscan/apis/youscan-api/docs/topics/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new topic for mention monitoring.

## Request body

- object
  - `name` string, required: Name of the topic (1-75 characters).
  - `topicQuery` TopicQuery, required: Topic query parameters. Either `textQuery` or `viQuery` must be set.
    - `textQuery` string, nullable: Text query using YouScan query syntax.
    - `viQuery` string, nullable: VI query using YouScan query syntax (requires VI subscription). Used to match mentions by logos, text, and objects on images.
    - `filter` CustomFilter
      - `op` 'and' | 'or': How the listed filters are combined.
      - `filters` FilterItem[]
        - `fieldName` 'country' | 'countryGroup' | 'language' | 'source' | 'sourceType' | 'postType' | 'contentType' | 'authorAge' | 'authorSubscribers' | 'gender', required: The field to filter on.
        - `op` 'oneOf' | 'notOneOf' | 'greaterOrEqual' | 'lessOrEqual', required: The operation to perform.
        - `value` string, required: JSON-encoded array of values, e.g. `["ua"]`.
  - `sampling` number: Sampling rate (0 < value ≤ 1). Allows you to monitor a fraction of all matching mentions. Requires a subscription plan with sampling support, otherwise the request is rejected with `400`. Optional (default value is 1 — full sample).

## Response `201`

Topic created.

- TopicInfo
  - `id` integer: Topic ID.
  - `name` string: Topic name.
  - `topicQuery` TopicQuery: Topic query parameters. Either `textQuery` or `viQuery` must be set.
    - `textQuery` string, nullable: Text query using YouScan query syntax.
    - `viQuery` string, nullable: VI query using YouScan query syntax (requires VI subscription). Used to match mentions by logos, text, and objects on images.
    - `filter` CustomFilter
      - `op` 'and' | 'or': How the listed filters are combined.
      - `filters` FilterItem[]
        - `fieldName` 'country' | 'countryGroup' | 'language' | 'source' | 'sourceType' | 'postType' | 'contentType' | 'authorAge' | 'authorSubscribers' | 'gender', required: The field to filter on.
        - `op` 'oneOf' | 'notOneOf' | 'greaterOrEqual' | 'lessOrEqual', required: The operation to perform.
        - `value` string, required: JSON-encoded array of values, e.g. `["ua"]`.
  - `sampling` number, nullable: Sampling rate, if sampling is enabled for the topic.

## Other responses

- `400`: The request is invalid.
- `401`: The API key is missing or invalid.
- `402`: Too many mentions matching the query for your subscription plan.
- `403`: You don't have permission to create topics in the target space.

---

[API](https://skmtc.dev/youscan/apis/youscan-api.md) - [All operations](https://skmtc.dev/youscan/apis/youscan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/youscan/apis/youscan-api/revisions/f5bef260f153?raw)