Queries - Create

Reference

Service:: Work Item Tracking

API Version:: 5.0

Creates a query, or moves a query.

Learn more about Work Item Query Language (WIQL) syntax here.

POST https://dev.azure.com/{organization}/{project}/_apis/wit/queries/{query}?api-version=5.0

URI Parameters

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

Request Body

Name	Type	Description
_links	ReferenceLinks	Link references to related REST resources.
children	QueryHierarchyItem[]	The child query items inside a query folder.
clauses	WorkItemQueryClause	The clauses for a flat query.
columns	WorkItemFieldReference[]	The columns of the query.
createdBy	IdentityReference	The identity who created the query item.
createdDate	string	When the query item was created.
filterOptions	LinkQueryMode	The link query mode.
hasChildren	boolean	If this is a query folder, indicates if it contains any children.
id	string	The id of the query item.
isDeleted	boolean	Indicates if this query item is deleted. Setting this to false on a deleted query item will undelete it. Undeleting a query or folder will not bring back the permission changes that were previously applied to it.
isFolder	boolean	Indicates if this is a query folder or a query.
isInvalidSyntax	boolean	Indicates if the WIQL of this query is invalid. This could be due to invalid syntax or a no longer valid area/iteration path.
isPublic	boolean	Indicates if this query item is public or private.
lastExecutedBy	IdentityReference	The identity who last ran the query.
lastExecutedDate	string	When the query was last run.
lastModifiedBy	IdentityReference	The identity who last modified the query item.
lastModifiedDate	string	When the query item was last modified.
linkClauses	WorkItemQueryClause	The link query clause.
name	string	The name of the query item.
path	string	The path of the query item.
queryRecursionOption	QueryRecursionOption	The recursion option for use in a tree query.
queryType	QueryType	The type of query.
sortColumns	WorkItemQuerySortColumn[]	The sort columns of the query.
sourceClauses	WorkItemQueryClause	The source clauses in a tree or one-hop link query.
targetClauses	WorkItemQueryClause	The target clauses in a tree or one-hop link query.
url	string
wiql	string	The WIQL text of the query

Responses

Name	Type	Description
200 OK	QueryHierarchyItem	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_write	Grants the ability to read, create, and update work items and queries, update board metadata, read area and iterations paths other work item tracking related metadata, execute queries, and to receive notifications about work item events via service hooks.

Examples

Create a folder

Create a query

Move a query or folder

Create a folder

Sample request

HTTP

POST https://dev.azure.com/fabrikam/Fabrikam-Fiber-Git/_apis/wit/queries/{query}?api-version=5.0

{
  "name": "Website team",
  "isFolder": true
}

Sample response

Status code:: 201

{
  "id": "8a8c8212-15ca-41ed-97aa-1d6fbfbcd581",
  "name": "Website team",
  "path": "Shared Queries/Website team",
  "createdBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "createdDate": "2016-06-01T16:58:56.323Z",
  "lastModifiedBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "lastModifiedDate": "2016-06-01T16:58:56.323Z",
  "isFolder": true,
  "hasChildren": false,
  "isPublic": true,
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "html": {
      "href": "https://dev.azure.com/fabrikam/web/qr.aspx?pguid=6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c&qid=8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "parent": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/eb5c1e25-9b3e-4416-a833-e500122882c7"
    }
  },
  "url": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
}

Create a query

Sample request

HTTP

POST https://dev.azure.com/fabrikam/Fabrikam-Fiber-Git/_apis/wit/queries/{query}?api-version=5.0

{
  "name": "All Bugs",
  "wiql": "Select [System.Id], [System.Title], [System.State] From WorkItems Where [System.WorkItemType] = 'Bug' order by [Microsoft.VSTS.Common.Priority] asc, [System.CreatedDate] desc"
}

Sample response

Status code:: 201

