↓Skip to main content

API for the Azure DevOps Team Calendar

·2 mins
Table of Contents

Azure DevOps has an extension that provides a calendar for each Team, but the API is not documented. These notes cover API methods for the Team calendar, to enable automation.

Installing The Team Calendar #

Add the Azure DevOps Team Calendar from the Marketplace to your organization in Azure DevOps.

URL Format #

To access a calendar, you must build a URL that specifies your Azure DevOps organization, the teamId of the Team, and the month and year that are relevant for the operation:

https://extmgmt.dev.azure.com/{organisation}/_apis/ExtensionManagement/InstalledExtensions/ms-devlabs/team-calendar/Data/Scopes/Default/Current/Collections/{teamId}.{monthNumber}.{year}/Documents

You must include an API version with calls that create, update or delete a calendar event:

https://extmgmt.dev.azure.com/{organisation}/_apis/ExtensionManagement/InstalledExtensions/ms-devlabs/team-calendar/Data/Scopes/Default/Current/Collections/{teamId}.{monthNumber}.{year}/Documents?api-version=6.1-preview.1
It seems that the API will accept any version, but the query string for api-version must include the string -preview.

API Calls #

You access the calendar resources through the Azure DevOps REST API.

GET Calendar Events #

Issue a GET request on the main URL:

https://extmgmt.dev.azure.com/{organisation}/_apis/ExtensionManagement/InstalledExtensions/ms-devlabs/team-calendar/Data/Scopes/Default/Current/Collections/{teamId}.{monthNumber}.{year}/Documents

This returns a document with this structure:

{
  "count": 1,
  "value": [
    {
      "category": "Uncategorized",
      "description": "",
      "endDate": "2021-02-03T00:00:00Z",
      "startDate": "2021-02-03T00:00:00Z",
      "title": "Example event 1",
      "__etag": 1,
      "id": "f14fd3ff-f39b-4d23-a353-6e3dfbf3af4a"
    }
  ]
}

A month with no events will return a document with this structure:

{
  "count": 0,
  "value": []
}

PUT New Calendar Event #

Send a JSON document with this structure:

{
  "category": "Uncategorized",
  "description": "",
  "endDate": "2021-03-01T00:00:00Z",
  "startDate": "2021-03-01T00:00:00Z",
  "title": "Example event 21"
}

PUT Update Calendar Event #

To delete a calendar event, send a HTTP PUT request. This is the format of the JSON document:

{
  "__etag": 3,
  "id": "290d0223-0256-432d-9c18-a6fed6e8b5e3",
  "category": "Uncategorized",
  "description": "",
  "endDate": "2021-02-01T00:00:00Z",
  "startDate": "2021-02-01T00:00:00Z",
  "title": "Example event 1"
}

Note that this includes the id of the calendar, and an __etag value. Always set the __etag value as the current __etag value of the event, plus one. The Data Storage that Team Calendar uses relies on the etag value for locking.

DELETE Calendar Event #

To delete a calendar event, send a HTTP DELETE request to a URL that includes the ID for the event:

https://extmgmt.dev.azure.com/{organisation}/_apis/ExtensionManagement/InstalledExtensions/ms-devlabs/team-calendar/Data/Scopes/Default/Current/Collections/{teamId}.{monthId}.{year}/Documents/{eventId}?api-version=6.1-preview.1

This returns a HTTP 204 response, with an empty body.

Error Structure #

Errors return a JSON document with this structure:

{
  "$id": "1",
  "innerException": null,
  "message": "%error=\"1660000\";%:The document already exists",
  "typeName": "Microsoft.VisualStudio.Services.ExtensionManagement.WebApi.DocumentExistsException, Microsoft.VisualStudio.Services.ExtensionManagement.WebApi",
  "typeKey": "DocumentExistsException",
  "errorCode": 0,
  "eventId": 3000
}

Resources #