OpenAPI Specification
openapi: 3.1.0
info:
title: YouScan Data Import Tags 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\ncollected by the YouScan social media listening platform.\n\n## Authentication\n\nYouScan API uses a token authentication scheme. Requests should contain the header\n`X-API-KEY` or, alternatively, an `apiKey` query parameter (for testing purposes).\n\n```bash\ncurl -X GET \\\n --url \"https://api.youscan.io/api/external/topics\" \\\n --header \"Accept: application/json\" \\\n --header \"X-API-KEY: **********\"\n```\n\n## Permissions\n\nEach API key belongs to a single user in a single account and inherits that user's access.\nMost endpoints act on a topic, and what you may do depends on your permission level for it:\n\n- **View** — read mentions, statistics and tags; create and abort imports\n- **Edit** — View, plus create tags and bulk-update mentions\n- **Manage** — Edit, plus change the topic query, delete the topic, and start/stop history collection\n\nAdministrators and managers have full access to all topics in their spaces.\n\nWhen your access is insufficient, endpoints respond with:\n\n- **403 Forbidden** — you can see the topic but your permission level is too low for the action.\n- **404 Not Found** (`message: \"Theme not found\"`) — the topic doesn't exist or isn't visible\n to your account. Existence is intentionally not revealed.\n- **402 Payment Required** — your subscription plan doesn't include the API access the\n endpoint requires.\n\nCreating a topic also requires permission to create topics in the target space: administrators\nand managers always can; a regular member can only if granted the \"create topics\" permission,\notherwise the request returns **403**.\n\n## Rate limits\n\nWe recommend to use no more than 5 parallel API requests and no more than 10 requests per 10 seconds.\n\nRequests beyond those limits might be rejected with 429 status code (`Too Many Requests`).\n\n## Status and error codes\n\nYouScan uses conventional HTTP response codes to indicate the success or failure of an API request.\n\nIn general, codes in the 200 range indicate success. Codes in the 400 range indicate an error\nthat failed given the information provided (for example, a required parameter was omitted).\nCodes in the 500 range indicate an error with YouScan's servers.\n\nBesides the status code, `errorCode` and `message` fields are returned in the response body for\nall types of client errors. The `errorCode` field should be used by robots, while `message`\ncontains user-friendly information.\n\nSending an invalid request results in a `400 Bad Request` response with `errorCode` equal to\n`VALIDATION_ERROR`:\n\n```json\n{\n \"message\": \"Validation Failed -- 'Name' must be between 1 and 75 characters. You entered 500 characters.\",\n \"errorCode\": \"VALIDATION_ERROR\",\n \"errors\": [\n {\n \"field\": \"Name\",\n \"errorCode\": \"length_error\",\n \"message\": \"'Name' must be between 1 and 75 characters. You entered 500 characters.\"\n }\n ]\n}\n```\n"
servers:
- url: https://api.youscan.io/api/external
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Tags
description: Manage tags created in your topic.
paths:
/topics/{topicId}/tags:
get:
tags:
- Tags
operationId: listTags
summary: List tags
description: Returns the collection of tags created in your topic.
parameters:
- $ref: '#/components/parameters/TopicId'
responses:
'200':
description: Tags in the topic.
content:
application/json:
schema:
type: object
properties:
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
example:
tags:
- id: 1
name: Spam
color: red
note: Special tag for spam mentions
- id: 2
name: News
color: green
- id: 3
name: Social
note: Special tag for mentions from social network
'404':
$ref: '#/components/responses/TopicNotFound'
'401':
$ref: '#/components/responses/Unauthorized'
post:
tags:
- Tags
operationId: createTag
summary: Create tag
description: Creates a new tag in the topic.
parameters:
- $ref: '#/components/parameters/TopicId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 100
description: Unique tag name.
note:
type: string
description: Optional tag notes.
color:
type: string
maxLength: 50
description: 'Optional tag color. Any string up to 50 characters is accepted; the standard palette is red, pink, purple, indigo, blue, teal, green, lime, yellow, amber, orange, gray.
'
example:
name: unique_name
note: some notes
color: red
responses:
'201':
description: Tag created.
'400':
$ref: '#/components/responses/ValidationError'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/TopicNotFound'
'409':
description: Tag with the same name already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errorCode: ALREADY_EXISTS
message: Tag already exists
'401':
$ref: '#/components/responses/Unauthorized'
components:
responses:
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
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.'
Unauthorized:
description: The API key is missing or invalid.
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
schemas:
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").
'
Tag:
type: object
properties:
id:
type: integer
description: Tag ID.
name:
type: string
description: Tag name, unique within the topic.
color:
type:
- string
- 'null'
description: Tag color.
note:
type:
- string
- 'null'
description: Tag notes.
parameters:
TopicId:
name: topicId
in: path
required: true
description: ID of the Topic.
schema:
type: integer
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.