Service endpoints

Article
03/22/2022

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 3.0-preview.1

If you haven't already, look at the information on getting started with these APIs.

Get a list of service endpoints

GET https://{instance}/defaultcollection/{project}/_apis/distributedtask/serviceendpoints?[api-version={version}]

Parameter	Type	Notes
URL
instance	string	TFS server name ({server:port}).
project	string	Project ID or name.
Query
version	string	Version of the API to use.

Sample request

GET https://mytfsserver/DefaultCollection/ff213d65-d61d-447c-b39d-d16f21b18364/_apis/distributedtask/serviceendpoints?api-version=3.0-preview.1

Sample response

{
  "count": 3,
  "value": [
    {
      "data": {
        "subscriptionId": "ddc11291-9826-55be-b932-70349146ddf8",
        "subscriptionName": "Fabrikam-Azure"
      },
      "id": "178cd0a2-536d-4ceb-9e5b-2ebc46a66d0e",
      "name": "Fabrikam-Azure",
      "type": "azure",
      "url": "https://management.core.windows.net/",
      "createdBy": {
        "id": "52a5bc8d-4730-400a-95c7-7276d4ae5953",
        "displayName": "Chuck Reinhart",
        "uniqueName": "chuckreinhart@outlook.com"
      },
      "authorization": {
        "scheme": "Certificate"
      },
      "groupScopeId": "afd9a2f8-2ff2-490c-b5bb-a070a5acffe8",
      "administratorsGroup": {
        "id": "e98d5799-6571-46b3-a867-aeaf33c6df8d",
        "displayName": "[Service Endpoint 178cd0a2-536d-4ceb-9e5b-2ebc46a66d0e]\\Endpoint Administrators",
        "uniqueName": "vstfs:///Framework/Generic/afd9a2f8-2ff2-490c-b5bb-a070a5acffe8\\Endpoint Administrators",
        "isContainer": true
      },
      "readersGroup": {
        "id": "fcfdfa1c-f958-427d-8743-b8e3a1981689",
        "displayName": "[Service Endpoint 178cd0a2-536d-4ceb-9e5b-2ebc46a66d0e]\\Endpoint Readers",
        "uniqueName": "vstfs:///Framework/Generic/afd9a2f8-2ff2-490c-b5bb-a070a5acffe8\\Endpoint Readers",
        "isContainer": true
      },
      "isReady": true
    },
    {
      "data": {},
      "id": "03b4a664-2285-4c1b-bfb1-51595ac6b44b",
      "name": "Jenkins-Fabrikam",
      "type": "jenkins",
      "url": "https://fab-jenkins:8080/",
      "createdBy": {
        "id": "52a5bc8d-4730-400a-95c7-7276d4ae5953",
        "displayName": "Chuck Reinhart",
        "uniqueName": "chuckreinhart@outlook.com"
      },
      "authorization": {
        "scheme": "UsernamePassword"
      },
      "groupScopeId": "4147b96d-4c42-49d0-bf6d-04406b44f807",
      "administratorsGroup": {
        "id": "25b7297a-b10a-49ff-9437-c8f91521165e",
        "displayName": "[Service Endpoint 03b4a664-2285-4c1b-bfb1-51595ac6b44b]\\Endpoint Administrators",
        "uniqueName": "vstfs:///Framework/Generic/4147b96d-4c42-49d0-bf6d-04406b44f807\\Endpoint Administrators",
        "isContainer": true
      },
      "readersGroup": {
        "id": "fc783397-019e-4bb1-94e8-dd99e3aa6a75",
        "displayName": "[Service Endpoint 03b4a664-2285-4c1b-bfb1-51595ac6b44b]\\Endpoint Readers",
        "uniqueName": "vstfs:///Framework/Generic/4147b96d-4c42-49d0-bf6d-04406b44f807\\Endpoint Readers",
        "isContainer": true
      },
      "isReady": true
    }
  ]
}

Create a service endpoint

POST https://{instance}/defaultcollection/{project}/_apis/distributedtask/serviceendpoints?[api-version={version}]

Parameter	Type	Notes
URL
instance	string	TFS server name ({server:port}).
project	string	Project ID or name.
Query
version	string	Version of the API to use.
Body
name	string	Name of the service endpoint.
type	string	Type of the service endpoint.
url	string	Complete URL of the service that is being connected.
authorization	JSON	Inputs related to authentication of the service endpoint.
data	JSON	Other inputs that are required by the mentioned endpoint type.
Response
isReady	bool	Indicates if the created endpoint is ready to use or not. Applies only to Azure SPN, always true for other endpoint types

Sample request

POST https://mytfsserver/DefaultCollection/ff213d65-d61d-447c-b39d-d16f21b18364/_apis/distributedtask/serviceendpoints?api-version=3.0-preview.1

