Workspace documents in Postman

Workspace documents let you capture information about your API directly alongside your collections, environments, and specifications. This page explains what workspace documents are, how to pin one to your workspace overview, and how Postman syncs documents when you work in Native Git local mode.

Workspace documents

A workspace document is a Markdown file that you can create and edit in Postman. You can use them to share information, such as design decisions, implementation details, and usage instructions. Your workspace documents are located in the Documents sidebar.

You can create, rename, duplicate, and delete workspace documents, and edit them in either a visual rich-text editor or a Markdown editor while in Local View. You can also change which document is pinned in your workspace overview.

Any document in your workspace can also be pinned, which displays its full contents below the workspace header. By default, Postman uses a file named WORKSPACE-README.md as the main workspace document, and it’s created with a structured template. To create a new workspace document and pin it to your workspace, click Add WORKSPACE-README in the workspace overview.

When a workspace is linked to a Git repository, documents are included in sync and only documents in the postman/documents/ folder are visible. To include more documents, add them as a localResources.documents entry in the resources.yaml file with the path to the file.

Files added to the resources.yaml file are automatically added to the sidebar and changes are reflected in the local-to-cloud diff. Users assigned as Admins and Editors can create and edit documents, and Viewers can read them.

Postman’s Agent Mode has full CRUD access to documents and can generate WORKSPACE-README files, update existing content, and write task output like plans, decisions, and summaries.

Change a pinned workspace document

You can change which document is pinned in your workspace overview. The pinned document serves as an overview of the workspace and is displayed below the workspace header. You can pin any document in your workspace, including a custom document or the default WORKSPACE-README file.

To change the pinned document, do the following:

1. In the workspace’s Overview tab, click Change pinned document.
2. In the Workspace overview section of the workspace’s settings, select a document from the dropdown list. To remove a pinned document, click Clear.

If no documents are pinned to the workspace, click Pin document to overview and select a document.

Sync workspace documents in local mode

When you work in local mode, Postman automatically syncs certain files in your project folder as workspace documents. By default, Postman syncs any document in the postman/documents/ folder.