Welcome to Documoto's Headless API documentation. Designed exclusively for our customers, our Headless Endpoints offer seamless integration and unparalleled flexibility. These set of services are intended de-couple Documoto’s back-end from front-end and allow customers to access, manage, create, and delete Documoto resources outside of the Documoto user interface.
\nPurpose-built to bridge the gap between front-end applications and Documoto's robust back-end repository, these endpoints prioritize efficiency and data security. By incorporating user access controls and privileges, they empower you to deliver exceptional experiences to internal support resources, customers, and equipment operators and servicers.
\nWhether fetching comprehensive resources or specific information via dynamic query parameters, these endpoints facilitate seamless integration into any application or system.
\nTo start using the Headless APIs, you need to understand the requirements –
\nYou must use a valid API Key to send requests to the API endpoints.
\nUnderstand Documoto API’s rate and usage limits - linked here.
\nAll API’s require developers to authenticate via HTTPS-secured communications.
\nBase URL's needed:
\nProduction: https://documoto.digabit.com/api/ext
\nIntegration: https://integration.digabit.com/api/ext
\nWhen query parameters include characters that are reserved or potentially unsafe within URLs, you must perform URL encoding before using them in an API Request.
\nThe API’s generally returns request responses in JSON format*
\nAPI Key is obtained by a Documoto administrator. For more information on creating/obtaining a key please see our Knowledge Base article here: https://support.documoto.com/hc/en-us/articles/4414871920915-REST-API-Web-Services-Reference
\nThe Documoto Headless REST APIs will use API Key-based authentication for authentication and authorization. An HTTP Basic header containing an access key is required to authenticate each request.
\nAPI Keys are generated and presented once to the user that generated them.
\nThey are not stored or accessible by us (Documoto) or the administrator that created them.
\nAPI Keys can be regenerated or revoked, but never accessed or viewed again.
\nUsers do not have to include credentials when using the API Keys.
\nAPI Keys are also not supplied to a third party (such as with OAuth).
\nAll communication with Documoto is also done via HTTPS, which requires TLS.
\nWhen interacting with Documoto's API endpoints, you may encounter various response status codes indicating the outcome of your request. Below is a comprehensive list of response status codes along with their meanings:
\nWhen handling errors, developers should pay close attention to the status code provided in the API response, as it indicates the nature of the issue encountered. Also, accompanying error messages may provide more context to help troubleshoot and resolve the issue effectively.
\nIn managing large datasets returned by APIs, implementing pagination is a fundamental practice for developers. Pagination empowers developers to efficiently retrieve and display data in manageable chunks, thereby significantly enhancing performance and user experience.
\nTo optimize data retrieval and navigation, Headless REST endpoints adhere to off-set pagination standards. Below are the specifications for pagination management:
\nPagination Guidelines:
\nBy default, the offset parameter is set to 0.
\nThe limit parameter defines the maximum number of items to retrieve per page. This can be adjusted to any desired value.
\nEach request can fetch a maximum of 100 results at once.
\nResponses include a total count of all available results.
\nPagination is managed by incrementing the offset parameter.
\nThe next_page attribute provides the URL to access the next page of results.
\nWhen reaching the last page, the next_page attribute will be null.
\nThese standardized practices ensure smooth and efficient pagination across all Headless REST endpoints, enabling developers to seamlessly retrieve and navigate through data.
\nFile Size Limits and Rate Multiplier for API Users
\nIn utilizing Documoto's Headless API, it's important to be mindful of file size constraints and potential rate limits to ensure smooth operation and optimal performance. Here's a breakdown of the limitations and considerations you should be aware of:
\nFile Size Limit:
\nInbound and Outbound Files: Generally constrained at 1 GB. This means any files being sent to or received from the API should not exceed this size limit.
\nIllustrations for Interactive Pages: Limited to 25 MB to maintain consistency with Page Builder file size limits. This restriction applies specifically to illustrations added for interactive pages.
Any files surpassing these size limits will trigger a clear error message, providing feedback to the API user regarding the exceeded limit.
Rate Multiplier for Resource Intensive Activities:
\nCertain API activities are resource intensive and may require additional processing time and resources. To manage these effectively, a rate multiplier is introduced for such activities, clearly communicated in the documentation for API users.
\nFor every request against any rate-limited activity, there will be a multiplier of 10 additional requests. This ensures that resource-intensive tasks are processed efficiently while maintaining system stability and performance.
Activities subjected to this rate multiplier include:
• Copy Access Controls
• Print Job PDFs
• Search Export ZIPs
• Media Export Job MDZs/ZIPs
Be mindful of these considerations when designing and implementing your API interactions to ensure smooth operation and adherence to system constraints.
In Documoto, API usage for each customer is governed by their Subscription Plan, which outlines the allowed number of requests within a one-hour timeframe. To ensure effective enforcement of this limit, Documoto implements throttling based on five-minute intervals.
\nDetermining Throttling Intervals
Throttling intervals are calculated by dividing the hourly request limit by twelve, resulting in five-minute intervals. Refer to the table below for details:
Throttling Process
\nDocumoto actively monitors API requests, performing checks every ten seconds to determine if the request count exceeds the limit for the current five-minute interval. If the limit is surpassed, subsequent requests are throttled until the end of the five-minute interval. Once the interval concludes, users can resume submitting requests.
\nAs Documoto's APIs evolve to enhance interoperability features, we strive to make non-breaking changes to continuously improve our Headless REST endpoint offerings. Below, we outline our approach to handling changes and provide guidance on how to adapt your applications accordingly.
\nImportant Considerations
We may introduce changes without prior notice in cases of critical product bugs or legal, security, or privacy concerns, especially if they constitute breaking changes.
As a best practice, we highly recommend implementing client-side handling for unknown response elements. This ensures that your code remains flexible and tolerant of errors, thereby increasing the robustness and interoperability of your integrations and software applications using Documoto APIs.
\nDefinitions
\nBreaking Change: A change that may require modifications to your application to prevent disruption to your integration. In such cases, Documoto will version the endpoint and require migration from the previous version within 6 months. Examples include:
\nRemoving endpoints
\nRenaming endpoints, request/response attributes, query parameters and headers
\nRemoving non-optional response body attributes
\nRemoving non-optional response headers
\nRemoval of an allowed parameter, request field or response field
\nAddition of a required parameter or request field without default values
\nChanges to the intended functionality of an endpoint. For example, if a DELETE request previously used to softdelete the resource but now hard deletes the resource.
\nChanging the nesting structure of request or response body attributes*
\nNon-breaking Change: A change that can be adapted to at your discretion and pace without causing disruption. We will communicate such changes after they are implemented. Examples include:
\nAddition of new endpoints
\nAddition of new media types
\nRemoval of optional response attributes
\nAddition of new fields in the following scenarios:
\nNew fields in responses
\nNew optional request fields or parameters
\nNew required request fields that have default values
\nAddition of a new value returned for an existing text field
\nChanging non-optional fields in the following scenarios:
\nNon-optional request body attributes to optional
\nNon-optional query parameters to optional
\nNon-optional request headers to optional
\nChanges to the order of fields returned within a response
\nAddition of an optional request header
\nRemoval of redundant request header
\nChanges to the length of data returned within a field
\nChanges to the overall response size
\nChanges to error messages. We do not recommend parsing error messages to perform business logic. Instead, you should only rely on HTTP response codes and error codes.
\nFixes to HTTP response codes and error codes from incorrect code to correct code
\nLook out for email communication from Documoto regarding notable non-breaking changes or upcoming new versions for breaking changes.
\nFor breaking changes, API responses will include a header indicating that an endpoint has been deprecated and will be removed. Additionally, Documoto Administrators will be notified about deprecated APIs for your tenant.
\nTimelines for API version deprecation will be determined based on customer change management needs. Generally, older versions will be deprecated within 6 months of the release of new versions.
\nFetches information and attached content or links for a specific part in the Documoto library.
\nAPI users must specify a part ID in the URL to retrieve part information.
\nThe response includes all critical part details such as Part ID, Part Number, Supplier information, Part Name, Description, Created and Updated Dates, UOM, and attachments.
\nAPI users can override the locale using a locale query parameter, which honors standard fallback logic.
\nMethod: GET
\nURL: {{baseUrl}}/library/parts/v1/{{part-id}}
Overrides the default locale for name and description translations, following fallback logic (e.g., locale=en-us).
\n","type":"text/plain"},"key":"locale","value":"String"}],"variable":[]}},"response":[{"id":"d7a15689-6260-4ae8-913d-c9823e3b19b0","name":"200","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"{{authString}}"}],"url":{"raw":"{{baseUrl}}/library/parts/v1/{{part-id}}","host":["{{baseUrl}}"],"path":["library","parts","v1","{{part-id}}"],"query":[{"key":"locale","value":"String","description":"Overrides the default locale for name and description translations, following fallback logic (e.g., locale=en-us).","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 11 Dec 2024 21:53:07 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": 3322724,\n \"partNumber\": \"000174\",\n \"supplierKey\": \"CALLIFTEST\",\n \"supplierId\": 580,\n \"locale\": \"en-US\",\n \"name\": \"CE .375X1.25 .156X1.09\",\n \"description\": \"\",\n \"created\": \"2022-06-10T14:04:27Z\",\n \"updated\": \"2022-06-10T14:04:27Z\",\n \"uom\": \"EA\",\n \"orderable\": true,\n \"visible\": true,\n \"thumbnailUrl\": null,\n \"attachments\": [],\n \"tagCount\": 5,\n \"commentCount\": 0,\n \"attachmentCount\": 0,\n \"relatedMediaCount\": 0,\n \"pagesWhereUsedCount\": 2,\n \"booksWhereUsedCount\": 1,\n \"orderSuggestionsCount\": 0\n}"},{"id":"8688819a-4402-43d2-a7ef-07303dcfbddb","name":"401","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"{{authString}}","disabled":true}],"url":{"raw":"{{baseUrl}}/library/parts/v1/{{part-id}}","host":["{{baseUrl}}"],"path":["library","parts","v1","{{part-id}}"],"query":[{"key":"locale","value":"String","description":"Overrides the default locale for name and description translations, following fallback logic (e.g., locale=en-us).","disabled":true}]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 11 Dec 2024 21:53:54 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"WWW-Authenticate","value":"Basic realm=\"Documoto\", charset=\"UTF-8\""}],"cookie":[],"responseTime":null,"body":"{\n \"action\": \"exception-caught\",\n \"error\": \"UNAUTHORIZED\",\n \"handled-by\": \"jax-rs-handler\",\n \"message\": \"HTTP 401 Unauthorized\",\n \"requestId\": null,\n \"response-code\": 401,\n \"tenantKey\": null,\n \"timestamp\": 1733954034503,\n \"username\": null\n}"},{"id":"0f5d3381-f2e5-40ad-953d-d2c613831fdd","name":"404","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"{{authString}}"}],"url":{"raw":"{{baseUrl}}/library/parts/v1/{{part-id}}","host":["{{baseUrl}}"],"path":["library","parts","v1","{{part-id}}"],"query":[{"key":"locale","value":"String","description":"Overrides the default locale for name and description translations, following fallback logic (e.g., locale=en-us).","disabled":true}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 11 Dec 2024 21:54:02 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"action\": \"exception-caught\",\n \"error\": \"NOT_FOUND\",\n \"handled-by\": \"jax-rs-handler\",\n \"message\": \"Part not found\",\n \"requestId\": null,\n \"response-code\": 404,\n \"tenantKey\": null,\n \"timestamp\": 1733954042026,\n \"username\": null\n}"}],"_postman_id":"7134dd32-366b-4b22-8b7f-9aa6a099775f"},{"name":"Retrieve Part Attachments","id":"ac221391-fd3e-45c1-b08e-1fa3699df044","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"{{authString}}"}],"url":"{{baseUrl}}/library/parts/v1/{{part-id}}/attachments/{{part-attachment-id}}","description":"Retrieves attachments associated with a specific part in the Documoto library. This endpoint provides access to files such as documents, images, and videos linked to a given part.
\nAPI users must specify the part ID and the specific attachment ID to retrieve the file: /library/parts/v1/{part-id}/attachments/{attachment-id}.
\nIf the file cannot be found or if the part ID is invalid, a 404 error is returned with the description: “Unable to locate the file.”
\nAPI users can only retrieve attachments for part IDs they have access to.
\nThe response is an application/octet-stream file of the requested attachment.
\nMethod: GET
\nURL: {{baseUrl}}/library/parts/v1/{{part-id}}/attachments/{{part-attachment-id}}