Service endpoints

Last Update: 12/5/2016

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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Team project ID or name.
Query
version string Version of the API to use.

Sample request

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

Sample response

Status code: 200
{
  "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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Team 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://fabfiber.visualstudio.com/DefaultCollection/ff213d65-d61d-447c-b39d-d16f21b18364/_apis/distributedtask/serviceendpoints?api-version=3.0-preview.1
Content-Type: application/json
{
  "name": "Fabrikam-Chef",
  "type": "chef",
  "url": "https://fabrikam-chef:9090",
  "authorization": {
    "scheme": "UsernamePassword",
    "parameters": {
      "username": "someUsername",
      "password": "somePassword"
    }
  }
}

Sample response

Status code: 200
{
  "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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Team project ID or name.
id string Endpoint ID.
Query
version string Version of the API to use.

Sample request

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

Sample response

Status code: 200
{
  "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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Team project ID or name.
id string Endpoint ID.
Query
version string Version of the API to use.

Sample request

PUT https://fabfiber.visualstudio.com/DefaultCollection/ff213d65-d61d-447c-b39d-d16f21b18364/_apis/distributedtask/serviceendpoints/d4177445-c5ad-414a-82bf-2d5727a8176e?api-version=3.0-preview.1
Content-Type: application/json
{
  "name": "Fabrikam-Chef-Updated",
  "type": "chef",
  "url": "https://fabrikam-chef-updated:9090",
  "authorization": {
    "scheme": "UsernamePassword",
    "parameters": {
      "username": "someUsername",
      "password": "somePassword"
    }
  }
}

Sample response

Status code: 200
{
  "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 VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string Team project ID or name.
id string Endpoint ID.
Query
version string Version of the API to use.

Sample request

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

Sample response

Status code: 204