How to Retrieve Project-Related Documents Using the Project Insight API

Overview

The Project Insight REST API allows developers to retrieve items associated with a specific project using the /api/item-utility/related-items/{id} endpoint.

This article demonstrates how to retrieve project-related items, identify associated documents, and access their metadata using C# and Python.

The examples use authenticated HTTP GET requests and display document information, including names, types, and available URLs.

Important: This endpoint returns the items listed as related to a project. It may include documents, tasks, and other Project Insight items. It does not necessarily return every file stored within the project's folder or task hierarchy.

Prerequisites

Before following the examples in this article, you will need:

• A valid Project Insight workspace URL.
• A valid Project Insight API token.
• The GUID of the project whose related documents you want to retrieve.
• Appropriate permissions to access the project's related items.
• A C# or Python development environment.

If you have not configured API access, follow How to Set Up REST API Access in Project Insight before continuing.

1. Understanding the related-items endpoint

Project Insight provides the following endpoint for retrieving items associated with a project:

GET /api/item-utility/related-items/{id}

The {id} parameter represents the unique identifier (GUID) of the project.

For example:

GET https://your-workspace.projectinsight.net/api/item-utility/related-items/00000000-0000-0000-0000-000000000000

Replace the example GUID with the ID of an existing Project Insight project.

The endpoint returns a JSON collection containing metadata about the related items.

Response properties

Some useful properties returned by this endpoint include:

These properties allow an application to inspect the related items returned by the endpoint and identify records representing files or documents.

For the complete list of available response properties, see the GET item-utility/related-items/{id} API Reference.

2. Test the endpoint in Postman

Before implementing the request in an application, you can test it using Postman.

1. Create a new HTTP request in Postman.
2. Set the HTTP method to GET.
3. Enter your Project Insight workspace URL followed by /api/item-utility/related-items/ and the desired Project ID.
4. Open the Headers tab.
5. Add api-token as the key and your API token as the value.
6. Add Accept with the value application/json.
7. Select Send.

If successful, the API returns an HTTP 200 OK response with a JSON collection of related items.

The returned collection may contain document records as well as other related item types.

If there are no related items, the response may be an empty collection.

3. Retrieve project-related documents using C#

The following example uses the .NET HttpClient class to retrieve all related items for a given project.

It then identifies records that appear to represent files or documents using the returned type information and download URLs.

Requirements: .NET 6 or later.

C# example

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;

// STEP 1: Enter your Project Insight workspace URL.
string baseUrl =
    "https://your-workspace.projectinsight.net/";

// STEP 2: Retrieve your existing API token.
// See the API setup article for instructions on creating one.
string apiToken =
    Environment.GetEnvironmentVariable("PI_API_TOKEN")
    ?? throw new Exception("PI_API_TOKEN is not configured.");

// STEP 3: Enter the GUID of the project.
// Replace this value with your Project Insight Project ID.
string projectId =
    "00000000-0000-0000-0000-000000000000";

// STEP 4: Create and configure the HTTP client.
using HttpClient client = new HttpClient();

client.BaseAddress = new Uri(baseUrl);

// Add the token required for Project Insight authentication.
client.DefaultRequestHeaders.Add("api-token", apiToken);

// Request a JSON response.
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json")
);

try
{
    // STEP 5: Build the related-items endpoint using
    // the specified Project ID.
    string endpoint =
        $"api/item-utility/related-items/{projectId}";

    // Send an authenticated GET request.
    HttpResponseMessage response =
        await client.GetAsync(endpoint);

    // Throw an exception for unsuccessful HTTP responses.
    response.EnsureSuccessStatusCode();

    // STEP 6: Read and parse the returned JSON collection.
    string responseBody =
        await response.Content.ReadAsStringAsync();

    using JsonDocument json =
        JsonDocument.Parse(responseBody);

    int documentCount = 0;

    // STEP 7: Examine every related item returned by the API.
    foreach (JsonElement item in
             json.RootElement.EnumerateArray())
    {
        // Read the properties used to identify documents.
        string name = GetField(item, "Name");
        string sdkType = GetField(item, "InternalSDKType");
        string type = GetField(item, "TypeDescription");
        string downloadUrl =
            GetField(item, "UrlDownloadFull");
        string itemUrl = GetField(item, "UrlFull");

        // STEP 8: Identify records that appear to be files.
        // This is an example filter. Inspect the actual
        // type values returned by your workspace to confirm
        // that all relevant document types are included.
        bool isDocument =
            sdkType.Contains(
                "File",
                StringComparison.OrdinalIgnoreCase
            )
            || type.Contains(
                "File",
                StringComparison.OrdinalIgnoreCase
            )
            || type.Contains(
                "Document",
                StringComparison.OrdinalIgnoreCase
            )
            || !string.IsNullOrWhiteSpace(downloadUrl);

        if (!isDocument)
        {
            continue;
        }

        documentCount++;

        // STEP 9: Display the document's information.
        Console.WriteLine($"Document: {name}");
        Console.WriteLine($"Type: {type}");
        Console.WriteLine($"Item URL: {itemUrl}");
        Console.WriteLine($"Download URL: {downloadUrl}");
        Console.WriteLine("-------------------------");
    }

    Console.WriteLine(
        $"Document candidates found: {documentCount}"
    );
}
catch (HttpRequestException ex)
{
    // Handle invalid requests, authentication errors,
    // and other HTTP-related failures.
    Console.WriteLine($"API request failed: {ex.Message}");
}
catch (JsonException ex)
{
    // Handle responses that are not valid JSON.
    Console.WriteLine($"JSON error: {ex.Message}");
}

