Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Consumer Research Projects API
version: '2.0'
servers:
- url: https://api.brandwatch.com
security:
- sec0: []
tags:
- name: Projects
paths:
/projects/summary:
get:
summary: Project Summary List
description: Retrieve a summary of all of your Projects.
operationId: retrieving-project-summary
parameters:
- name: page
in: query
description: page
schema:
type: integer
format: int32
default: -1
- name: pageSize
in: query
description: Total results shown per page
schema:
type: integer
format: int32
default: -1
- name: nameContains
in: query
description: Search for projects which contain a specified string in their name
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"resultsTotal\": 2,\n \"resultsPage\": -1,\n \"resultsPageSize\": -1,\n \"results\": [\n {\n \"id\": 398748937,\n \"name\": \"Telecoms research\",\n \"description\": \"Mobile phones\",\n \"billableClientId\": 127732,\n \"billableClientName\": \"My company\",\n \"timezone\": \"Africa/Abidjan\",\n \"billableClientIsPitch\": false\n },\n {\n \"id\": 32092327,\n \"name\": \"GPS research\",\n \"description\": \"In-car navigation systems\",\n \"billableClientId\": 127732,\n \"billableClientName\": \"My company\",\n \"timezone\": \"America/Glace_Bay\",\n \"billableClientIsPitch\": false\n }\n ]\n}"
schema:
type: object
properties:
resultsTotal:
type: integer
example: 2
default: 0
resultsPage:
type: integer
example: -1
default: 0
resultsPageSize:
type: integer
example: -1
default: 0
results:
type: array
items:
type: object
properties:
id:
type: integer
example: 398748937
default: 0
name:
type: string
example: Telecoms research
description:
type: string
example: Mobile phones
billableClientId:
type: integer
example: 127732
default: 0
billableClientName:
type: string
example: My company
timezone:
type: string
example: Africa/Abidjan
billableClientIsPitch:
type: boolean
example: false
default: true
'401':
description: '401'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'403':
description: '403'
content:
text/plain:
examples:
Result:
value: ''
'404':
description: '404'
content:
text/plain:
examples:
Result:
value: ''
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl -X GET https://api.brandwatch.com/projects/summary
samples-languages:
- curl
tags:
- Projects
/projects/{projectId}:
get:
summary: Project Info
description: Retrieve information on a specific Project.
operationId: retrieving-specific-project-summary
parameters:
- name: projectId
in: path
schema:
type: integer
format: int32
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": 1998283570,\n \"name\": \"Test Project\",\n \"description\": \"\",\n \"clientId\": 1997404085,\n \"defaultLangCodes\": [\n \"en\"\n ],\n \"creatorUserId\": 212280860,\n \"creationDate\": \"2020-01-27T22:25:50.755+0000\",\n \"billableClientId\": 1997404084,\n \"timezone\": \"America/New_York\",\n \"clientName\": \"Staff - Test Client\",\n \"billableClientName\": \"Staff - Test Client\",\n \"shardName\": \"39\",\n \"shard\": 39,\n \"queryLimit\": null,\n \"twitterChannelLimit\": null,\n \"nonTwitterChannelLimit\": null,\n}"
'401':
description: '401'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'404':
description: '404'
content:
text/plain:
examples:
Result:
value: ''
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl -X GET https://api.brandwatch.com/projects/32092327
samples-languages:
- curl
tags:
- Projects
/projects/{projectId}/queries/summary:
get:
summary: Query Summary List
description: Retrieve a list of all Queries in a Project.
operationId: retrieving-queries-1
parameters:
- name: projectId
in: path
schema:
type: integer
format: int32
required: true
- name: includeActive
in: query
description: Include active projects
schema:
type: boolean
default: false
- name: includeInactive
in: query
description: Include inactive projects
schema:
type: boolean
default: false
- name: page
in: query
schema:
type: integer
format: int32
default: -1
- name: pageSize
in: query
description: The number of projects shown per page
schema:
type: integer
format: int32
default: -1
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"resultsTotal\": 2,\n \"resultsPage\": -1,\n \"resultsPageSize\": -1,\n \"results\": [\n {\n \"id\": 1999933037,\n \"name\": \"@brandwatchsocial\",\n \"type\": \"monitor\",\n \"creationDate\": \"2019-10-10T17:36:13.933+0000\",\n \"lastModificationDate\": \"2019-10-10T17:37:23.681+0000\",\n \"lastModifiedUsername\": \"example@example.com\",\n \"lockedQuery\": false,\n \"lockedByUsername\": null,\n \"createdByWizard\": false,\n \"languages\": [\n \"en\"\n ],\n \"contentSources\": [\n \"news\",\n \"twitter\",\n \"review\",\n \"blog\"\n ],\n \"languageAgnostic\": false\n },\n {\n \"id\": 1999934807,\n \"name\": \"Mentions of Pepsi\",\n \"type\": \"monitor\",\n \"creationDate\": \"2019-10-14T13:58:21.525+0000\",\n \"lastModificationDate\": \"2019-10-23T17:22:15.904+0000\",\n \"lastModifiedUsername\": \"example@example.com\",\n \"lockedQuery\": false,\n \"lockedByUsername\": null,\n \"createdByWizard\": false,\n \"languages\": [\n \"en\"\n ],\n \"contentSources\": [\n \"news\"\n ],\n \"languageAgnostic\": false\n }\n ]\n}"
schema:
type: object
properties:
resultsTotal:
type: integer
example: 2
default: 0
resultsPage:
type: integer
example: -1
default: 0
resultsPageSize:
type: integer
example: -1
default: 0
results:
type: array
items:
type: object
properties:
id:
type: integer
example: 1999933037
default: 0
name:
type: string
example: '@brandwatchsocial'
type:
type: string
example: monitor
creationDate:
type: string
example: 2019-10-10T17:36:13.933+0000
lastModificationDate:
type: string
example: 2019-10-10T17:37:23.681+0000
lastModifiedUsername:
type: string
example: example@example.com
lockedQuery:
type: boolean
example: false
default: true
lockedByUsername: {}
createdByWizard:
type: boolean
example: false
default: true
languages:
type: array
items:
type: string
example: en
contentSources:
type: array
items:
type: string
example: news
languageAgnostic:
type: boolean
example: false
default: true
'401':
description: '401'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'403':
description: '403'
content:
text/plain:
examples:
Result:
value: ''
'404':
description: '404'
content:
text/plain:
examples:
Result:
value: ''
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl -X GET https://api.brandwatch.com/projects/398748937/queries/summary
samples-languages:
- curl
tags:
- Projects
/projects/{projectId}/queries:
get:
summary: Detailed Query Summary List
description: Retrieve a detailed summary of all Queries in your Project.
operationId: retrieving-detailed-summary-all-queries
parameters:
- name: projectId
in: path
schema:
type: integer
format: int32
required: true
- name: nameContains
in: query
description: Search for Queries with a specified string in their name
schema:
type: string
- name: type
in: query
description: '`monitor`,`publicFacebook`,`twitter` or `instagram`'
schema:
type: array
items:
type: string
- name: includeHidden
in: query
description: Include hidden Queries
schema:
type: boolean
default: false
- name: includeActive
in: query
description: Include active Queries
schema:
type: boolean
default: true
- name: includeInactive
in: query
description: Include inactive Queries
schema:
type: boolean
default: false
- name: page
in: query
schema:
type: integer
format: int32
default: -1
- name: pageSize
in: query
description: The number of Queries shown per page
schema:
type: integer
format: int32
default: -1
- name: ids
in: query
description: Use the Query ID to show specified Queries
schema:
type: array
items:
type: integer
format: int32
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"resultsTotal\": 1,\n \"resultsPage\": -1,\n \"resultsPageSize\": -1,\n \"results\": [\n {\n \"id\": 1999933037,\n \"name\": \"BBC\",\n \"description\": null,\n \"creationDate\": \"2019-10-10T17:36:13.933+0000\",\n \"lastModificationDate\": \"2019-10-10T17:37:23.681+0000\",\n \"languages\": [\n \"en\"\n ],\n \"type\": \"monitor\",\n \"highlightTerms\": [\n \"the BBC\",\n ],\n \"lastModifiedUsername\": \"example@example.com\",\n \"lockedQuery\": false,\n \"lockedByUsername\": null,\n \"lockedTime\": null,\n \"createdByWizard\": false,\n \"booleanQuery\": \"the BBC\",\n \"startDate\": \"2016-01-01T00:00:00.000+0000\",\n \"percentComplete\": 100,\n \"samplePercentage\": 11.4649,\n \"sampled\": false,\n \"locationFilter\": null,\n \"imageFilter\": null,\n \"contentSources\": [\n \"news\",\n \"twitter\",\n \"review\",\n \"blog\"\n ],\n }\n ]\n}"
'401':
description: '401'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'403':
description: '403'
content:
text/plain:
examples:
Result:
value: ''
'404':
description: '404'
content:
text/plain:
examples:
Result:
value: ''
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl -X GET https://api.brandwatch.com/projects/398748937/queries
samples-languages:
- curl
tags:
- Projects
/projects/{projectId}/queries/{queryId}:
get:
summary: Detailed Query Info
description: Retrieve information for a single Query.
operationId: retrieve-details-specific-query
parameters:
- name: projectId
in: path
schema:
type: integer
format: int32
required: true
- name: queryId/queryGroupId
in: path
schema:
type: integer
format: int32
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": 2000124252,\n \"name\": \"GM Demo - Buick\",\n \"description\": null,\n \"creationDate\": \"2020-04-03T23:20:35.043+0000\",\n \"lastModificationDate\": \"2020-04-03T23:38:56.851+0000\",\n \"languages\": [\n \"en\"\n ],\n \"type\": \"monitor\",\n \"highlightTerms\": [\n \"buick\",\n \"buicks\"\n ],\n \"lastModifiedUsername\": \"example@brandwatch.com\",\n \"lockedQuery\": false,\n \"lockedByUsername\": null,\n \"lockedTime\": null,\n \"createdByWizard\": false,\n \"booleanQuery\": \"buick OR buicks OR title:(buick OR buicks)\",\n \"monitorId\": 34655332892,\n \"startDate\": \"2020-03-01T00:00:00.000+0000\",\n \"percentComplete\": 100,\n \"samplePercentage\": 100.0000,\n \"userRequestedSampling\": false,\n \"sampled\": false,\n \"queryLimitUsage\": 1,\n \"locationFilter\": {\n \"includedLocations\": [\n \"USA\"\n ],\n \"excludedLocations\": []\n },\n \"imageFilter\": null,\n \"contentSources\": [\n \"forum\",\n \"news\",\n \"twitter\"\n ],\n \"audienceLists\": null,\n \"exclusionSnippets\": [],\n \"active\": true\n}"
schema:
type: object
properties:
id:
type: integer
example: 2000124252
default: 0
name:
type: string
example: GM Demo - Buick
description: {}
creationDate:
type: string
example: 2020-04-03T23:20:35.043+0000
lastModificationDate:
type: string
example: 2020-04-03T23:38:56.851+0000
languages:
type: array
items:
type: string
example: en
type:
type: string
example: monitor
highlightTerms:
type: array
items:
type: string
example: buick
lastModifiedUsername:
type: string
example: example@brandwatch.com
lockedQuery:
type: boolean
example: false
default: true
lockedByUsername: {}
lockedTime: {}
createdByWizard:
type: boolean
example: false
default: true
booleanQuery:
type: string
example: buick OR buicks OR title:(buick OR buicks)
monitorId:
type: integer
example: 34655332892
default: 0
startDate:
type: string
example: 2020-03-01T00:00:00.000+0000
percentComplete:
type: integer
example: 100
default: 0
samplePercentage:
type: integer
example: 100
default: 0
userRequestedSampling:
type: boolean
example: false
default: true
sampled:
type: boolean
example: false
default: true
queryLimitUsage:
type: integer
example: 1
default: 0
locationFilter:
type: object
properties:
includedLocations:
type: array
items:
type: string
example: USA
excludedLocations:
type: array
items:
type: object
properties: {}
imageFilter: {}
contentSources:
type: array
items:
type: string
example: forum
audienceLists: {}
exclusionSnippets:
type: array
items:
type: object
properties: {}
active:
type: boolean
example: true
default: true
'401':
description: '401'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'403':
description: '403'
content:
text/plain:
examples:
Result:
value: ''
'404':
description: '404'
content:
text/plain:
examples:
Result:
value: ''
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl -X GET 'https://api.brandwatch.com/projects/1998283571/queries/2000124252'
samples-languages:
- curl
tags:
- Projects
delete:
summary: Delete Queries
description: ''
operationId: deleting-queries-1
parameters:
- name: projectId
in: path
schema:
type: integer
format: int32
required: true
- name: queryId/queryGroupId
in: path
schema:
type: integer
format: int32
required: true
responses:
'204':
description: '204'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'401':
description: '401'
content:
text/plain:
examples:
Result:
value: ''
'403':
description: '403'
content:
text/plain:
examples:
Result:
value: ''
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl -X DELETE https://api.brandwatch.com/projects/398748937/queries/11554
samples-languages:
- curl
tags:
- Projects
/projects/{projectId}/querygroups:
get:
summary: Query Groups Summary
description: 'Listing the Query Groups that you have created.
You can create Query Groups to represent a relationship between related Queries. They are stored within Projects.'
operationId: retrieving-query-groups-1
parameters:
- name: projectId
in: path
schema:
type: integer
format: int32
required: true
- name: page
in: query
schema:
type: integer
format: int32
default: -1
- name: pageSize
in: query
description: Number of Query Groups shown per page
schema:
type: integer
format: int32
default: -1
- name: ids
in: query
description: Show specified Query Groups using Query Group IDs
schema:
type: array
items:
type: integer
format: int32
- name: includeHidden
in: query
description: Include hidden Query Groups
schema:
type: boolean
default: false
- name: includeActive
in: query
description: Include active Query Groups
schema:
type: boolean
default: true
- name: includeInactive
in: query
description: Include inactive Query Groups
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"resultsTotal\": -1,\n \"resultsPage\": -1,\n \"resultsPageSize\": -1,\n \"results\": [\n {\n \"id\": 165923298,\n \"name\": \"Competitors\",\n \"shared\": \"public\",\n \"sharedProjectIds\": [\n 1494022974\n ],\n \"queries\": [\n {\n \"id\": 39037892,\n \"name\": \"Ikea\"\n },\n {\n \"id\": 49482811,\n \"name\": \"DFS\"\n }\n ],\n \"users\": [\n {\n \"id\": 298473382,\n \"username\": \"example@example.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"uiRole\": \"regular\"\n }\n ]\n }\n ]\n}"
schema:
type: object
properties:
resultsTotal:
type: integer
example: -1
default: 0
resultsPage:
type: integer
example: -1
default: 0
resultsPageSize:
type: integer
example: -1
default: 0
results:
type: array
items:
type: object
properties:
id:
type: integer
example: 165923298
default: 0
name:
type: string
example: Competitors
shared:
type: string
example: public
sharedProjectIds:
type: array
items:
type: integer
example: 1494022974
default: 0
queries:
type: array
items:
type: object
properties:
id:
type: integer
example: 39037892
default: 0
name:
type: string
example: Ikea
users:
type: array
items:
type: object
properties:
id:
type: integer
example: 298473382
default: 0
username:
type: string
example: example@example.com
firstName:
type: string
example: John
lastName:
type: string
example: Doe
uiRole:
type: string
example: regular
'401':
description: '401'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'403':
description: '403'
content:
text/plain:
examples:
Result:
value: ''
'404':
description: '404'
content:
text/plain:
examples:
Result:
value: ''
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl -X GET https://api.brandwatch.com/projects/937893762/querygroups
samples-languages:
- curl
tags:
- Projects
/projects/{projectId}/querygroups/{queryGroupId}:
delete:
summary: Delete Query Groups
description: 'You can delete Query Groups via the Consumer Research API.
Assuming you know the Query Group id that you want to delete, then you can use the following request:'
operationId: deleting-query-groups-1
parameters:
- name: projectId
in: path
schema:
type: integer
format: int32
required: true
- name: queryGroupId
in: path
schema:
type: integer
format: int32
required: true
responses:
'204':
description: '204'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'401':
description: '401'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'403':
description: '403'
content:
text/plain:
examples:
Result:
value: ''
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl -X DELETE https://api.brandwatch.com/projects/398748937/querygroups/18349
samples-languages:
- curl
tags:
- Projects
/projects/{projectId}/tags:
get:
summary: Tags Summary
description: Listing the Tags within your Project.
operationId: retrieving-tags-1
parameters:
- name: projectId
in: path
description: Your [project id](retrieving-projects)
schema:
type: integer
format: int32
required: true
- name: nameContains
in: query
description: Search for Tags with a specified string in their name
schema:
type: string
- name: page
in: query
schema:
type: integer
format: int32
default: -1
- name: pageSize
in: query
description: Choose how many Tags are shown per page
schema:
type: integer
format: int32
default: -1
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"resultsTotal\": -1,\n \"resultsPage\": -1,\n \"resultsPageSize\": -1,\n \"results\": [\n {\n \"id\": 3897282,\n \"name\": \"Celebrities\"\n },\n {\n \"id\": 3472876,\n \"name\": \"Journalists\"\n },\n {\n \"id\": 9879833,\n \"name\": \"Bloggers\"\n },\n {\n \"id\": 7673322,\n \"name\": \"Members of the public\"\n }\n ]\n}"
schema:
type: object
properties:
resultsTotal:
type: integer
example: -1
default: 0
resultsPage:
type: integer
example: -1
default: 0
resultsPageSize:
type: integer
example: -1
default: 0
results:
type: array
items:
type: object
properties:
id:
type: integer
example: 3897282
default: 0
name:
type: st
# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brandwatch/refs/heads/main/openapi/brandwatch-projects-api-openapi.yml