Work Items - Create

Creates a single work item.

POST https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/${type}?api-version=5.1
POST https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/${type}?validateOnly={validateOnly}&bypassRules={bypassRules}&suppressNotifications={suppressNotifications}&$expand={$expand}&api-version=5.1

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

type
path True
  • string

The work item type of the work item to create

validateOnly
query
  • boolean

Indicate if you only want to validate the changes without saving the work item

bypassRules
query
  • boolean

Do not enforce the work item type rules on this update

suppressNotifications
query
  • boolean

Do not fire any notifications for this change

$expand
query

The expand parameters for work item attributes. Possible options are { None, Relations, Fields, Links, All }.

api-version
query True
  • string

Version of the API to use. This should be set to '5.1' to use this version of the api.

Request Body

Media Types: "application/json-patch+json"

Name Type Description
from
  • string

The path to copy from for the Move/Copy operation.

op

The patch operation

path
  • string

The path for the operation. In the case of an array, a zero based index can be used to specify the position in the array (e.g. /biscuits/0/name). The "-" character can be used instead of an index to insert at the end of the array (e.g. /biscuits/-).

value
  • object

The value for the operation. This is either a primitive or a JToken.

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_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 work item

Sample Request

POST https://dev.azure.com/fabrikam/{project}/_apis/wit/workitems/${type}?api-version=5.1
[
  {
    "op": "add",
    "path": "/fields/System.Title",
    "from": null,
    "value": "Sample task"
  }
]

Sample Response

{
  "id": 131489,
  "rev": 1,
  "fields": {
    "System.AreaPath": "CustomProcessPrj",
    "System.TeamProject": "CustomProcessPrj",
    "System.IterationPath": "CustomProcessPrj",
    "System.WorkItemType": "Task",
    "System.State": "New",
    "System.Reason": "New",
    "System.CreatedDate": "2017-10-06T01:04:51.57Z",
    "System.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"
    },
    "System.ChangedDate": "2017-10-06T01:04:51.57Z",
    "System.ChangedBy": {
      "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"
    },
    "System.Title": "Sample task",
    "Microsoft.VSTS.Common.StateChangeDate": "2017-10-06T01:04:51.57Z",
    "Microsoft.VSTS.Common.Priority": 2
  },
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/_apis/wit/workItems/131489"
    },
    "workItemUpdates": {
      "href": "https://dev.azure.com/fabrikam/_apis/wit/workItems/131489/updates"
    },
    "workItemRevisions": {
      "href": "https://dev.azure.com/fabrikam/_apis/wit/workItems/131489/revisions"
    },
    "workItemHistory": {
      "href": "https://dev.azure.com/fabrikam/_apis/wit/workItems/131489/history"
    },
    "html": {
      "href": "https://dev.azure.com/fabrikam/web/wi.aspx?pcguid=20cda608-32f0-4e6e-9b7c-8def7b38d15a&id=131489"
    },
    "workItemType": {
      "href": "https://dev.azure.com/fabrikam/aaee31d9-14cf-48b9-a92b-3f1446c13f80/_apis/wit/workItemTypes/Task"
    },
    "fields": {
      "href": "https://dev.azure.com/fabrikam/_apis/wit/fields"
    }
  },
  "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/131489"
}

Definitions

JsonPatchDocument

The JSON model for JSON Patch Operations

Operation

The patch operation

ReferenceLinks

The class to represent a collection of REST reference links.

WorkItem

Describes a work item.

WorkItemCommentVersionRef

Represents the reference to a specific version of a comment on a Work Item.

WorkItemExpand

The expand parameters for work item attributes. Possible options are { None, Relations, Fields, Links, All }

WorkItemRelation

JsonPatchDocument

The JSON model for JSON Patch Operations

Name Type Description
from
  • string

The path to copy from for the Move/Copy operation.

op

The patch operation

path
  • string

The path for the operation. In the case of an array, a zero based index can be used to specify the position in the array (e.g. /biscuits/0/name). The "-" character can be used instead of an index to insert at the end of the array (e.g. /biscuits/-).

value
  • object

The value for the operation. This is either a primitive or a JToken.

Operation

The patch operation

Name Type Description
add
  • string
copy
  • string
move
  • string
remove
  • string
replace
  • string
test
  • string

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.

WorkItem

Describes a work item.

Name Type Description
_links

Link references to related REST resources.

commentVersionRef

Reference to a specific version of the comment added/edited/deleted in this revision.

fields
  • object

Map of field and values for the work item.

id
  • integer

The work item ID.

relations

Relations of the work item.

rev
  • integer

Revision number of the work item.

url
  • string

WorkItemCommentVersionRef

Represents the reference to a specific version of a comment on a Work Item.

Name Type Description
commentId
  • integer

The id assigned to the comment.

createdInRevision
  • integer

[Internal] The work item revision where this comment was originally added.

isDeleted
  • boolean

[Internal] Specifies whether comment was deleted.

text
  • string

[Internal] The text of the comment.

url
  • string
version
  • integer

The version number.

WorkItemExpand

The expand parameters for work item attributes. Possible options are { None, Relations, Fields, Links, All }

Name Type Description
all
  • string

Expands all.

fields
  • string

Fields work item expand.

links
  • string

Links work item expand.

none
  • string

Default behavior.

relations
  • string

Relations work item expand.

WorkItemRelation

Name Type Description
attributes
  • object

Collection of link attributes.

rel
  • string

Relation type.

url
  • string

Link url.