Work Item Search Results - Fetch Work Item Search Results

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

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

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

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

{
  "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

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

Highlighted snippets of fields that match the search request. The list is sorted by relevance of the snippets.

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

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

List of top matched work items.