{
  "id": "342f0f44-4069-46b1-a940-3d0468979ceb",
  "name": "All Bugs",
  "path": "Shared Queries/Website team/All Bugs",
  "createdBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "createdDate": "2016-06-01T16:58:56.64Z",
  "lastModifiedBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "lastModifiedDate": "2016-06-01T16:58:56.64Z",
  "queryType": "flat",
  "columns": [
    {
      "referenceName": "System.Id",
      "name": "ID",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.Id"
    },
    {
      "referenceName": "System.Title",
      "name": "Title",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.Title"
    },
    {
      "referenceName": "System.State",
      "name": "State",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.State"
    }
  ],
  "sortColumns": [
    {
      "field": {
        "referenceName": "Microsoft.VSTS.Common.Priority",
        "name": "Priority",
        "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/Microsoft.VSTS.Common.Priority"
      },
      "descending": false
    },
    {
      "field": {
        "referenceName": "System.CreatedDate",
        "name": "Created Date",
        "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.CreatedDate"
      },
      "descending": true
    }
  ],
  "wiql": "select [System.Id], [System.Title], [System.State] from WorkItems where [System.WorkItemType] = 'Bug' order by [Microsoft.VSTS.Common.Priority] asc, [System.CreatedDate] desc",
  "isPublic": true,
  "clauses": {
    "field": {
      "referenceName": "System.WorkItemType",
      "name": "Work Item Type",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.WorkItemType"
    },
    "operator": {
      "referenceName": "SupportedOperations.Equals",
      "name": "="
    },
    "value": "Bug"
  },
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/342f0f44-4069-46b1-a940-3d0468979ceb"
    },
    "html": {
      "href": "https://dev.azure.com/fabrikam/web/qr.aspx?pguid=6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c&qid=342f0f44-4069-46b1-a940-3d0468979ceb"
    },
    "parent": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "wiql": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/wiql/342f0f44-4069-46b1-a940-3d0468979ceb"
    }
  },
  "url": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/342f0f44-4069-46b1-a940-3d0468979ceb"
}

Move a query or folder

Sample request

HTTP

POST https://dev.azure.com/fabrikam/Fabrikam-Fiber-Git/_apis/wit/queries/{query}?api-version=5.0

{
  "id": "8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
}

Sample response

Status code:: 200

{
  "id": "8a8c8212-15ca-41ed-97aa-1d6fbfbcd581",
  "name": "Website",
  "path": "My Queries/Website",
  "createdBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "createdDate": "2016-06-01T16:58:56.323Z",
  "lastModifiedBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "lastModifiedDate": "2016-06-01T16:58:59.407Z",
  "isFolder": true,
  "hasChildren": true,
  "isPublic": false,
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "html": {
      "href": "https://dev.azure.com/fabrikam/web/qr.aspx?pguid=6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c&qid=8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "parent": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/3c65fbc1-d427-48ce-9091-633dde9e27e2"
    }
  },
  "url": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
}

Definitions

Name	Description
IdentityReference	Describes a reference to an identity.
LinkQueryMode	The link query mode.
LogicalOperation	Logical operator separating the condition clause
QueryHierarchyItem	Represents an item in the work item query hierarchy. This can be either a query or a folder.
QueryRecursionOption	The recursion option for use in a tree query.
QueryType	The type of query.
ReferenceLinks	The class to represent a collection of REST reference links.
WorkItemFieldOperation	Describes a work item field operation.
WorkItemFieldReference	Reference to a field in a work item
WorkItemQueryClause	Represents a clause in a work item query. This shows the structure of a work item query.
WorkItemQuerySortColumn	A sort column.

IdentityReference

Describes a reference to an identity.

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias	string
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
id	string
imageUrl	string
inactive	boolean
isAadIdentity	boolean
isContainer	boolean
isDeletedInOrigin	boolean
name	string	Legacy back-compat property. This has been the WIT specific value from Constants. Will be hidden (but exists) on the client unless they are targeting the newest version
profileUrl	string
uniqueName	string
url	string	This url is the full route to the source resource of this graph subject.

LinkQueryMode

The link query mode.

Name	Type	Description
linksOneHopDoesNotContain	string	Returns work items that satisfy the source, only if no linked work item satisfies the link and target criteria.
linksOneHopMayContain	string	Returns work items that satisfy the source and link criteria, even if no linked work item satisfies the target criteria.
linksOneHopMustContain	string	Returns work items where the source, target, and link criteria are all satisfied.
linksRecursiveDoesNotContain	string
linksRecursiveMayContain	string	Returns work items a hierarchy of work items that by default satisfy the source
linksRecursiveMustContain	string
workItems	string

