Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
title: Consumer Research API
version: '2.0'
servers:
- url: https://api.brandwatch.com
components:
securitySchemes:
sec0:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://example.com/oauth2/token
scopes: {}
security:
- sec0: []
paths:
/me:
get:
summary: The Me Call
description: 'Return a combination of User and Client information in one call.
There is a handy combined API call to find out a combination of User and Client information in
one go:'
operationId: the-me-call-1
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": 328973287,\n \"username\": \"example@example.com\",\n \"\
uiRole\": \"user\",\n \"firstName\": \"Wile E.\",\n \"tags\": {\n \"\
notify\": \"true\"\n },\n \"client\": {\n \"id\": 3328928272,\n \
\ \"name\": \"ACME Robotics\",\n \"theme\": \"brandwatch\",\n \"parentId\"\
: -1,\n \"userInactivityTimeoutMinutes\": 1440,\n \"priceStructureName\"\
: \"Legacy\",\n \"queryLimit\": 20000,\n \"mentionLimit\": -1,\n \
\ \"priceStructureLineCost\": 0,\n \"startDate\": \"0024-07-30T00:00:00.000+0000\"\
\n },\n \"crmAccount\": null,\n \"passwordExpiryDate\": null,\n \"creationDate\"\
: \"2016-06-29T16:19:17.744+0000\",\n \"lastName\": \"Coyote\"\n}"
schema:
type: object
properties:
id:
type: integer
example: 328973287
default: 0
username:
type: string
example: example@example.com
uiRole:
type: string
example: user
firstName:
type: string
example: Wile E.
tags:
type: object
properties:
notify:
type: string
example: 'true'
client:
type: object
properties:
id:
type: integer
example: 3328928272
default: 0
name:
type: string
example: ACME Robotics
theme:
type: string
example: brandwatch
parentId:
type: integer
example: -1
default: 0
userInactivityTimeoutMinutes:
type: integer
example: 1440
default: 0
priceStructureName:
type: string
example: Legacy
queryLimit:
type: integer
example: 20000
default: 0
mentionLimit:
type: integer
example: -1
default: 0
priceStructureLineCost:
type: integer
example: 0
default: 0
startDate:
type: string
example: 0024-07-30T00:00:00.000+0000
crmAccount: {}
passwordExpiryDate: {}
creationDate:
type: string
example: 2016-06-29T16:19:17.744+0000
lastName:
type: string
example: Coyote
'401':
description: '401'
content:
application/json:
examples:
Result:
value: "{\n \"error\": \"unauthorized\",\n \"error_description\": \"Invalid authentication\
\ credentials found on request\"\n}"
schema:
type: object
properties:
error:
type: string
example: unauthorized
error_description:
type: string
example: Invalid authentication credentials found on request
'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/me
samples-languages:
- curl
/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
/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
/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
/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
/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
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
/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
# --- truncated at 32 KB (138 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brandwatch/refs/heads/main/openapi/brandwatch-consumer-research-openapi.yml