Skip to main content

Retrieve documentations for an asset

This guide explains how to retrieve documentations tree associated with a specific asset using the public API.

Prerequisites
  • A valid set of API credentials
  • A valid access token
  • A valid organization code
  • A valid asset ID

Step 1: Identify the asset​

You must provide either the assetId which can be either the asset uid or the external id of the asset you want to retrieve documentation for.

The asset uid format is asset-123 and the external id format is ERP:BAT001 (a composition of the type code and the asset code separated by a colon).

  • If it is not provided, the API returns a 400 Bad Request.
note

Ensure the user has the necessary access rights to the organization and asset to successfully retrieve the documentation.

Step 2: Call the API​

See: API Specification

GET /document-storage/v1/organizations/{organizationCode}/assets/{assetId}/documentations

Query Parameters:

Name Type Required Description assetId string true Unique identifier of the asset or External identifier of the asset

Important

At least one of assetUid or externalId must be provided.

Example request using assetUid:

curl -X GET "https://api.stonal.io/document-storage/v1/organizations/STONAL/assets/asset-123/documentations" \
-H "Authorization: Bearer {token}"

Example request using externalId:

curl -X GET "https://api.stonal.io/document-storage/v1/organizations/STONAL/assets/ERP:BAT001/documentations" \
-H "Authorization: Bearer {token}"

Possible Responses​

  • 200: Successfully retrieved documentation entries
  • 400: Bad request (both assetUid and externalId are missing)
  • 404: No documentation found for the given asset

Notes​

  • The API returns the documentation structure up to a default depth level (10 levels deep).
  • If the asset has no associated documentation, a 404 Not Found is returned.
  • Ensure you handle gracefully the cases where the asset does not yet have documentation.

Error Handling​

Common error scenarios:

  • Both assetUid and externalId are null → 400 Bad Request
  • Invalid or unauthorized asset reference → 404 Not Found
  • Missing or expired access token → 401 Unauthorized

Always verify the response status and handle error responses appropriately in your implementation.