// Helper function to retrieve JSON fields safely.
static string GetField(
    JsonElement item,
    string propertyName)
{
    return item.TryGetProperty(
        propertyName,
        out JsonElement value
    )
        ? value.ToString()
        : "";
}

How the C# example works

The example creates an authenticated connection to the Project Insight workspace and builds a request using the specified Project ID.

It then sends a GET request to /api/item-utility/related-items/{id}.

Once the JSON response is received, the application iterates through the returned collection and reads properties such as Name, InternalSDKType, TypeDescription, and UrlDownloadFull.

The example uses these properties to identify records that appear to represent documents.

Because item types may vary, inspect the actual values returned by your workspace before treating the example filter as exhaustive.

4. Retrieve project-related documents using Python

Python can retrieve the same information using the requests library.

First, install the required library:

pip install requests

Python example

import os
import requests

# STEP 1: Enter your Project Insight workspace URL.
base_url = "https://your-workspace.projectinsight.net"

# STEP 2: Retrieve your existing API token.
api_token = os.environ["PI_API_TOKEN"]

# STEP 3: Specify the GUID of the project.
project_id = "00000000-0000-0000-0000-000000000000"

# STEP 4: Build the endpoint URL.
url = (
    f"{base_url}/api/item-utility/related-items/"
    f"{project_id}"
)

# STEP 5: Configure authentication headers.
headers = {
    "api-token": api_token,
    "Accept": "application/json"
}

try:
    # STEP 6: Send the GET request.
    response = requests.get(
        url,
        headers=headers,
        timeout=30
    )

    # Raise an exception if the request failed.
    response.raise_for_status()

    # STEP 7: Convert the JSON response into a Python list.
    related_items = response.json()

    if not isinstance(related_items, list):
        raise ValueError("Expected a JSON array of related items.")

    # STEP 8: Identify items that appear to be documents.
    documents = []

    for item in related_items:
        sdk_type = str(item.get("InternalSDKType") or "")
        type_description = str(
            item.get("TypeDescription") or ""
        )
        download_url = item.get("UrlDownloadFull")

        # Example classification based on type or download URL.
        # Adjust this filter after reviewing actual response data.
        is_document = (
            "file" in sdk_type.lower()
            or "file" in type_description.lower()
            or "document" in type_description.lower()
            or bool(download_url)
        )

        if is_document:
            documents.append(item)

    # STEP 9: Display each matching document.
    for document in documents:
        print("Document:", document.get("Name"))
        print("Type:", document.get("TypeDescription"))
        print("Item URL:", document.get("UrlFull"))
        print("Download URL:", document.get("UrlDownloadFull"))
        print("-------------------------")

    print(f"Document candidates found: {len(documents)}")

except requests.exceptions.RequestException as error:
    # Handle authentication, network, and HTTP errors.
    print(f"API request failed: {error}")

except ValueError as error:
    # Handle an unexpected JSON response structure.
    print(f"Response error: {error}")

How the Python example works

The Python example performs the same operations as the C# example.

It constructs the endpoint using the supplied Project ID and authenticates the request using the api-token HTTP header.

Once the API returns a JSON response, the application examines each related item and identifies potential document records using the type and download URL properties.

Finally, it prints each matching document's name, type, and URLs.

The list of related_items contains the complete collection returned by this endpoint, while documents contains the records identified by the example filter.

5. Understanding the returned documents

The /api/item-utility/related-items/{id} endpoint returns metadata describing the items related to a project.

For document records, this metadata may include URLs that allow the application to open or download the associated file.

Two useful properties are:

• UrlFull: The full URL used to view the item in Project Insight.
• UrlDownloadFull: The full URL used to download the item, when available.

These properties can be used by another application to provide document links or initiate downloads.

A download URL should not be assumed to be publicly accessible. Access may still require valid Project Insight authentication and appropriate permissions.

Are all project documents returned?

Not necessarily.

This endpoint retrieves related items associated with the supplied project. It should not be treated as a comprehensive search of every document stored anywhere within the project.

For example, a file attached to a task or stored within a nested folder may not appear in the project's direct related-items collection.

If you need files attached directly to a specific item, see the GET /api/file-item/children/{itemId} reference.

For broader searches across project files, see the GET /api/file-item/search reference.

6. Troubleshooting

401 Unauthorized

Verify that the API token is valid, has not expired, and is correctly included in the api-token HTTP request header.

403 Forbidden

Check that the user associated with the token has permission to access the project and its related items.

404 Not Found

Verify that the endpoint path is correct and that the Project ID is a valid GUID belonging to a project in the intended workspace.

No documents are returned

If the API returns an empty collection, confirm that the specified project has related items.

If the API returns other items but no documents are identified, review the InternalSDKType, TypeDescription, and UrlDownloadFull values returned by the endpoint.

The example filtering logic may need to be adjusted for the document types present in your workspace.

Also confirm that the files you expect to retrieve are actually associated with the project through its Related Items functionality rather than stored elsewhere in the project hierarchy.

Additional Resources

• How to Set Up REST API Access in Project Insight
• Project Insight REST API References
• GET /api/item-utility/related-items/{id}
• GET /api/file-item/children/{itemId}
• Project Insight References & Models