Ctrl+K

Introduction to Milestones Endpoints

Introduction to Milestones Endpoints#

Workiva’s Milestones endpoints allow customers to interact with milestones in documents, presentations, and spreadsheets. Milestones represents a specific revision or point-in-time of a specific document, spreadsheet, or presentation. In this guide, you’ll learn:

  • How do I retrieve milestones from a document?

  • How do I retrieve milestones from a spreadsheet?

  • How do I retrieve milestones from a presentation?

  • How do I create a new milestone?

  • How do I update an existing milestone?

  • How do I delete a milestone?

  • How do I query for content associated with a milestone?

Example Use Cases#

How do I retrieve milestones from a document?#

To retrieve milestones for a document, use the GET document milestones endpoint. This endpoint requires the documentId parameter and returns a paginated list of milestones associated with the document.

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/b4a60ce10bc8479e836700b02ce45dea/milestones

The response includes milestone data with details such as the milestone ID, title, remarks, creation information, and resource references.

How do I retrieve milestones from a spreadsheet?#

To retrieve milestones for a spreadsheet, use the GET spreadsheet milestones endpoint. This endpoint requires the spreadsheetId parameter and returns a paginated list of milestones associated with the spreadsheet.

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/spreadsheets/b4a60ce10bc8479e836700b02ce45dea/milestones

How do I retrieve milestones from a presentation?#

To retrieve milestones for a presentation, use the GET presentation milestones endpoint. This endpoint requires the presentationId parameter and returns a paginated list of milestones associated with the presentation.

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/presentation/b4a60ce10bc8479e836700b02ce45dea/milestones

How do I create a new milestone?#

To create a new milestone, use the POST milestone creation endpoint. This operation will create a milestone at the current revision of the document, spreadsheet, or presentation. This is a long-running operation that requires a MilestoneCreation request body.

The request body must include:

  • type: The milestone resource type

  • title: The milestone title (1-200 characters)

  • One of: document, presentation, or spreadsheet ID

  • remarks: Optional remarks (defaults to empty string)

Request#
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/milestones/creation
Request Body#
{
  "type": "document",
  "document": "16b1f641613847469b7aa1ca29af40b1",
  "title": "Q1 Review Complete",
  "remarks": "All Q1 deliverables have been reviewed and approved"
}

After the request is made, the status of the request can be found by polling the Operations endpoint set in the location header of the action’s response. When the operation is complete a GET request can be made to the completed operation’s resourceUrl to retrieve the newly created milestone id. If the response is 202, your creation request was accepted. Read the Operations guide to learn more about operations.

How do I update an existing milestone?#

To update an existing milestone, use the PATCH milestone endpoint. This endpoint supports partial updates using JSON Patch operations.

Request#
curl -X PATCH -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/milestones/bWlsZXN0b25lLXYxOjcxNTMyYWI1OTljNTRmMjliOGRmMTQ4ZmI0YjJkOTI0OjJjNjQzOGFiNDU1NTNkZWU
Request Body#
[
  {
    "op": "replace",
    "path": "/title",
    "value": "Updated Milestone Title"
  },
  {
    "op": "replace",
    "path": "/remarks",
    "value": "Updated remarks for the milestone"
  }
]

Supported PATCH operations:

  • /title: Replace the milestone title

  • /remarks: Replace the milestone remarks. Replacing with null will clear the remarks.

How do I delete a milestone?#

To delete a milestone, use the DELETE milestone endpoint. This endpoint requires the milestoneId parameter.

Request#
curl -X DELETE -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/milestones/bWlsZXN0b25lLXYxOjcxNTMyYWI1OTljNTRmMjliOGRmMTQ4ZmI0YjJkOTI0OjJjNjQzOGFiNDU1NTNkZWU

The endpoint returns a 204 No Content response upon successful deletion.

How do I query for content associated with a milestone?#

To get content from a specific milestone, first use the GET milestone endpoint with the milestoneId to find the corresponding revision.

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/milestones/bWlsZXN0b25lLXYxOjcxNTMyYWI1OTljNTRmMjliOGRmMTQ4ZmI0YjJkOTI0OjJjNjQzOGFiNDU1NTNkZWU
Response Body#
{
  "created": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "displayName": "string",
      "email": "string",
      "id": "bWlsZXN0b25lLXYxOjcxNTMyYWI1OTljNTRmMjliOGRmMTQ4ZmI0YjJkOTI0OjJjNjQzOGFiNDU1NTNkZWU"
    }
  },
  "id": "WW91IGZvdW5kIG1d5kIGSd2lIQ",
  "remarks": "string",
  "resource": {
    "document": {
      "document": "16b1f641613847469b7aa1ca29af40b1",
      "location": "<opaque_url>",
      "revision": "2B3C4D5E"
    },
    "type": "document"
  },
  "title": "string"
}

Then, use that revision as a query parameter in GET requests for the desired content associated with the milestone. For example, to retrieve the rich text in a milestone’s section the following requests can be made:

  1. GET Section request with the document id, section id, and milestone revision:

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/16b1f641613847469b7aa1ca29af40b1/sections/16b1f641613847469b7aa1ca29af40b1_37?$revision=2B3C4D5E

  1. GET Rich Text Paragraphs request with the rich text id of the section body and milestone revision

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/content/richText/WA318fnx9AydtxnHa1OuP9AGn3NUZkgl3990WH59AYV9BLFYLTNW736RhdneRU2w/paragraphs?$revision=2B3C4D5E

For more information about how to query for revision specific content, see the Introduction to Content Endpoints.

Common Concepts#

Milestone#

A Milestone represents a specific revision of a document, presentation, or spreadsheet. Each milestone contains:

  • id: Unique identifier for the milestone

  • resource: Reference to the associated content (document, presentation, or spreadsheet)

  • title: The milestone title

  • remarks: Optional remarks or notes

  • created: Information about when and by whom the milestone was created

Milestone Resource Reference#

The resource property contains a MilestoneResourceRef that specifies:

  • type: The milestone resource type

  • One of: document, presentation, or spreadsheet reference containing the content ID and revision

Milestone Creation#

When creating a milestone, use the MilestoneCreation schema which requires:

  • type: The content type

  • title: The milestone title (1-200 characters)

  • One of: document, presentation, or spreadsheet ID

  • remarks: Optional remarks (defaults to empty string)

The created milestone will be associated with the latest revision of the content at the time of creation.