Search
Guide exposes three different search APIs: the Article and Post search APIs enable you to search for articles and posts respectively, the Unified search API allows you to search across articles, posts and external content in a single query.
You can call the search APIs from a JavaScript client in a domain other than your Help Center. The API implements Cross-Origin Resource Sharing (CORS). CORS lets a JavaScript client access resources in other domains.
JSON format
Search are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
results | array | false | true | An array with the base articles or community posts |
Unified Search
GET /api/v2/guide/search?filter[locales]={filter[locales]}
Use the Unified Search endpoint to search for knowledge base articles, community posts, andexternal records.
Returns a default number of 10 results per page.
The only mandatory parameter isfilter[locales]
. Other parameters can be added to narrow down the search result set.
如果您指定一个无效的区域或地区的s not enabled for any of your account's help centers, no search results are returned. You can check for valid locales with the API. SeeList all enabled locales and default locale.
If thequery
parameter is used, results are sorted by relevance according to the rules described inAbout Help Center End User Search. If thequery
parameter is not used, results are sorted using an internal ordering.
Pagination
This API only supports cursor-based pagination. SeeUsing cursor based paginationin the Help Center API docs. Currently, this API does not support backwards pagination.
Returns a maximum of 50 records per page.
Allowed for
- Authenticated users
- Agents
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
filter[brand_ids] | string | Query | false | Limit the search to articles or posts within these brands. If no brand is specified, results are returned across all brands. If you want to scope the result of your search with multiple brands, separate each value with a comma |
filter[category_ids] | string | Query | false | Limit the search to articles with these category ids. SeeFiltering by Category |
filter[content_types] | string | Query | false | Limit the search to one of these content types: ARTICLE, POST. At present, it is not possible to specifyEXTERNAL_RECORD . Instead, use thefilter[external_source_id] parameter above |
filter[external_source_ids] | string | Query | false | Use this parameter to scope the result of your search to a specific external source or external sources. If no external source is given, results are returned across all sources |
filter[locales] | string | Query | true | Limit the search to these locales. SeeFiltering by Locale |
filter[section_ids] | string | Query | false | Limit the search to articles with these section ids. SeeFiltering by Section |
filter[topic_ids] | string | Query | false | Limit the search to posts within these topics. SeeFiltering by Topic |
page[after] | string | Query | false | A string representing the cursor to the next page. |
page[size] | integer | Query | false | A numeric value that indicates the maximum number of items that can be included in a response. The value of this parameter has an upper limit of 50. The default value is 10. |
query | string | Query | false | The search text to be matched or a search string |
Code Samples
Curl
curl--request GET https://support.zendesk.com/api/v2/guide/search?filter[brand_ids]=73%2C67&filter[category_ids]=42%2C43&filter[content_types]=% 2条cpost&filter[external_source_ids]=01EC05A5T1J4ZSDJX4Q8JGFRHP&filter[locales]=en-us%2Cen-gb&filter[section_ids]=42%2C43&filter[topic_ids]=42%2C43&page[after]=&page[size]=&query=carrot\
--header"Content-Type: application/json"\
-u username:password
a query with password authentication
# Use commas to separate multiple search terms.
# Authorization can be achieved using `email:password`
curl"https://{subdomain}.zendesk.com/api/v2/guide/search?query=Printing&filter[locales]=en-us,en-gb"-g\
-v -u{email_address}:{password}
external source filtering with basic authentication
# You can omit the query term if you just need to apply a filter
# The `Authorization` header can be used to pass a Base 64 encoded Authorization token
curl"https://{subdomain}.zendesk.com/api/v2/guide/search?filter[locales]=en-us&filter[external_source_ids]=01EC05A5T1J4ZSDJX4Q8JGFRHP"-g\
-H"Authorization: Basic {token}"
pagination with basic authentication
# You can use page[size] and page[after] to paginate your result set
curl"https://{subdomain}.zendesk.comapi/v2/guide/search?filter[locales]=en-us&page[size]=2&page[after]=WzEuMCwxNjld"-g\
-H"Authorization: Basic {token}"
Go
import(
"fmt"
"io"
"net/http"
)
funcmain(){
url:="https://support.zendesk.com/api/v2/guide/search?filter[brand_ids]=73%2C67&filter[category_ids]=42%2C43&filter[content_types]=ARTICLE%2CPOST&filter[external_source_ids]=01EC05A5T1J4ZSDJX4Q8JGFRHP&filter[locales]=en-us%2Cen-gb&filter[section_ids]=42%2C43&filter[topic_ids]=42%2C43&page[after]=&page[size]=&query=carrot"
method:="GET"
req,err:=http.NewRequest(method,url,nil)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Basic
" )// Base64 encoded "username:password"client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
importcom.squareup.okhttp.*;
OkHttpClientclient=newOkHttpClient();
HttpUrl.BuilderurlBuilder=HttpUrl.parse("https://support.zendesk.com/api/v2/guide/search")
.newBuilder()
.addQueryParameter("filter[brand_ids]","73,67")
.addQueryParameter("filter[category_ids]","42,43")
.addQueryParameter("filter[content_types]","ARTICLE,POST")
.addQueryParameter("filter[external_source_ids]","01EC05A5T1J4ZSDJX4Q8JGFRHP")
.addQueryParameter("filter[locales]","en-us,en-gb")
.addQueryParameter("filter[section_ids]","42,43")
.addQueryParameter("filter[topic_ids]","42,43")
.addQueryParameter("page[after]","")
.addQueryParameter("page[size]","")
.addQueryParameter("query","carrot");
Request请求=newRequest.Builder()
.url(urlBuilder.build())
.method("GET",null)
.addHeader("Content-Type","application/json")
.addHeader("Authorization",Credentials.basic("your-email","your-password"))
.build();
Responseresponse=client.newCall(请求).execute();
javascript to search external content from a Help Center front-end as a logged in user
constexternalSourceId=""// some source id
constresponse=awaitfetch(
`https://${window.location.hostname}/api/v2/guide/search?filter[locales]=en-us&filter[external_source_ids]=${externalSourceId}`,
{
credentials:'include',
headers:{'Content-Type':'application/json'}
}
);
constdata=awaitresponse.json();
data.results.forEach(something);// do something with the results
Nodejs
varaxios=require('axios');
varconfig={
method:'GET',
url:'https://support.zendesk.com/api/v2/guide/search',
headers:{
'Content-Type':'application/json',
'Authorization':'Basic
' ,// Base64 encoded "username:password"},
params:{
'filter[brand_ids]':'73%2C67',
'filter[category_ids]':'42%2C43',
'filter[content_types]':'ARTICLE%2CPOST',
'filter[external_source_ids]':'01EC05A5T1J4ZSDJX4Q8JGFRHP',
'filter[locales]':'en-us%2Cen-gb',
'filter[section_ids]':'42%2C43',
'filter[topic_ids]':'42%2C43',
'page[after]':'',
'page[size]':'',
'query':'carrot',
},
};
axios(config)
.then(function(response){
console.log(JSON.stringify(response.data));
})
.catch(function(error){
console.log(error);
});
Python
import请求s
url="https://support.zendesk.com/api/v2/guide/search?filter[brand_ids]=73%2C67&filter[category_ids]=42%2C43&filter[content_types]=ARTICLE%2CPOST&filter[external_source_ids]=01EC05A5T1J4ZSDJX4Q8JGFRHP&filter[locales]=en-us%2Cen-gb&filter[section_ids]=42%2C43&filter[topic_ids]=42%2C43&page[after]=&page[size]=&query=carrot"
headers={
"Content-Type":"application/json",
}
response=请求s.请求(
"GET",
url,
auth=('
' ,'' ),headers=headers
)
print(response.text)
Ruby
require"net/http"
uri=URI("https://support.zendesk.com/api/v2/guide/search")
uri.query=URI.encode_www_form("filter[brand_ids]":"73,67","filter[category_ids]":"42,43","filter[content_types]":"ARTICLE,POST","filter[external_source_ids]":"01EC05A5T1J4ZSDJX4Q8JGFRHP","filter[locales]":"en-us,en-gb","filter[section_ids]":"42,43","filter[topic_ids]":"42,43","page[after]":"","page[size]":"","query":"carrot")
请求=Net::HTTP::Get.new(uri,"Content-Type":"application/json")
请求.basic_auth"username","password"
response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|
http.请求(请求)
end
Example response(s)
200 OK
// Status 200 OK
{
"meta":{
"after_cursor":"WzEuMCwxNjld",
"before_cursor":"WzEuMCwxNjhd",
"has_more":true
},
"results":[
{
"title":"How to make fish stew",
"type":"ARTICLE",
"updated_at":"2021-10-11T15:02:22Z",
"url":“http://example.亚博zendesk.com/hc/en-us/articles/38393937-How-to-make-fish-stew"
},
{
"title":"Latest updates on fish stew",
"type":"EXTERNAL_RECORD",
"updated_at":"2021-11-12T15:02:22Z",
"url":"http://example.com/blog/fish-stew-latest"
}
]
}
Search Articles
GET /api/v2/help_center/articles/search
Returns a default number of 25 articles per page, up to a maximum of 1000 results. SeePagination. Theper_page
parameter, if provided, must be an integer between 1 and 100.
Thepage
parameter, if provided, must be an integer greater than 0.
The results are sorted by relevance by default. You can also sort the results bycreated_at
orupdated_at
.
Thearticle objectsreturned by the search endpoint contain two additional properties:
Name | Type | Read-only | Mandatory | Comment |
---|---|---|---|---|
result_type | string | yes | no | For articles, always the string "article" |
片段 | string | yes | no | The portion of an article that is relevant to the search query, with matching words or phrases delimited by tags. Example: a query for "carrot potato" might return the snippet "...don't confuse carrots with potatoes ..." |
You must specify at least one of the following parameters in your request:
- query
- category
- section
- label_names
Pagination
- Offset pagination only
SeePagination.
Returns a maximum of 100 articles per page.
Allowed for
- Anonymous users
Filtering by Date
You can filter the search results by the creation or update date with the following parameters:
- created_before
- created_after
- created_at
- updated_before
- updated_after
- updated_at
GET /api/v2/help_center/articles/search.json?query={search_string}&updated_after=2014-01-01&updated_before=2014-02-01
When filtering byupdated_*
, the results might not always match theupdated_at
timestamps for the documents returned. The reason is that not all updates are propagated to the search index. Only updates that are meaningful for search, such as content changes, are re-indexed. As a result, it's possible for an article to have anupdated_at
timestamp of "2019-10-31" but be returned in a search with the filterupdated_before=2019-08-01
if no meaningful content changes have been made to the article.
Filtering by Labels
If you want to search for articles with specific labels, use thelabel_names
parameter and pass a comma-separated list of label names to filter the results:
GET /api/v2/help_center/articles/search.json?label_names=photos,camera
An article must have at least one of the labels to match. Also, matching is not case-sensitive. For example, 'camera' matches both 'Camera' and 'camera'.
This feature is only available on Professional and Enterprise.
Filtering by Locale
By default, searches are carried out in the default language specified in the Help Center settings. Use thelocale
parameter to search for articles in another language.
GET /api/v2/help_center/articles/search.json?query={search_string}&locale={locale}
如果您指定一个无效的区域或地区的s not enabled for Help Center, the default locale for the account is used for the search. You can check for valid locales with the API. SeeList all enabled locales and default locale.
If you uselocale=*
, search is carried out across all valid locales and returns all article translations in all languages, that match the search criteria.
Filtering by Category
If you want to scope the result of your search within a given category, use thecategory
parameter.
GET /api/v2/help_center/articles/search.json?query={search_string}&category={category_id}
If you want to scope the result of your search with multiple categories, use thecategory
parameter as above and separate each value with a comma.
GET /api/v2/help_center/articles/search.json?query={search_string}&category={category_id},{another_category_id}
Filtering by Section
If you want to scope the result of your search within a given section, use thesection
parameter.
GET /api/v2/help_center/articles/search.json?query={search_string}§ion={section id}
If you want to scope the result of your search with multiple sections, usesection
parameter as above and separate each value with a comma.
GET /api/v2/help_center/articles/search.json?query={search_string}§ion={section_id},{another_section_id}
Filtering by Brand
Use themultibrand
parameter to search across all brands, orbrand_id
to scope the result of your search to a specific brand.
GET /api/v2/help_center/articles/search.json?query={search_string}&brand_id={brand_id}
GET /api/v2/help_center/articles/search.json?query={search_string}&multibrand=true
If you usemultibrand=true
in your request and nobrand_id
, search will return results from all brands that match the query criteria. If you usebrand_id
in your request, the search results will be scoped to the specified brand, regardless of the use of themultibrand
parameter.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
brand_id | integer | Query | false | Search for articles in the specified brand. |
category | integer | Query | false | Limit the search to this category id. SeeFiltering by Category |
created_after | string | Query | false | Limit the search to articles created after a given date (format YYYY-MM-DD). |
created_at | string | Query | false | Limit the search to articles created on a given date (format YYYY-MM-DD). |
created_before | string | Query | false | Limit the search to articles created before a given date (format YYYY-MM-DD). |
label_names | string | Query | false | A comma-separated list of label names. SeeFiltering by Labels |
locale | string | Query | false | Search for articles in the specified locale. SeeFiltering by Locale |
multibrand | boolean | Query | false | Enable search across all brands if true. Defaults to false if omitted. |
query | string | Query | false | The search text to be matched or a search string. Examples: "carrot potato", "'carrot potato'". |
section | integer | Query | false | Limit the search to this section id. SeeFiltering by Section |
sort_by | string | Query | false | One of created_at or updated_at. Defaults to sorting by relevance |
sort_order | string | Query | false | One of asc or desc. Defaults to desc |
updated_after | string | Query | false | Limit the search to articles updated after a given date (format YYYY-MM-DD). |
updated_at | string | Query | false | Limit the search to articles updated on a given date (format YYYY-MM-DD). |
updated_before | string | Query | false | Limit the search to articles updated before a given date (format YYYY-MM-DD). |
Code Samples
curl
# If using the command line, use commas to separate multiple search terms. Example:
# search.json?query=print,orders
curl"https://{subdomain}.zendesk.com/api/v2/help_center/articles/search.json?query=Printing&updated_after=2014-01-01&updated_before=2014-02-01"\
-v -u{email_address}:{password}
Go
import(
"fmt"
"io"
"net/http"
)
funcmain(){
url:="https://support.zendesk.com/api/v2/help_center/articles/search?brand_id=&category=&created_after=&created_at=&created_before=&label_names=&locale=&multibrand=&query=§ion=&sort_by=&sort_order=&updated_after=&updated_at=&updated_before="
method:="GET"
req,err:=http.NewRequest(method,url,nil)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Basic
" )// Base64 encoded "username:password"client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
importcom.squareup.okhttp.*;
OkHttpClientclient=newOkHttpClient();
HttpUrl.BuilderurlBuilder=HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/articles/search")
.newBuilder()
.addQueryParameter("brand_id","")
.addQueryParameter("category","")
.addQueryParameter("created_after","")
.addQueryParameter("created_at","")
.addQueryParameter("created_before","")
.addQueryParameter("label_names","")
.addQueryParameter("locale","")
.addQueryParameter("multibrand","")
.addQueryParameter("query","")
.addQueryParameter("section","")
.addQueryParameter("sort_by","")
.addQueryParameter("sort_order","")
.addQueryParameter("updated_after","")
.addQueryParameter("updated_at","")
.addQueryParameter("updated_before","");
Request请求=newRequest.Builder()
.url(urlBuilder.build())
.method("GET",null)
.addHeader("Content-Type","application/json")
.addHeader("Authorization",Credentials.basic("your-email","your-password"))
.build();
Responseresponse=client.newCall(请求).execute();
Nodejs
varaxios=require('axios');
varconfig={
method:'GET',
url:'https://support.zendesk.com/api/v2/help_center/articles/search',
headers:{
'Content-Type':'application/json',
'Authorization':'Basic
' ,// Base64 encoded "username:password"},
params:{
'brand_id':'',
'category':'',
'created_after':'',
'created_at':'',
'created_before':'',
'label_names':'',
'locale':'',
'multibrand':'',
'query':'',
'section':'',
'sort_by':'',
'sort_order':'',
'updated_after':'',
'updated_at':'',
'updated_before':'',
},
};
axios(config)
.then(function(response){
console.log(JSON.stringify(response.data));
})
.catch(function(error){
console.log(error);
});
Python
import请求s
url="https://support.zendesk.com/api/v2/help_center/articles/search?brand_id=&category=&created_after=&created_at=&created_before=&label_names=&locale=&multibrand=&query=§ion=&sort_by=&sort_order=&updated_after=&updated_at=&updated_before="
headers={
"Content-Type":"application/json",
}
response=请求s.请求(
"GET",
url,
auth=('
' ,'' ),headers=headers
)
print(response.text)
Ruby
require"net/http"
uri=URI("https://support.zendesk.com/api/v2/help_center/articles/search")
uri.query=URI.encode_www_form("brand_id":"","category":"","created_after":"","created_at":"","created_before":"","label_names":"","locale":"","multibrand":"","query":"","section":"","sort_by":"","sort_order":"","updated_after":"","updated_at":"","updated_before":"")
请求=Net::HTTP::Get.new(uri,"Content-Type":"application/json")
请求.basic_auth"username","password"
response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|
http.请求(请求)
end
Example response(s)
200 OK
// Status 200 OK
{
"results":[
{
"author_id":888887,
"draft":false,
"id":35467,
"locale":"en",
"permission_group_id":123,
"title":"Printing orders",
"user_segment_id":12
}
]
}
Search Posts
GET /api/v2/help_center/community_posts/search?query={query}
Returns a maximum of 25 posts per page, up to a maximum of 1000 results. SeePagination.
The results are sorted by relevance by default. You can also sort the results bycreated_at
orupdated_at
.
Pagination
- Offset pagination only
SeePagination.
Returns a maximum of 100 articles per page.
Allowed for
- End users
Filtering by Date
You can filter the search results by the creation or update date with the following parameters:
- created_before
- created_after
- created_at
- updated_before
- updated_after
- updated_at
GET /api/v2/community/posts/search.json?query={search_string}&updated_after=2014-01-01&updated_before=2014-02-01
Filtering by Topic
If you want to scope the result of your search within a given topic, use thetopic
parameter.
GET /api/v2/community/posts/search.json?query={search_string}&topic={topic id}
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
created_after | string | Query | false | Search posts created after a given date (format YYYY-MM-DD) |
created_at | string | Query | false | Search posts created on a given date (format YYYY-MM-DD) |
created_before | string | Query | false | the search to posts created before a given date (format YYYY-MM-DD) |
query | string | Query | true | Search text to be matched or a search string. Examples: "carrot potato", "''carrot potato''"' |
sort_by | string | Query | false | Sort bycreated_at orupdated_at . Defaults to sorting by relevance |
sort_order | string | Query | false | Sort in ascending or descending order. Default is descending order. |
topic | integer | Query | false | Search by topic ID. SeeFiltering by Topic |
updated_after | string | Query | false | 搜索帖子更新工程r a given date (format YYYY-MM-DD) |
updated_at | string | Query | false | Search posts updated on a given date (format YYYY-MM-DD) |
updated_before | string | Query | false | Search posts updated before a given date (format YYYY-MM-DD) |
Code Samples
curl
# If using the command line, use commas to separate multiple search terms. Example:
# search.json?query=print,orders
curl"https://{subdomain}.zendesk.com/api/v2/help_center/community_posts/search.json?query={search_string}"\
-v -u{email_address}:{password}
Go
import(
"fmt"
"io"
"net/http"
)
funcmain(){
url:="https://support.zendesk.com/api/v2/help_center/community_posts/search?created_after=&created_at=&created_before=&query=help+center&sort_by=&sort_order=&topic=&updated_after=&updated_at=&updated_before="
method:="GET"
req,err:=http.NewRequest(method,url,nil)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Basic
" )// Base64 encoded "username:password"client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
importcom.squareup.okhttp.*;
OkHttpClientclient=newOkHttpClient();
HttpUrl.BuilderurlBuilder=HttpUrl.parse("https://support.zendesk.com/api/v2/help_center/community_posts/search")
.newBuilder()
.addQueryParameter("created_after","")
.addQueryParameter("created_at","")
.addQueryParameter("created_before","")
.addQueryParameter("query",“帮助中心”)
.addQueryParameter("sort_by","")
.addQueryParameter("sort_order","")
.addQueryParameter("topic","")
.addQueryParameter("updated_after","")
.addQueryParameter("updated_at","")
.addQueryParameter("updated_before","");
Request请求=newRequest.Builder()
.url(urlBuilder.build())
.method("GET",null)
.addHeader("Content-Type","application/json")
.addHeader("Authorization",Credentials.basic("your-email","your-password"))
.build();
Responseresponse=client.newCall(请求).execute();
Nodejs
varaxios=require('axios');
varconfig={
method:'GET',
url:'https://support.zendesk.com/api/v2/help_center/community_posts/search',
headers:{
'Content-Type':'application/json',
'Authorization':'Basic
' ,// Base64 encoded "username:password"},
params:{
'created_after':'',
'created_at':'',
'created_before':'',
'query':'help+center',
'sort_by':'',
'sort_order':'',
'topic':'',
'updated_after':'',
'updated_at':'',
'updated_before':'',
},
};
axios(config)
.then(function(response){
console.log(JSON.stringify(response.data));
})
.catch(function(error){
console.log(error);
});
Python
import请求s
url="https://support.zendesk.com/api/v2/help_center/community_posts/search?created_after=&created_at=&created_before=&query=help+center&sort_by=&sort_order=&topic=&updated_after=&updated_at=&updated_before="
headers={
"Content-Type":"application/json",
}
response=请求s.请求(
"GET",
url,
auth=('
' ,'' ),headers=headers
)
print(response.text)
Ruby
require"net/http"
uri=URI("https://support.zendesk.com/api/v2/help_center/community_posts/search")
uri.query=URI.encode_www_form("created_after":"","created_at":"","created_before":"","query":“帮助中心”,"sort_by":"","sort_order":"","topic":"","updated_after":"","updated_at":"","updated_before":"")
请求=Net::HTTP::Get.new(uri,"Content-Type":"application/json")
请求.basic_auth"username","password"
response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|
http.请求(请求)
end
Example response(s)
200 OK
// Status 200 OK
{
"results":[
{
"author_id":4333787,
"id":4212256,
"title":"How do I make a return?"
}
]
}