Search Data
Searches across Kintone, including App records and Thread posts.
| Method | POST |
|---|---|
| URL | https://{subdomain}.kintone.com/k/v1/search.json |
| URL (search all guest spaces the user is a member of) | https://{subdomain}.kintone.com/k/guest/v1/search.json |
| URL (search a specific guest space) | https://{subdomain}.kintone.com/k/guest/{GUEST_SPACE_ID}/v1/search.json |
| Authentication | Password Authentication , Session Authentication |
| Content-Type | application/json |
Contents
Permissions
- No permissions are needed.
- The search only covers data that the authenticated user has permission to view.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | Array | Yes | The search conditions. Specify between 1 and 20 conditions. If multiple conditions are specified, data that meets all conditions is returned. |
| query[].operator | String | Yes | How the search condition is evaluated. Specify one of the following values:
query contains no conditions that use AND or OR. |
| query[].keywords | Array | Yes | An array of keywords. Specify between 1 and 20 keywords. Each keyword must be between 1 and 50 characters. The maximum limit is 20 keywords across the entire query. The request will fail if this limit is exceeded. |
| types | Array | Optional | The types of data to search. Specify any of the following values:
|
| scopes | Array | Optional | The search scopes. The maximum limit is 20 scopes. If multiple scopes are specified, data that meets any of the scopes is returned. |
| scopes[].scope | String | Yes | The type of search scope. Specify one of the following values:
scopes is specified. |
| scopes[].ids | Array | Optional | The App IDs or Space IDs. The maximum limit is 20 IDs. If scopes[].scope is APP or SPACE, specify App IDs or Space IDs to limit the search scope to those Apps or Spaces. If ignored, all Apps or all Spaces are searched.This parameter cannot be specified if scopes[].scope is PEOPLE or MESSAGE. |
| scopes[].codes | Array | Optional | The log in names of users. The maximum limit is 20 log in names. If scopes[].scope is PEOPLE or MESSAGE, specify the log in names of People owners or Message partners. This limits the search scope to those People or Messages. If ignored, all People or all Messages are searched.This parameter cannot be specified if scopes[].scope is APP or SPACE. |
| excludeScopes | Array | Optional | The scopes to exclude from the search. The maximum limit is 20 scopes. If multiple scopes are specified, data that meets all conditions is returned. If both scopes and excludeScopes are specified, data that meets both conditions is returned. Therefore, excludeScopes takes priority where the two scopes overlap. |
| excludeScopes[].scope | String | Yes | The type of search scope to exclude. Specify one of the following values:
excludeScopes is specified. |
| excludeScopes[].ids | Array | Optional | The App IDs or Space IDs. The maximum limit is 20 IDs. If excludeScopes[].scope is APP or SPACE, specify App IDs or Space IDs to exclude those Apps or Spaces from the search scope. If ignored, all Apps or all Spaces are excluded.This parameter cannot be specified if excludeScopes[].scope is PEOPLE or MESSAGE. |
| excludeScopes[].codes | Array | Optional | The log in names of users. The maximum limit is 20 log in names. If excludeScopes[].scope is PEOPLE or MESSAGE, specify the log in names of People owners or Message partners. This excludes those People or Messages from the search scope. If ignored, all People or all Messages are excluded.This parameter cannot be specified if excludeScopes[].scope is APP or SPACE. |
| createdAfter | String | Optional | The earliest created datetime. Returns data created on or after the specified datetime. This value cannot be later than createdBefore.For more information on the datetime format, refer to the Kintone REST API Overview article. |
| createdBefore | String | Optional | The latest created datetime. Returns data created on or before the specified datetime. This value cannot be earlier than createdAfter.For more information on the datetime format, refer to the Kintone REST API Overview article. |
| creators | Array | Optional | The log in names of the creators. The maximum limit is 20 log in names. |
| includeSynonyms | Boolean or String | Optional | Whether to include spelling variations, abbreviations, and synonyms of the keywords in the search. If ignored, this value is false. |
| sort | Object | Optional | The sort conditions. |
| sort.by | String | Optional | The sort criteria. Specify one of the following values:
RELEVANCE. |
| sort.order | String | Optional | The sort direction. Specify one of the following values:
DESC.ASC cannot be specified if sort.by is RELEVANCE. |
| limit | Integer or String | Optional | The maximum number of results to retrieve. Specify a value between 1 and 20. If ignored, this value is 20.The response may contain fewer results than the limit, even if more matching data remains. Use the nextPageToken property in the response to check whether more matching data remains. |
| pageToken | String | Optional | The token used to retrieve the next page of search results. Ignore this parameter in the first request. To retrieve the next page, specify the nextPageToken value from the previous response.The token expires 30 minutes after it is issued. The request will fail if an expired token is specified. |
Sample Request
Request Body (Multiple Keywords)
This request body searches for data that contains both abc and def.
|
|
Request Body (Excluded Keywords)
This request body searches for data that contains abc but does not contain def.
|
|
Request Body (Specified Apps)
This request body searches App 1 and App 2 for attachments that contain abc.
|
|
Request Body (Specified Space)
This request body searches Space 1 for data that contains abc. Data in App 2, which is in Space 1, is excluded.
|
|
Request Body (Specified Period)
This request body searches for data created by user1 within a specific period. The results are sorted by created datetime in ascending order.
|
|
JavaScript using kintone.api()
For more information on kintone.api(), refer to the
Kintone REST API Request
article.
|
|
curl Sample
The curl format may vary depending on the environment.
|
|
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| hits | Array | The search results. |
| hits[].type | String | The type of search result. One of the following values is returned:
|
| hits[].url | String | The URL. If the search result is an attachment, this is the URL of the location the file is attached to. |
| hits[].snippets | Array | The text surrounding the keywords. Up to 3 snippets are returned. |
| hits[].record | Object | The record information. Only included if the search result is a record or a file attached to a record. |
| hits[].record.appId | String | The App ID. |
| hits[].record.appName | String | The App name. |
| hits[].record.recordId | String | The record ID. |
| hits[].record.recordTitle | String | The record title. |
| hits[].record.createdAt | String | The created datetime.null is returned if the user does not have view permission for the Created datetime field. |
| hits[].record.creator | Object | The creator.null is returned if the user does not have view permission for the Created by field. |
| hits[].record.creator.code | String | The log in name of the creator. |
| hits[].record.creator.name | String | The display name of the creator. |
| hits[].record.matchedFields | Array | The fields that matched the keywords. |
| hits[].record.matchedFields[].code | String | The field code. |
| hits[].record.matchedFields[].label | String | The field name. |
| hits[].record.spaceId | String | The Space ID.null is returned if the record is not in a Space App. |
| hits[].record.spaceName | String | The Space name.null is returned if the record is not in a Space App. |
| hits[].recordComment | Object | The record comment information. Only included if the search result is a record comment. |
| hits[].recordComment.appId | String | The App ID. |
| hits[].recordComment.appName | String | The App name. |
| hits[].recordComment.recordId | String | The record ID. |
| hits[].recordComment.recordTitle | String | The record title. |
| hits[].recordComment.commentId | String | The comment ID. |
| hits[].recordComment.createdAt | String | The created datetime. |
| hits[].recordComment.creator | Object | The creator. |
| hits[].recordComment.creator.code | String | The log in name of the creator. |
| hits[].recordComment.creator.name | String | The display name of the creator. |
| hits[].recordComment.spaceId | String | The Space ID.null is returned if the record is not in a Space App. |
| hits[].recordComment.spaceName | String | The Space name.null is returned if the record is not in a Space App. |
| hits[].space | Object | The Space information. Only included if the search result is a Space or a file attached to a Space. |
| hits[].space.spaceId | String | The Space ID. |
| hits[].space.spaceName | String | The Space name. |
| hits[].space.createdAt | String | The created datetime. |
| hits[].space.creator | Object | The creator. |
| hits[].space.creator.code | String | The log in name of the creator. |
| hits[].space.creator.name | String | The display name of the creator. |
| hits[].thread | Object | The Thread information. Only included if the search result is a Thread or a file attached to a Thread. |
| hits[].thread.threadId | String | The Thread ID. |
| hits[].thread.threadName | String | The Thread name. |
| hits[].thread.spaceId | String | The Space ID. |
| hits[].thread.spaceName | String | The Space name. |
| hits[].thread.createdAt | String | The created datetime. |
| hits[].thread.creator | Object | The creator. |
| hits[].thread.creator.code | String | The log in name of the creator. |
| hits[].thread.creator.name | String | The display name of the creator. |
| hits[].threadComment | Object | The Thread comment information. Only included if the search result is a Thread comment or a file attached to a Thread comment. |
| hits[].threadComment.commentId | String | The comment ID. |
| hits[].threadComment.replyId | String | The reply ID.null is returned if the search result is not a reply. |
| hits[].threadComment.spaceId | String | The Space ID. |
| hits[].threadComment.spaceName | String | The Space name. |
| hits[].threadComment.threadId | String | The Thread ID. |
| hits[].threadComment.threadName | String | The Thread name. |
| hits[].threadComment.createdAt | String | The created datetime. |
| hits[].threadComment.creator | Object | The creator. |
| hits[].threadComment.creator.code | String | The log in name of the creator. |
| hits[].threadComment.creator.name | String | The display name of the creator. |
| hits[].peopleComment | Object | The People comment information. Only included if the search result is a People comment or a file attached to a People comment. |
| hits[].peopleComment.commentId | String | The comment ID. |
| hits[].peopleComment.replyId | String | The reply ID.null is returned if the search result is not a reply. |
| hits[].peopleComment.owner | Object | The owner of the People. |
| hits[].peopleComment.owner.code | String | The log in name of the People owner. |
| hits[].peopleComment.owner.name | String | The display name of the People owner. |
| hits[].peopleComment.createdAt | String | The created datetime. |
| hits[].peopleComment.creator | Object | The creator. |
| hits[].peopleComment.creator.code | String | The log in name of the creator. |
| hits[].peopleComment.creator.name | String | The display name of the creator. |
| hits[].messageComment | Object | The Message comment information. Only included if the search result is a Message comment or a file attached to a Message comment. |
| hits[].messageComment.commentId | String | The comment ID. |
| hits[].messageComment.createdAt | String | The created datetime. |
| hits[].messageComment.creator | Object | The creator. This is the user who posted the comment. |
| hits[].messageComment.creator.code | String | The log in name of the creator. |
| hits[].messageComment.creator.name | String | The display name of the creator. |
| hits[].messageComment.recipient | Object | The recipient of the comment. This is the Message participant who is not the creator. |
| hits[].messageComment.recipient.code | String | The log in name of the recipient. |
| hits[].messageComment.recipient.name | String | The display name of the recipient. |
| hits[].attachment | Object | The attachment information. Only included if the search result is an attachment. |
| hits[].attachment.attachedTo | String | The type of location the file is attached to. One of the following values is returned:
|
| hits[].attachment.fileKey | String | The file key. |
| hits[].attachment.name | String | The file name. |
| hits[].attachment.createdAt | String | The created datetime. For files attached to records, null is returned if the user does not have view permission for the Created datetime field. |
| hits[].attachment.creator | Object | The creator. For files attached to records, null is returned if the user does not have view permission for the Created by field. |
| hits[].attachment.creator.code | String | The log in name of the creator. |
| hits[].attachment.creator.name | String | The display name of the creator. |
| nextPageToken | String | The token used to retrieve the next page of search results. Specify this value in the pageToken request parameter to request the next page.null is returned if there is no next page. |
Sample Response
|
|
Limitations
- Requests to
/k/v1/search.jsonalso search guest spaces that the user is a member of. Guest users cannot send requests to this URL. - Requests to
/k/guest/v1/search.jsononly search guest spaces that the user is a member of. - Requests to
/k/guest/{GUEST_SPACE_ID}/v1/search.jsononly search the specified guest space. The search result will be empty if the user is not a member of the guest space or the guest space does not exist. - Search improvements may change the data included in the search results, the order of the results, and the content of
hits[].snippets. - The maximum limit is 600 requests per minute per domain. If this limit is exceeded, an error response with HTTP status code 429 is returned.