Work Item Search Results - Fetch Work Item Search Results

Reference

Service:: Search

API Version:: 5.0-preview.1

Provides a set of results for the search text.

POST https://almsearch.dev.azure.com/{organization}/{project}/_apis/search/workitemsearchresults?api-version=5.0-preview.1

URI Parameters

Name	In	Required	Type	Description
organization	path	True	string	The name of the Azure DevOps organization.
project	path		string	Project ID or project name
api-version	query	True	string	Version of the API to use. This should be set to '5.0-preview.1' to use this version of the api.

Request Body

Name	Type	Description
$orderBy	SortOption[]	Options for sorting search results. If set to null, the results will be returned sorted by relevance. If more than one sort option is provided, the results are sorted in the order specified in the OrderBy.
$skip	integer	Number of results to be skipped.
$top	integer	Number of results to be returned.
filters	object	Filters to be applied. Set it to null if there are no filters to be applied.
includeFacets	boolean	Flag to opt for faceting in the result. Default behavior is false.
searchText	string	The search text.

Responses

Name	Type	Description
200 OK	WorkItemSearchResponse	successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.work	Grants the ability to read work items, queries, boards, area and iterations paths, and other work item tracking related metadata. Also grants the ability to execute queries, search work items and to receive notifications about work item events via service hooks.

Examples

Sample request

HTTP

POST https://almsearch.dev.azure.com/fabrikam/_apis/search/workitemsearchresults?api-version=5.0-preview.1

{
  "searchText": "Rest Api Story",
  "$skip": 0,
  "$top": 1,
  "filters": {
    "System.TeamProject": [
      "MyFirstProject"
    ],
    "System.AreaPath": [
      "MyFirstProject"
    ],
    "System.WorkItemType": [
      "Bug",
      "User Story",
      "Feature",
      "Task"
    ],
    "System.State": [
      "New",
      "Active",
      "Closed"
    ],
    "System.AssignedTo": [
      "John Doe <jodoe@microsoft.com>"
    ]
  },
  "$orderBy": [
    {
      "field": "system.id",
      "sortOrder": "ASC"
    }
  ],
  "includeFacets": true
}

Sample response

Status code:: 200

{
  "count": 2,
  "results": [
    {
      "project": {
        "name": "MyFirstProject",
        "id": "5a0690b2-823c-4389-a3ab-5ea2a9cbde75"
      },
      "fields": {
        "system.id": "2",
        "system.workitemtype": "User Story",
        "system.title": "Rest Api User Story",
        "system.assignedto": "John Doe <jodoe@microsoft.com>",
        "system.state": "Closed",
        "system.tags": "api; rest",
        "system.rev": "5",
        "system.createddate": "2018-01-05T17:14:40.033Z",
        "system.changeddate": "2018-01-05T17:55:36.953Z"
      },
      "hits": [
        {
          "fieldReferenceName": "system.tags",
          "highlights": [
            "<highlighthit>api</highlighthit>; <highlighthit>rest</highlighthit>"
          ]
        },
        {
          "fieldReferenceName": "system.title",
          "highlights": [
            "<highlighthit>Rest</highlighthit> <highlighthit>Api</highlighthit> User <highlighthit>Story</highlighthit>"
          ]
        }
      ],
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/2"
    }
  ],
  "infoCode": 0,
  "facets": {
    "System.TeamProject": [
      {
        "name": "MyFirstProject",
        "id": "MyFirstProject",
        "resultCount": 2
      }
    ],
    "System.WorkItemType": [
      {
        "name": "Task",
        "id": "Task",
        "resultCount": 1
      },
      {
        "name": "User Story",
        "id": "User Story",
        "resultCount": 1
      },
      {
        "name": "Bug",
        "id": "Bug",
        "resultCount": 0
      },
      {
        "name": "Feature",
        "id": "Feature",
        "resultCount": 0
      }
    ],
    "System.State": [
      {
        "name": "Closed",
        "id": "Closed",
        "resultCount": 1
      },
      {
        "name": "New",
        "id": "New",
        "resultCount": 1
      },
      {
        "name": "Active",
        "id": "Active",
        "resultCount": 0
      }
    ],
    "System.AssignedTo": [
      {
        "name": "John Doe <jodoe@microsoft.com>",
        "id": "John Doe <jodoe@microsoft.com>",
        "resultCount": 2
      }
    ]
  }
}

Definitions

Name	Description
Project	Defines the details of the project.
SortOption	Defines how to sort the result.
WorkItemHit	Defines the matched terms in the field of the work item result.
WorkItemResult	Defines the work item result that matched a work item search request.
WorkItemSearchRequest	Defines a work item search request.
WorkItemSearchResponse	Defines a response item that is returned for a work item search request.

Project

Defines the details of the project.

Name	Type	Description
id	string	Id of the project.
name	string	Name of the project.

SortOption

Defines how to sort the result.

Name	Type	Description
field	string	Field name on which sorting should be done.
sortOrder	string	Order (ASC/DESC) in which the results should be sorted.

WorkItemHit

Defines the matched terms in the field of the work item result.

Name	Type	Description
fieldReferenceName	string	Reference name of the highlighted field.
highlights	string[]	Matched/highlighted snippets of the field.

WorkItemResult

Defines the work item result that matched a work item search request.

Name	Type	Description
fields	object	A standard set of work item fields and their values.
hits	WorkItemHit[]	Highlighted snippets of fields that match the search request. The list is sorted by relevance of the snippets.
project	Project	Project details of the work item.
url	string	Reference to the work item.

WorkItemSearchRequest

Defines a work item search request.

Name	Type	Description
$orderBy	SortOption[]	Options for sorting search results. If set to null, the results will be returned sorted by relevance. If more than one sort option is provided, the results are sorted in the order specified in the OrderBy.
$skip	integer	Number of results to be skipped.
$top	integer	Number of results to be returned.
filters	object	Filters to be applied. Set it to null if there are no filters to be applied.
includeFacets	boolean	Flag to opt for faceting in the result. Default behavior is false.
searchText	string	The search text.

WorkItemSearchResponse

Defines a response item that is returned for a work item search request.

Name	Type	Description
count	integer	Total number of matched work items.
facets	object	A dictionary storing an array of `Filter` object against each facet.
infoCode	integer	Numeric code indicating any additional information: 0 - Ok, 1 - Account is being reindexed, 2 - Account indexing has not started, 3 - Invalid Request, 4 - Prefix wildcard query not supported, 5 - MultiWords with code facet not supported, 6 - Account is being onboarded, 7 - Account is being onboarded or reindexed, 8 - Top value trimmed to maxresult allowed 9 - Branches are being indexed, 10 - Faceting not enabled, 11 - Work items not accessible, 19 - Phrase queries with code type filters not supported, 20 - Wildcard queries with code type filters not supported. Any other info code is used for internal purpose.
results	WorkItemResult[]	List of top matched work items.

Share via