YouScan

YouScan Topics API

Create and manage topics — the monitoring entities that collect mentions matching your queries. ### Topic query structure A topic query consists of a `textQuery` and/or `viQuery` (at least one is required) plus an optional `filter`. For all topic query filters, the following field names are supported: - `country`: ISO2 country code (e.g. `country=US`, `country=UA`) - `countryGroup`: Europe, Asia, NorthAmerica, CentralAmerica, TheCaribbean, SouthAmerica, Africa, Oceania (e.g. `countryGroup=Europe`) - `language`: ISO639-2 language code (e.g. `language=ENG`, `language=UKR`) - `source`: domain format (e.g. `source=instagram.com`) - `sourceType`: social, messenger, reviews, news, blog, forum (e.g. `sourceType=social`) - `postType`: post, repost, extendedRepost, comment (e.g. `postType=post`) - `contentType`: text, link, image, video, poll, subtitles, sticker (e.g. `contentType=image`) - `authorAge`: numeric value (e.g. `authorAge=18`) - `authorSubscribers`: numeric value (e.g. `authorSubscribers=1000`) - `gender`: `male` or `female` (e.g. `gender=male`) Supported Visual Insights (VI) query values (used inside `viQuery`): - `logo`: detect specific brand logos (e.g. `logo:"nike"`) - `image.object`: find specific objects (e.g. `image.object:"car"`) - `image.activity`: find activities (e.g. `image.activity:"cooking"`) - `image.person`: find people types (e.g. `image.person:"athlete"`) - `image.scene`: find settings (e.g. `image.scene:"beach"`) - `image.type`: filter by image type (e.g. `image.type:"PHOTO"`) - `image.subtype`: filter by image subtype (e.g. `image.subtype:"selfie"`) - `text`: search mention text (e.g. `text:"sale"`) Supported operations for each filter: - `oneOf`: field value must match one of the specified values. Applicable to most fields. - `notOneOf`: field value must not match any of the specified values. Applicable to most fields. - `greaterOrEqual`: field value must be greater than or equal to the specified value. Numeric fields only (`authorAge`, `authorSubscribers`). - `lessOrEqual`: field value must be less than or equal to the specified value. Numeric fields only (`authorAge`, `authorSubscribers`). Each filter object must specify: - `fieldName`: The field to filter on (see the list above) - `op`: The operation to perform (see the list above) - `value`: JSON-encoded array of values (e.g. `["ua"]`)

GitHub OpenAPI

Operations 5

GET /topics List topics #
POST /topics Create topic #
POST /topics/preview Preview topic #
POST /topics/{topicId}/query/edit Update topic query #
DELETE /topics/{topicId} Delete topic #

Documentation

📖
Documentation
https://developers.youscan.io/
📖
APIReference
https://developers.youscan.io/api/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/youscan/refs/heads/main/openapi/youscan-topics-api-openapi.yml

Other Resources

🔗
LLMsTxt
https://raw.githubusercontent.com/api-evangelist/youscan/refs/heads/main/llms/youscan-llms.txt

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/youscan-topics-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

youscan-topics-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: YouScan Topics API
  version: '1.0'
  contact:
    name: YouScan Support
    url: https://youscan.io
  license:
    name: Proprietary
    url: https://youscan.io/terms-of-service
  description: 'YouScan provides a REST API to manage topics, retrieve mentions, and query statistics

    collected by the YouScan social media listening platform.'
servers:
- url: https://api.youscan.io/api/external
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Topics
  description: Create and manage topics — the monitoring entities that collect mentions matching your queries.
