Work Items - Create

Creates a single work item.

POST https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/${type}?api-version=7.1
POST https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/${type}?validateOnly={validateOnly}&bypassRules={bypassRules}&suppressNotifications={suppressNotifications}&$expand={$expand}&api-version=7.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

api-version
query True

string

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

$expand
query

WorkItemExpand

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

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

validateOnly
query

boolean

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

Request Body

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

Name Type Description
from

string

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

op

Operation

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

WorkItem

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=7.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

Name Description
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

Operation

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

ReferenceLinks

Link references to related REST resources.

commentVersionRef

WorkItemCommentVersionRef

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

WorkItemRelation[]

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.