Ctrl+K

Introduction to Content Endpoints

Introduction to Content Endpoints#

Workiva’s Content endpoints allow customers to produce and format rich, structured content within the Workiva Platform. Content tasks include editing and formatting rich text, managing data in tables, and setting up documents. This guide answers the following questions:

  • What are some example use cases for content endpoints?

  • What are some common concepts to consider when working with content?

Example Use Cases#

Content endpoints enable users to edit content in a document or spreadsheet similar to editing content directly in the document or spreadsheet editor, allowing a variety of use cases. Here are some high-level examples of how content endpoints might be useful:

Generating New Documents#

Workiva’s Files and Documents endpoints can be used to both create a new document and to add new sections to that document. Content endpoints allow you to take things a step further and set up content within the section body, header, and footer. This enables you to generate a document with styled content without having to manually build it in the Workiva Platform.

Updating Existing Content#

In addition to setting up new content in a document, the Content endpoints can update existing content in a document section, header, footer, or embedded table, or to a sheet in a spreadsheet.

Common Concepts#

What is content?#

Content is any user-entered data in a document section, spreadsheet table, or presentation slide. For example, content may be the text of a section, an embedded table, a spreadsheet sheet, or a slide drawing.

Content endpoints currently support three container types: rich text, tables, and drawings. All content-related actions (reads and writes) occur within one of those containers.

Revisions#

Revisions describe a single atomic change or group of changes in a document or spreadsheet. Content editing via API requires you to specify which revision of the Content your changes are based on, in order to correctly account for concurrent collaborative edits.

When a content edit is made, the revision is required so that the correct offsets for a rich text edit or cell location for a table edit are used.

Tip

If you are making multiple edit requests to the same content, it is important that you use the latest revision from the previous edit on the subsequent request to ensure your edits take into account the state from previous edits.

Important

All content in a document or spreadsheet shares the same revision. Making a single edit to a document or spreadsheet sheet will increment all sections in the document or sheets in the spreadsheet to the revision for that edit.

Async Operations#

All content edits are asynchronous operations. If an edit is Accepted, the returned response has a Location header, which indicates an Operation poll for results. The completed Operation will include a resourceUrl that will contain either:

  • A GET request to the updated content with a $revision query parameter containing the created revision from the edit request.

  • A GET request to a results endpoint containing the created resources and revision from the edit request.

For more information about async operations, see Introduction to Operations.

Anchors#

Drawing, rich text, and table content can be extended with an anchor. An anchor is an attachment point to existing content. Examples of anchors include source links and comment selections.

For more information, see Introduction to Anchor Endpoints.

Drawings#

A drawing contains a collection of drawing elements for a slide in a presentation or floating content in a document. Examples of drawing elements include text boxes, lines, images, tables, charts, and shapes.

For more information, see Introduction to Drawings Endpoints

Images#

Image content can be retrieved and inserted through Content endpoints.

For more information see Introduction to Image Endpoints.

Rich Text#

Rich text contains the content for the section body, header, or footer in a document. Rich text is a collection of paragraphs, each containing a collection of rich text elements.

For more information, see Introduction to Rich Text Endpoints.

Tables#

A table is either an embedded table or a spreadsheet sheet, and is represented by a collection of cells. In a spreadsheet, each sheet is the container for a table, similar to a section being the container for rich text in a document.

For more information see Introduction to Table Endpoints.