Pull Request Threads - Create

Create a thread in a pull request.

POST https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullRequests/{pullRequestId}/threads?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

repositoryId
path True
  • string

Repository ID of the pull request's target branch.

pullRequestId
path True
  • integer
int32

ID of the pull request.

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
_links

Links to other related objects.

comments

A list of the comments.

id
  • integer

The comment thread id.

identities

Set of identities related to this thread

isDeleted
  • boolean

Specify if the thread is deleted which happens when all comments are deleted.

lastUpdatedDate
  • string

The time this thread was last updated.

properties

Optional properties associated with the thread as a collection of key-value pairs.

publishedDate
  • string

The time this thread was published.

pullRequestThreadContext

Extended context information unique to pull requests

status

The status of the comment thread.

threadContext

Specify thread context such as position in left/right file.

Responses

Name Type Description
200 OK

successful operation

Examples

Comment on a specific file in the pull request
Comment on the pull request

Comment on a specific file in the pull request

Sample Request

POST https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullRequests/22/threads?api-version=5.0-preview.1
{
  "comments": [
    {
      "parentCommentId": 0,
      "content": "Should we add a comment about what this value means?",
      "commentType": 1
    }
  ],
  "status": 1,
  "threadContext": {
    "filePath": "/new_feature.cpp",
    "leftFileEnd": null,
    "leftFileStart": null,
    "rightFileEnd": {
      "line": 5,
      "offset": 13
    },
    "rightFileStart": {
      "line": 5,
      "offset": 1
    }
  },
  "pullRequestThreadContext": {
    "changeTrackingId": 1,
    "iterationContext": {
      "firstComparingIteration": 1,
      "secondComparingIteration": 2
    }
  }
}

Sample Response

{
  "pullRequestThreadContext": {
    "iterationContext": {
      "firstComparingIteration": 1,
      "secondComparingIteration": 2
    },
    "changeTrackingId": 1
  },
  "id": 148,
  "publishedDate": "2016-11-01T16:30:50.083Z",
  "lastUpdatedDate": "2016-11-01T16:30:50.083Z",
  "comments": [
    {
      "id": 1,
      "parentCommentId": 0,
      "author": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://dev.azure.com/fabrikam/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "content": "Should we add a comment about what this value means?",
      "publishedDate": "2016-11-01T16:30:50.083Z",
      "lastUpdatedDate": "2016-11-01T16:30:50.083Z",
      "commentType": "text"
    }
  ],
  "status": "active",
  "threadContext": {
    "filePath": "/new_feature.cpp",
    "rightFileStart": {
      "line": 5,
      "offset": 1
    },
    "rightFileEnd": {
      "line": 5,
      "offset": 13
    }
  },
  "properties": {},
  "isDeleted": false,
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullRequests/22/threads/148"
    },
    "repository": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719"
    }
  }
}

Comment on the pull request

Sample Request

POST https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullRequests/22/threads?api-version=5.0-preview.1
{
  "comments": [
    {
      "parentCommentId": 0,
      "content": "This new feature looks good!",
      "commentType": 1
    }
  ],
  "status": 1
}

Sample Response

{
  "pullRequestThreadContext": null,
  "id": 147,
  "publishedDate": "2016-11-01T16:30:48.91Z",
  "lastUpdatedDate": "2016-11-01T16:30:48.91Z",
  "comments": [
    {
      "id": 1,
      "parentCommentId": 0,
      "author": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://dev.azure.com/fabrikam/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "content": "This new feature looks good!",
      "publishedDate": "2016-11-01T16:30:48.91Z",
      "lastUpdatedDate": "2016-11-01T16:30:48.91Z",
      "commentType": "text"
    }
  ],
  "status": "active",
  "threadContext": null,
  "properties": {},
  "isDeleted": false,
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullRequests/22/threads/147"
    },
    "repository": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719"
    }
  }
}

Definitions

Comment

Represents a comment which is one of potentially many in a comment thread.

CommentIterationContext

Comment iteration context is used to identify which diff was being viewed when the thread was created.

CommentPosition
CommentThreadContext
CommentThreadStatus

The status of the comment thread.

CommentTrackingCriteria

Comment tracking criteria is used to identify which iteration context the thread has been tracked to (if any) along with some detail about the original position and filename.

CommentType

The comment type at the time of creation.

GitPullRequestCommentThread

Represents a comment thread of a pull request. A thread contains meta data about the file it was left on (if any) along with one or more comments (an initial comment and the subsequent replies).

GitPullRequestCommentThreadContext

Comment thread context contains details about what diffs were being viewed at the time of thread creation and whether or not the thread has been tracked from that original diff.

IdentityRef
PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

ReferenceLinks

The class to represent a collection of REST reference links.

Comment

