From 2dff0d2e2c6828bb9dfa1bfa3278fd61d3f0d5ca Mon Sep 17 00:00:00 2001 From: Yohanan Assefa Date: Wed, 16 Sep 2026 10:02:46 -0400 Subject: [PATCH] [DOCINT-2096] docs: enable Document Revisions guide navigation List and download routes are going public in DOCINT-1853, so the guide can appear in nav, search, and related-docs links. --- _data/navigation.yml | 4 ++-- .../document_management_document_revisions.md | 20 ++++++++++++++----- .../document_management_intro.md | 1 + .../document_management_metadata_details.md | 1 + .../document_management_technical_guide.md | 1 + 5 files changed, 20 insertions(+), 7 deletions(-) diff --git a/_data/navigation.yml b/_data/navigation.yml index cefb7b9..145c04d 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -183,8 +183,8 @@ # url: /document-management-api-endpoints - Retired 2026-08-17, re-hosted endpoint data; see the REST reference. Needed for Redirect - title: Technical Guide url: /document-management-technical-guide - # - title: Document Revisions - # url: /document-management-document-revisions - Hidden until DOCINT-1853 flips List Document Revisions to public visibility + - title: Document Revisions + url: /document-management-document-revisions - title: Metadata Details url: /document-management-metadata-details diff --git a/document_management_integration/document_management_document_revisions.md b/document_management_integration/document_management_document_revisions.md index 0828e4e..ec069bc 100644 --- a/document_management_integration/document_management_document_revisions.md +++ b/document_management_integration/document_management_document_revisions.md @@ -23,10 +23,10 @@ This guide covers the read side of that lifecycle: how to list revisions after s *** -> **List Document Revisions and List Recycled Document Revisions are private and beta.** Both are annotated `visibility: private` and `stage: beta` in the Document Management service. List Selected Document Revisions is public and beta. +> **These endpoints are in beta.** Watch the changelog for new [resource versions]({{ site.url }}{{ site.baseurl }}{% link getting_started/rest_api_overview.md %}). {: .callout .callout--warning} -All three endpoints require a valid OAuth 2.0 token. Results are scoped to the calling principal's Document Management permission groups — the same request returns different rows for different tokens. How a withheld revision appears depends on the call: a discovery list omits it with no withheld-count signal; a hydration call by ID returns a masked row. See [Permission Scoping](#permission-scoping). +All endpoints require a valid OAuth 2.0 token. Results are scoped to the calling principal's Document Management permission groups — the same request returns different rows for different tokens. How a withheld revision appears depends on the call: a discovery list omits it with no withheld-count signal; a hydration call by ID returns a masked row. See [Permission Scoping](#permission-scoping). ### Base URL @@ -36,7 +36,7 @@ Document Revision read endpoints use the following base path: /rest/v{version}/companies/{company_id}/projects/{project_id}/document_management ``` -Replace `{version}` with the version shown on each endpoint (`2.0` or `2.1`). Replace `{company_id}` and `{project_id}` with your actual Procore company and project IDs. List Document Revisions and List Selected Document Revisions are mounted on both `2.0` and `2.1`. List Recycled Document Revisions is mounted on `2.0` only. +Replace `{version}` with the version shown on each endpoint (`2.0` or `2.1`). Replace `{company_id}` and `{project_id}` with your actual Procore company and project IDs. List Document Revisions, List Selected Document Revisions, and Download Document Revision are mounted on both `2.0` and `2.1`. List Recycled Document Revisions and Download Recycled Document Revision are mounted on `2.0` only. ### Three Endpoints, Three Jobs @@ -321,12 +321,22 @@ How a withheld revision appears depends on the call: ## Downloading a Revision -Full-record list, selected-revisions, and recycled-revisions responses include `download_url` when the caller has view access: +Full-record list, selected-revisions, and recycled-revisions responses include `download_url` when the caller has view access. + +**Request** — [Download Document Revision](https://developers.procore.com/reference/rest/document-revisions?version=2.0#download-document-revision) + +``` +GET /rest/v2.0/companies/{company_id}/projects/{project_id}/document_management/document_revisions/{document_revision_id}/download +``` + +**Request** — [Download Recycled Document Revision](https://developers.procore.com/reference/rest/document-revisions?version=2.0#download-recycled-document-revision) ``` -https://{host}/rest/v2.0/companies/{company_id}/projects/{project_id}/document_management/document_revisions/{document_revision_id}/download +GET /rest/v2.0/companies/{company_id}/projects/{project_id}/document_management/document_revisions/recycled_revisions/{document_revision_id}/download ``` +This endpoint is `2.0` only. It requires Recycle Bin view permission (`view_recycle_bin`). + GET that URL with the same OAuth 2.0 token. The service responds with HTTP 302 to a short-lived storage URL. Follow the redirect to retrieve the file bytes. Pass `no_redirect=true` to receive HTTP 200 with a JSON body instead of the 302. `download_url` is never present on a `view=ids_only` response — hydrate first, then download. Masked hydration rows also omit it. diff --git a/document_management_integration/document_management_intro.md b/document_management_integration/document_management_intro.md index 4140a4d..ac859a0 100644 --- a/document_management_integration/document_management_intro.md +++ b/document_management_integration/document_management_intro.md @@ -15,6 +15,7 @@ Before you begin working with the various Document Management API endpoints, we - **Overview** (this page) - [Technical Guide]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %}) +- [Working with Document Revisions]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_document_revisions.md %}) - [Metadata Details]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_metadata_details.md %}) - [API Reference: Document Management](https://developers.procore.com/reference/rest/document-uploads?version=2.0) — canonical endpoint list, maintained per API version diff --git a/document_management_integration/document_management_metadata_details.md b/document_management_integration/document_management_metadata_details.md index 17e92af..48695e7 100644 --- a/document_management_integration/document_management_metadata_details.md +++ b/document_management_integration/document_management_metadata_details.md @@ -18,6 +18,7 @@ This reference describes the metadata structure returned by **Document Upload** - [Overview]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}) - [Technical Guide]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_technical_guide.md %}) +- [Working with Document Revisions]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_document_revisions.md %}) - **Metadata Details** (this page) - [API Reference: Document Management](https://developers.procore.com/reference/rest/document-uploads?version=2.0) — canonical endpoint list, maintained per API version diff --git a/document_management_integration/document_management_technical_guide.md b/document_management_integration/document_management_technical_guide.md index 23ec87b..05b5dd4 100644 --- a/document_management_integration/document_management_technical_guide.md +++ b/document_management_integration/document_management_technical_guide.md @@ -15,6 +15,7 @@ This guide walks you through the complete API workflow for uploading documents, - [Overview]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_intro.md %}) - **Technical Guide** (this page) +- [Working with Document Revisions]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_document_revisions.md %}) - [Metadata Details]({{ site.url }}{{ site.baseurl }}{% link document_management_integration/document_management_metadata_details.md %}) - [API Reference: Document Management](https://developers.procore.com/reference/rest/document-uploads?version=2.0) — canonical endpoint list, maintained per API version