Queries - Create

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

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

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

Sample response

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

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

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

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

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

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.