Details on the risk management API
Last week we announced the alpha release of the TCAnnex API. Now we’re excited to provide a little more detail as to how the API works and what it can do from a technical perspective. If you haven’t already, head to our shop to download a key. The key is free for TCAnnex Substack Founders or $75 for 2025 access for non-founders.
Introduction
The API has two main endpoints: /documents and /elements. /documents is the main entry point for the API. Every API call will require you to use your key. It’s passed through the HTTP GET parameter “api_key”. For the rest of the documentation, we’ll assume you’re passing the parameter and will omit it.
Data Format
The return format for every HTTP GET request will be a JSON object. That object will ALWAYS be a NIST CPRT JSON object validated against the CPRT Schema. This format allows for the traversal of the API utilizing the “doc_identifier” and subsequent “element_identifiers”. Read more about the format here. View the JSON Schema here.
The basics are that the top-level JSON object is a set of four lists: documents, elements, relationships, and relationship_types. These four lists allow for the representation of not only the document, its metadata, and its constituent elements, but also the way in which those elements relate to one another. Essentially, this information creates a graph of the risk management data.
In the future, this property of the data format will become powerful when traversing networks of documents. For now, it is simply used for expressing the internal structure of the documents (which in itself is useful for discovery and analysis).
/documents
The /documents endpoint is the entry point for the TCAnnex API. This call is specifically designed for document discovery. If you simply issue an HTTP GET request to /documents, you will get a JSON object with all currently available documents. Note that the entire set of elements, relationships, and relationship_types will NOT be returned. However, this set of doc_identifiers will be used to further target future requests.
Example: HTTP GET “api.tcannex.com/documents”
(results truncated)
From that list, you can navigate to a given document using /documents/<doc_identifier>. Issuing a request to a valid doc_identifier endpoint will return a JSON object of all elements within that document and the structure of the document through the relationship objects. In other words, the entire set of elements, relationships, and relationship_types will be returned. This set of objects allows you to programmatically re-create, view, or integrate the structure of the document into your processes.
Example: HTTP GET “api.tcannex.com/documents/CSF_1_0_0”
(results truncated)
/elements
The /elements entry point is for fine-grained access to elements within a document. Every element can be uniquely identified with a doc_identifier and an element_identifier. Issuing an HTTP GET request to /elements/<doc_identifier>/<element_identifier> will return the information only relevant to that element.
Example: HTTP GET “api.tcannex.com/elements/CSF_1_0_0/RC.RP-1”
These results are not truncated and show the full CPRT JSON object. The relationships list will contain all relationships that element has, whether the element is a destination or source of the relationship.
For astute observers, you will notice that the relationship represented ties the element RC.RP-1 (CSF Subcategory) to the element RC.RP (CSF Category). These relationships allow for programmatic walking, building, or discovery of structure within or between documents and elements.
Conclusion
The current list of endpoints serves as a general mechanism to discover valid documents (and document-related metadata) as well as detailed mechanisms to navigate and use the data within those documents. We have already built internal and client-facing applications using this API and data format that have streamlined our ability to effectively and efficiently deliver risk management results. We are excited to hear from you! Email info@tcannex.com to learn more or provide feedback.