{
  "name": "Fabrikam-Chef",
  "type": "chef",
  "url": "https://fabrikam-chef:9090",
  "authorization": {
    "scheme": "UsernamePassword",
    "parameters": {
      "username": "someUsername",
      "password": "somePassword"
    }
  }
}

Sample response

{
  "data": {},
  "id": "d4177445-c5ad-414a-82bf-2d5727a8176e",
  "name": "Fabrikam-Chef",
  "type": "chef",
  "url": "https://fabrikam-chef:9090",
  "createdBy": {
    "id": "52a5bc8d-4730-400a-95c7-7276d4ae5953",
    "displayName": "Chuck Reinhart",
    "uniqueName": "chuckreinhart@outlook.com"
  },
  "authorization": {
    "parameters": {
      "username": "someUsername",
      "password": "somePassword"
    },
    "scheme": "UsernamePassword"
  },
  "groupScopeId": "24f9e5e0-93a3-465a-a2a3-f5db672a72c2",
  "administratorsGroup": {
    "id": "3efde1c2-fd15-414e-acd1-975f5570d382"
  },
  "readersGroup": {
    "id": "4b12a0e3-48c9-45d7-8861-cadf0e5ca992"
  },
  "isReady": true
}

Get a service endpoint

GET https://{instance}/defaultcollection/{project}/_apis/distributedtask/serviceendpoints/{id}?[api-version={version}]

Parameter	Type	Notes
URL
instance	string	TFS server name ({server:port}).
project	string	Project ID or name.
id	string	Endpoint ID.
Query
version	string	Version of the API to use.

Sample request

GET https://mytfsserver/DefaultCollection/ff213d65-d61d-447c-b39d-d16f21b18364/_apis/distributedtask/serviceendpoints/d4177445-c5ad-414a-82bf-2d5727a8176e?api-version=3.0-preview.1

Sample response

{
  "data": {},
  "id": "d4177445-c5ad-414a-82bf-2d5727a8176e",
  "name": "Fabrikam-Chef",
  "type": "chef",
  "url": "https://fabrikam-chef:9090/",
  "createdBy": {
    "id": "52a5bc8d-4730-400a-95c7-7276d4ae5953",
    "displayName": "Chuck Reinhart",
    "uniqueName": "chuckreinhart@outlook.com"
  },
  "authorization": {
    "parameters": {
      "username": "someUsername"
    },
    "scheme": "UsernamePassword"
  },
  "groupScopeId": "24f9e5e0-93a3-465a-a2a3-f5db672a72c2",
  "administratorsGroup": {
    "id": "3efde1c2-fd15-414e-acd1-975f5570d382"
  },
  "readersGroup": {
    "id": "4b12a0e3-48c9-45d7-8861-cadf0e5ca992"
  },
  "isReady": true
}

Update a service endpoint

PUT https://{instance}/defaultcollection/{project}/_apis/distributedtask/serviceendpoints/{id}?[api-version={version}]

Parameter	Type	Notes
URL
instance	string	TFS server name ({server:port}).
project	string	Project ID or name.
id	string	Endpoint ID.
Query
version	string	Version of the API to use.

Sample request

PUT https://mytfsserver/DefaultCollection/ff213d65-d61d-447c-b39d-d16f21b18364/_apis/distributedtask/serviceendpoints/d4177445-c5ad-414a-82bf-2d5727a8176e?api-version=3.0-preview.1

{
  "name": "Fabrikam-Chef-Updated",
  "type": "chef",
  "url": "https://fabrikam-chef-updated:9090",
  "authorization": {
    "scheme": "UsernamePassword",
    "parameters": {
      "username": "someUsername",
      "password": "somePassword"
    }
  }
}

Sample response

{
  "data": {},
  "id": "d4177445-c5ad-414a-82bf-2d5727a8176e",
  "name": "Fabrikam-Chef-Updated",
  "type": "chef",
  "url": "https://fabrikam-chef-updated:9090",
  "authorization": {
    "parameters": {
      "username": "someUsername",
      "password": "somePassword"
    },
    "scheme": "UsernamePassword"
  },
  "isReady": true
}

Delete a service endpoint

DELETE https://{instance}/defaultcollection/{project}/_apis/distributedtask/serviceendpoints/{id}?[api-version={version}]

Parameter	Type	Notes
URL
instance	string	TFS server name ({server:port}).
project	string	Project ID or name.
id	string	Endpoint ID.
Query
version	string	Version of the API to use.

Sample request

DELETE https://mytfsserver/DefaultCollection/ff213d65-d61d-447c-b39d-d16f21b18364/_apis/distributedtask/serviceendpoints/d4177445-c5ad-414a-82bf-2d5727a8176e?api-version=3.0-preview.1

Service endpoints

Get a list of service endpoints

Sample request

Sample response

Create a service endpoint

Sample request

Sample response

Get a service endpoint

Sample request

Sample response

Update a service endpoint

Sample request

Sample response

Delete a service endpoint

Sample request

Additional resources