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.1URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
organization
|
path | True |
string |
The name of the Azure DevOps organization. |
|
pull
|
path | True |
integer int32 |
ID of the pull request. |
|
repository
|
path | True |
string |
Repository ID of the pull request's target branch. |
|
project
|
path |
string |
Project ID or project name |
|
|
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
| Name | Type | Description |
|---|---|---|
| _links |
Links to other related objects. |
|
| comments |
Comment[] |
A list of the comments. |
| id |
integer |
The comment thread id. |
| identities |
<string,
Identity |
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 |
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.code_write | Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage pull requests and code reviews and to receive notifications about version control events via service hooks. |
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.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.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
| Name | Description |
|---|---|
| Comment |
Represents a comment which is one of potentially many in a comment thread. |
|
Comment |
Comment iteration context is used to identify which diff was being viewed when the thread was created. |
|
Comment |
|
|
Comment |
|
|
Comment |
The status of the comment thread. |
|
Comment |
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. |
|
Comment |
The comment type at the time of creation. |
|
Git |
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). |
|
Git |
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. |
|
Identity |
|
|
Properties |
The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a |
|
Reference |
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 1. |
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 |
Comment[] |
A list of the comments. |
| id |
integer |
The comment thread id. |
| identities |
<string,
Identity |
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 |
Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary |
| 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 |
Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary |
| inactive |
boolean |
Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary |
| isAadIdentity |
boolean |
Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType) |
| isContainer |
boolean |
Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType) |
| isDeletedInOrigin |
boolean |
|
| profileUrl |
string |
Deprecated - not in use in most preexisting implementations of ToIdentityRef |
| uniqueName |
string |
Deprecated - use Domain+PrincipalName instead |
| 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. |
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. |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for