Represents a comment which is one of potentially many in a comment thread.

Name Type Description
_links

Links to other related objects.

author

The author of the comment.

commentType

The comment type at the time of creation.

content
  • string

The comment content.

id
  • integer

The comment ID. IDs start at 1 and are unique to a pull request.

isDeleted
  • boolean

Whether or not this comment was soft-deleted.

lastContentUpdatedDate
  • string

The date the comment's content was last updated.

lastUpdatedDate
  • string

The date the comment was last updated.

parentCommentId
  • integer

The ID of the parent comment. This is used for replies.

publishedDate
  • string

The date the comment was first published.

usersLiked

A list of the users who have liked this comment.

CommentIterationContext

Comment iteration context is used to identify which diff was being viewed when the thread was created.

Name Type Description
firstComparingIteration
  • integer

The iteration of the file on the left side of the diff when the thread was created. If this value is equal to SecondComparingIteration, then this version is the common commit between the source and target branches of the pull request.

secondComparingIteration
  • integer

The iteration of the file on the right side of the diff when the thread was created.

CommentPosition

Name Type Description
line
  • integer

The line number of a thread's position. Starts at 1.

offset
  • integer

The character offset of a thread's position inside of a line. Starts at 0.

CommentThreadContext

Name Type Description
filePath
  • string

File path relative to the root of the repository. It's up to the client to use any path format.

leftFileEnd

Position of last character of the thread's span in left file.

leftFileStart

Position of first character of the thread's span in left file.

rightFileEnd

Position of last character of the thread's span in right file.

rightFileStart

Position of first character of the thread's span in right file.

CommentThreadStatus

The status of the comment thread.

Name Type Description
active
  • string

The thread status is active.

byDesign
  • string

The thread status is resolved as by design.

closed
  • string

The thread status is closed.

fixed
  • string

The thread status is resolved as fixed.

pending
  • string

The thread status is pending.

unknown
  • string

The thread status is unknown.

wontFix
  • string

The thread status is resolved as won't fix.

CommentTrackingCriteria

Comment tracking criteria is used to identify which iteration context the thread has been tracked to (if any) along with some detail about the original position and filename.

Name Type Description
firstComparingIteration
  • integer

The iteration of the file on the left side of the diff that the thread will be tracked to. Threads were tracked if this is greater than 0.

origFilePath
  • string

Original filepath the thread was created on before tracking. This will be different than the current thread filepath if the file in question was renamed in a later iteration.

origLeftFileEnd

Original position of last character of the thread's span in left file.

origLeftFileStart

Original position of first character of the thread's span in left file.

origRightFileEnd

Original position of last character of the thread's span in right file.

origRightFileStart

Original position of first character of the thread's span in right file.

secondComparingIteration
  • integer

The iteration of the file on the right side of the diff that the thread will be tracked to. Threads were tracked if this is greater than 0.

CommentType

The comment type at the time of creation.

Name Type Description
codeChange
  • string

The comment comes as a result of a code change.

system
  • string

The comment represents a system message.

text
  • string

This is a regular user comment.

unknown
  • string

The comment type is not known.

GitPullRequestCommentThread

Represents a comment thread of a pull request. A thread contains meta data about the file it was left on (if any) along with one or more comments (an initial comment and the subsequent replies).

Name Type Description
_links

Links to other related objects.

comments

A list of the comments.

id
  • integer

The comment thread id.

identities

Set of identities related to this thread

isDeleted
  • boolean

Specify if the thread is deleted which happens when all comments are deleted.

lastUpdatedDate
  • string

The time this thread was last updated.

properties

Optional properties associated with the thread as a collection of key-value pairs.

publishedDate
  • string

The time this thread was published.

pullRequestThreadContext

Extended context information unique to pull requests

status

The status of the comment thread.

threadContext

Specify thread context such as position in left/right file.

GitPullRequestCommentThreadContext

Comment thread context contains details about what diffs were being viewed at the time of thread creation and whether or not the thread has been tracked from that original diff.

Name Type Description
changeTrackingId
  • integer

Used to track a comment across iterations. This value can be found by looking at the iteration's changes list. Must be set for pull requests with iteration support. Otherwise, it's not required for 'legacy' pull requests.

iterationContext

The iteration context being viewed when the thread was created.

trackingCriteria

The criteria used to track this thread. If this property is filled out when the thread is returned, then the thread has been tracked from its original location using the given criteria.

IdentityRef

Name Type Description
_links

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
profileUrl
  • string
uniqueName
  • string
url
  • string

This url is the full route to the source resource of this graph subject.

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

Name Type Description
count
  • integer

The count of properties in the collection.

item
  • object
keys
  • string[]

The set of keys in the collection.

values
  • string[]

The set of values in the collection.

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.