LogicalOperation

Logical operator separating the condition clause

Name	Type	Description
aND	string
nONE	string
oR	string

QueryHierarchyItem

Represents an item in the work item query hierarchy. This can be either a query or a folder.

Name	Type	Description
_links	ReferenceLinks	Link references to related REST resources.
children	QueryHierarchyItem[]	The child query items inside a query folder.
clauses	WorkItemQueryClause	The clauses for a flat query.
columns	WorkItemFieldReference[]	The columns of the query.
createdBy	IdentityReference	The identity who created the query item.
createdDate	string	When the query item was created.
filterOptions	LinkQueryMode	The link query mode.
hasChildren	boolean	If this is a query folder, indicates if it contains any children.
id	string	The id of the query item.
isDeleted	boolean	Indicates if this query item is deleted. Setting this to false on a deleted query item will undelete it. Undeleting a query or folder will not bring back the permission changes that were previously applied to it.
isFolder	boolean	Indicates if this is a query folder or a query.
isInvalidSyntax	boolean	Indicates if the WIQL of this query is invalid. This could be due to invalid syntax or a no longer valid area/iteration path.
isPublic	boolean	Indicates if this query item is public or private.
lastExecutedBy	IdentityReference	The identity who last ran the query.
lastExecutedDate	string	When the query was last run.
lastModifiedBy	IdentityReference	The identity who last modified the query item.
lastModifiedDate	string	When the query item was last modified.
linkClauses	WorkItemQueryClause	The link query clause.
name	string	The name of the query item.
path	string	The path of the query item.
queryRecursionOption	QueryRecursionOption	The recursion option for use in a tree query.
queryType	QueryType	The type of query.
sortColumns	WorkItemQuerySortColumn[]	The sort columns of the query.
sourceClauses	WorkItemQueryClause	The source clauses in a tree or one-hop link query.
targetClauses	WorkItemQueryClause	The target clauses in a tree or one-hop link query.
url	string
wiql	string	The WIQL text of the query

QueryRecursionOption

The recursion option for use in a tree query.

Name	Type	Description
childFirst	string	Returns work items that satisfy the target criteria, even if no work item satisfies the source and link criteria.
parentFirst	string	Returns work items that satisfy the source, even if no linked work item satisfies the target and link criteria.

QueryType

The type of query.

Name	Type	Description
flat	string	Gets a flat list of work items.
oneHop	string	Gets a list of work items and their direct links.
tree	string	Gets a tree of work items showing their link hierarchy.

ReferenceLinks

The class to represent a collection of REST reference links.

Name	Type	Description
links	object	The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

WorkItemFieldOperation

Describes a work item field operation.

Name	Type	Description
name	string	Name of the operation.
referenceName	string	Reference name of the operation.

WorkItemFieldReference

Reference to a field in a work item

Name	Type	Description
name	string	The name of the field.
referenceName	string	The reference name of the field.
url	string	The REST URL of the resource.

WorkItemQueryClause

Represents a clause in a work item query. This shows the structure of a work item query.

Name	Type	Description
clauses	WorkItemQueryClause[]	Child clauses if the current clause is a logical operator
field	WorkItemFieldReference	Field associated with condition
fieldValue	WorkItemFieldReference	Right side of the condition when a field to field comparison
isFieldValue	boolean	Determines if this is a field to field comparison
logicalOperator	LogicalOperation	Logical operator separating the condition clause
operator	WorkItemFieldOperation	The field operator
value	string	Right side of the condition when a field to value comparison

WorkItemQuerySortColumn

A sort column.

Name	Type	Description
descending	boolean	The direction to sort by.
field	WorkItemFieldReference	A work item field.

Share via

Queries - Create

URI Parameters

Request Body

Responses

Security

oauth2

Scopes

Examples

Create a folder

Sample request

Sample response

Create a query

Sample request

Sample response

Move a query or folder

Sample request

Sample response

Definitions

IdentityReference

LinkQueryMode

LogicalOperation

QueryHierarchyItem

QueryRecursionOption

QueryType

ReferenceLinks

WorkItemFieldOperation

WorkItemFieldReference

WorkItemQueryClause

WorkItemQuerySortColumn

Additional resources