paths:
  /topics:
    get:
      tags:
      - Topics
      operationId: listTopics
      summary: List topics
      description: List all topics available in your account.
      responses:
        '200':
          description: Topics available in the account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  topics:
                    type: array
                    items:
                      $ref: '#/components/schemas/TopicInfo'
              example:
                topics:
                - id: 41541
                  name: Coca-cola
                - id: 41546
                  name: Pepsi Cola
                - id: 41550
                  name: Fanta
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Topics
      operationId: createTopic
      summary: Create topic
      description: Creates a new topic for mention monitoring.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - topicQuery
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 75
                  description: Name of the topic (1-75 characters).
                topicQuery:
                  $ref: '#/components/schemas/TopicQuery'
                sampling:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 1
                  default: 1
                  description: '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).

                    '
            example:
              name: Topic Name
              topicQuery:
                textQuery: brand OR company
                viQuery: logo:microsoft
                filter:
                  op: and
                  filters:
                  - fieldName: country
                    op: notOneOf
                    value: '["ua"]'
              sampling: 0.5
      responses:
        '201':
          description: Topic created.
          headers:
            Location:
              description: URL of the created topic.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicInfo'
              example:
                id: 123
                name: Topic Name
                topicQuery:
                  textQuery: brand OR company
                  viQuery: logo:microsoft
                sampling: 0.5
        '400':
          $ref: '#/components/responses/ValidationError'
        '402':
          $ref: '#/components/responses/HistoryLimitExceeded'
        '403':
          description: You don't have permission to create topics in the target space.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: You don't have permission to create topics in this space
        '401':
          $ref: '#/components/responses/Unauthorized'
  /topics/preview:
    post:
      tags:
      - Topics
      operationId: previewTopic
      summary: Preview topic
      description: Estimate the number of monthly mentions for a topic query before creating a topic. This helps you check if your query is within your plan limits and if sampling is available.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - topicQuery
              properties:
                topicQuery:
                  $ref: '#/components/schemas/TopicQuery'
                sampling:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 1
                  default: 1
                  description: Sampling rate (0 < value ≤ 1). Optional (default value is 1 — full sample).
            example:
              topicQuery:
                textQuery: brand OR company
                viQuery: logo:microsoft
                filter:
                  op: and
                  filters:
                  - fieldName: country
                    op: notOneOf
                    value: '["ua"]'
              sampling: 0.5
      responses:
        '200':
          description: Estimation result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  monthlyCount:
                    type: integer
                    description: Estimated number of mentions per month for the query.
                  monthlyLimit:
                    type: integer
                    description: Monthly mentions limit of your subscription plan.
                  isWithinLimit:
                    type: boolean
                    description: Whether the estimated count fits into the plan limit.
                  samplingAllowed:
                    type: boolean
                    description: Whether sampling is available in your subscription plan.
                  sampling:
                    type:
                    - number
                    - 'null'
                    description: Sampling rate echoed from the request.
              example:
                monthlyCount: 12345
                monthlyLimit: 20000
                isWithinLimit: true
                samplingAllowed: true
                sampling: 0.5
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /topics/{topicId}/query/edit:
    post:
      tags:
      - Topics
      operationId: updateTopicQuery
      summary: Update topic query
      description: Updates an existing topic's query parameters.
      parameters:
      - $ref: '#/components/parameters/TopicId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - topicQuery
              properties:
                topicQuery:
                  $ref: '#/components/schemas/TopicQuery'
            example:
              topicQuery:
                textQuery: updated brand OR company
                viQuery: logo:microsoft
                filter:
                  op: and
                  filters:
                  - fieldName: country
                    op: notOneOf
                    value: '["ua"]'
      responses:
        '200':
          description: Updated topic.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicInfo'
              example:
                id: 123
                name: Topic Name
                topicQuery:
                  textQuery: updated brand OR company
                  viQuery: logo:microsoft
        '400':
          $ref: '#/components/responses/ValidationError'
        '402':
          $ref: '#/components/responses/HistoryLimitExceeded'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TopicNotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /topics/{topicId}:
    delete:
      tags:
      - Topics
      operationId: deleteTopic
      summary: Delete topic
      description: Deletes a topic and all its associated data. This action is irreversible.
      parameters:
      - $ref: '#/components/parameters/TopicId'
      responses:
        '200':
          description: Topic deleted successfully.
          content:
            application/json:
              schema:
                type: boolean
              example: true
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/TopicNotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    TopicId:
      name: topicId
      in: path
      required: true
      description: ID of the Topic.
      schema:
        type: integer
  schemas:
    TopicInfo:
      type: object
      properties:
        id:
          type: integer
          description: Topic ID.
        name:
          type: string
          description: Topic name.
        topicQuery:
          $ref: '#/components/schemas/TopicQuery'
        sampling:
          type:
          - number
          - 'null'
          description: Sampling rate, if sampling is enabled for the topic.
    CustomFilter:
      type: object
      properties:
        op:
          type: string
          enum:
          - and
          - or
          description: How the listed filters are combined.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/FilterItem'
    ValidationError:
      type: object
      properties:
        errorCode:
          type: string
          const: VALIDATION_ERROR
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              errorCode:
                type: string
              message:
                type: string
    Error:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error description.
        resourceType:
          type: string
          description: 'Present on `RESOURCE_NOT_FOUND` errors — the type of the missing resource (e.g. "Import", "Space").

            '
    FilterItem:
      type: object
      required:
      - fieldName
      - op
      - value
      properties:
        fieldName:
          type: string
          description: The field to filter on.
          enum:
          - country
          - countryGroup
          - language
          - source
          - sourceType
          - postType
          - contentType
          - authorAge
          - authorSubscribers
          - gender
        op:
          type: string
          description: The operation to perform.
          enum:
          - oneOf
          - notOneOf
          - greaterOrEqual
          - lessOrEqual
        value:
          type: string
          description: JSON-encoded array of values, e.g. `["ua"]`.
      example:
        fieldName: country
        op: notOneOf
        value: '["ua"]'
    TopicQuery:
      type: object
      description: 'Topic query parameters. Either `textQuery` or `viQuery` must be set.

        '
      properties:
        textQuery:
          type:
          - string
          - 'null'
          description: Text query using YouScan query syntax.
        viQuery:
          type:
          - string
          - 'null'
          description: 'VI query using YouScan query syntax (requires VI subscription). Used to match mentions by logos, text, and objects on images.

            '
        filter:
          oneOf:
          - $ref: '#/components/schemas/CustomFilter'
          - type: 'null'
          description: Optional filter criteria (see the filter structure description in the Topics section).
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
    ValidationError:
      description: The request is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            errorCode: VALIDATION_ERROR
            message: '''TextQuery'' should not be empty.'
            errors:
            - field: TextQuery
              errorCode: notempty_error
              message: '''TextQuery'' should not be empty.'
    HistoryLimitExceeded:
      description: Too many mentions matching the query for your subscription plan.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errorCode: HISTORY_LIMIT_EXCEEDED
            message: Too many mentions matching query. Please refine your search query or ask support for help
    TopicNotFound:
      description: Topic not found or you don't have access to it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Theme not found
    Forbidden:
      description: Your permission level for this topic is too low for the action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: THEME_PERMISSION_DENIED
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key authentication. The recommended way to authenticate requests.
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
      description: API key as a query parameter. For testing purposes only.