> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/web-application-and-api-protection-waap/discovery/discovery-1/documentation-and-inspector.md).
# Documentation and Inspector
**Documentation** refers to the specifications and manifests you use for testing and analysis. You can upload the documentation and use it in [Conformance Analysis](/web-application-and-api-protection-waap/discovery/risk/conformance-analysis.md) or [API Security Testing (AST) Scans](https://docs.traceable.ai/docs/ast-scans) according to your requirements. Traceable supports the following types of API documentation:
* Open API Specification
* Postman Collection
* Postman Environment
* GraphQL Schema
* WSDL
* MCP Server
You can use either of the above types and upload one or more files according to your requirements. For more information on uploading files, see [Uploading Documentation](#uploading-api-documentation).
Discovery Documentation
While uploading an API documentation, Traceable also provides you with the option to enable:
* [Naming](https://docs.traceable.ai/docs/api-discovery#api-naming) (*OpenAPI* documentation type only) — This option is useful when you want Traceable to use the specification for API naming.
* [Inspector](#api-inspector) (*OpenAPI* documentation type only) — This option is useful when you want Traceable to run the specification analyzer on your uploaded files.
* [Discovery](/web-application-and-api-protection-waap/discovery/discovery-1/inventory.md) (*OpenAPI*, *WSDL*, and *MCP Server* documentation types only) — This option is useful when you want Traceable to discover APIs or MCP assets from the uploaded specification.
For instructions on enabling these options, refer to the section below.
## Uploading Documentation
Navigate to the **Discovery** → **API Documentation** tab, and click **Upload** in the page’s top right corner to start uploading API documentation.
Uploading Documentation
As part of uploading the documentation, complete the following:
* **Documentation Name** — The name of the documentation. This field is non-editable as Traceable uses the uploaded specification name as the documentation name.
* **Documentation Type** — The type of documentation you wish to upload. For example, *Open API Spec*. For information on the MCP server manifest format, see Sample MCP Server manifest format
* **Enabled for Naming** — If enabled, the toggle allows Traceable to rename API endpoints according to the uploaded specification. For more information on API naming rules, see [API naming](https://docs.traceable.ai/docs/api-discovery#api-naming).
This option is available for the Open API Spec documentation type only.
* **Run Inspector** — If enabled, the toggle allows Traceable to analyze the uploaded specification for security concerns. For more information, see [API Inspector](#api-inspector).
This option is available for the Open API Spec documentation type only.
* **Enable Discovery** — If enabled, the toggle allows the discovery of assets (API and MCP server-related) based on the specification(s) you upload. Traceable lists the discovered assets on the Inventory page, using the documentation type as the source. For more information, see [Inventory](/web-application-and-api-protection-waap/discovery/discovery-1/inventory.md).
This option is available for OpenAPI Spec, WSDL, and MCP Server documentation types only.
* **Upload Documentation** — The documentation you wish to upload. You can upload a single file or a folder containing multiple files. Post-upload, you can update the file name and path according to your requirements. For information on the MCP manifest format, see [Sample MCP server manifest format](#sample-mcp-server-manifest-format).
When uploading a folder, you must ensure that all files are present in a single folder so that Traceable can understand the references (connections) between files. For more information, see API Referencing.
For the Postman Collection Documentation Type, Traceable only supports uploading v2.1.0 version files.
Traceable uses this file name as the documentation name. Following is the folder structure used in the above demo:
Once you have configured the above, click **Save**. Traceable displays the uploaded documentation as shown in the image below.
Uploaded API documentation
***
## Sample MCP server manifest format
The following is the format that you can use to upload the MCP server manifest:
```language-yaml
specFormatVersion: "1.0"
serverDefinition:
name: "Traceable API Security MCP Server"
description: "MCP server exposing Traceable's API security platform — API discovery, risk insights, and vulnerability data — to MCP-compatible AI clients"
owner: "traceable"
version: "1.0.0"
serverConnection:
url: "https://api.traceable.ai/mcp"
protocol: json-rpc-2.0
transport: http-streamable
path: /mcp
gatewayPath: /mcp/v1
authentication:
types: ["oauth2", "api-key"]
resourceDefinitions:
- uri: "traceable://server/instructions"
name: "Server Instructions"
title: "Server Instructions"
description: "Usage instructions and guidance for the Traceable API Security MCP server"
mimeType: "text/markdown"
size: 2048
icons:
- src: "https://www.traceable.ai/icons/instructions.png"
mimeType: "image/png"
sizes: "48x48"
annotations:
audience: ["user", "assistant"]
priority: 0.8
lastModified: "2026-08-01T00:00:00Z"
_meta:
source: "traceable-mcp"
category: "documentation"
promptDefinitions:
- name: "summarize-api-security-posture-v1"
title: "Summarize API Security Posture"
description: "Summarizes the current risk and vulnerability exposure for a given application or service"
arguments:
- name: "entity_name"
description: "The name of the application, service, or API to summarize"
required: true
- name: "max_entries"
description: "Maximum number of findings to include in the summary"
required: false
_meta:
source: "traceable-mcp"
category: "security"
toolDefinitions:
- name: "query-security-data-v1"
title: "Query Security Data"
description: |
Executes a validated query against the Traceable platform to retrieve API,
service, or vulnerability data.
Args:
query (str): The full query string to execute.
variables (object, optional): Dynamic values to substitute in the query.
Returns:
The result of the query execution.
inputSchema:
type: object
required: [query]
properties:
query:
type: string
description: "The full query string to execute"
variables:
type: object
additionalProperties: true
description: "Dictionary of dynamic values to substitute in the query"
additionalProperties: false
outputSchema:
type: object
additionalProperties: true
description: "Result of the query execution"
annotations:
title: "Query Security Data"
readOnlyHint: true
destructiveHint: false
idempotentHint: true
openWorldHint: true
_meta:
source: "traceable-mcp"
category: "query"
- name: "find-apis-by-pattern-v1"
title: "Find APIs by Pattern"
description: |
Finds API endpoints matching a name pattern, for discovery and security analysis.
Args:
pattern (str, MANDATORY): Pattern to match against API endpoint names.
limit (int, optional): Maximum number of results to return (default: 10).
Returns:
List of matching API endpoints including id, name, service name, risk score,
and risk category.
inputSchema:
type: object
required: [pattern]
properties:
pattern:
type: string
description: "Pattern to match against API endpoint names"
limit:
type: integer
default: 10
description: "Maximum number of results to return"
additionalProperties: false
outputSchema:
type: object
required: [results]
properties:
results:
type: array
description: "List of matching API endpoints"
additionalProperties: false
annotations:
title: "Find APIs by Pattern"
readOnlyHint: true
destructiveHint: false
idempotentHint: true
openWorldHint: true
_meta:
source: "traceable-mcp"
category: "discovery"
- name: "get-api-specification-v1"
title: "Get API Specification"
description: |
Fetches the API specification (OpenAPI) for a given API endpoint.
Args:
api_id (str, MANDATORY): The unique identifier of the API endpoint.
Returns:
api_id and definition (specification in YAML format) on success, or an error
message on failure.
inputSchema:
type: object
required: [api_id]
properties:
api_id:
type: string
description: "The unique identifier of the API endpoint"
additionalProperties: false
outputSchema:
type: object
properties:
api_id:
type: string
description: "The API identifier used in the query"
definition:
type: string
description: "The API specification in YAML format"
error:
type: string
description: "Error message if the request failed"
additionalProperties: false
annotations:
title: "Get API Specification"
readOnlyHint: true
destructiveHint: false
idempotentHint: true
openWorldHint: true
_meta:
source: "traceable-mcp"
category: "api-insights"
- name: "get-vulnerability-filter-values-v1"
title: "Get Vulnerability Filter Values"
description: |
Retrieves the supported values for vulnerability or issue filter keys, to use
when constructing a vulnerability query.
Args:
filter_keys (list[str], MANDATORY): List of filter keys to retrieve
supported values for, e.g. STATUS, SEVERITY, VULNERABILITY_CATEGORY.
Returns:
Dictionary mapping each filter key to its list of supported values and
value type.
inputSchema:
type: object
required: [filter_keys]
properties:
filter_keys:
type: array
items:
type: string
enum: [STATUS, SEVERITY, VULNERABILITY_CATEGORY, OWASP_API_TOP10]
description: "List of filter keys to retrieve supported values for"
additionalProperties: false
outputSchema:
type: object
additionalProperties: true
description: "Map of filter key to {values: [...], value_type: string}"
annotations:
title: "Get Vulnerability Filter Values"
readOnlyHint: true
destructiveHint: false
idempotentHint: true
openWorldHint: false
_meta:
source: "traceable-mcp"
category: "vulnerability"
```
***
## Documentation detailed view
After you upload documentation, click the document to view its details. Upon clicking, Traceable displays the following details based on the uploaded documentation type.
API Documentation Detailed View
* **Reference Tree** — The main specification file (parent specification) from the directory or folder you upload may contain one or more references, either nested or standalone. The tree visually represents these references, helping you navigate the connections between them. For example, in the above image, `openapi.yaml` is the main specification above and contains references to `orders.yaml`, `customers.yaml`, and `products.yaml` files. Similarly, `orders.yaml` and `customers.yaml` contain references to `customers.yaml` and `address.yaml` files respectively, while `products.yaml` does not contain any references.\
The reference tree visually illustrates how different API specifications are linked together. This makes it easy to see the structure and resolve missing references quickly. For more information, see [API Referencing](#api-referencing).
Traceable currently resolves references for OpenAPI Spec documentation only.
* **API** **Spec/MCP Server** — This section provides a detailed view of the specification or manifest. This is the resolved specification or manifest, meaning that Traceable resolves all references across the files that you uploaded.\
For example, the `openapi.yaml` file shown above contains references to `orders.yaml`, `customers.yaml`, and `products.yaml` files. However, those references are not visible in the image above because Traceable replaced them with the content in the files.
* **Paths found in OpenAPI spec** — This section lists all the paths Traceable discovers as part of the uploaded OpenAPI specification. If you enabled the API inspector while uploading the document, the section shows the issues found and the API inspector score corresponding to each path. For example, in the above image, the `/v1/customers/{customerid}` path contains 3 issues and an API inspector score of *68*. Similarly, this information is shown for all paths within an API documentation. For more information on the issues and score, see [API Inspector](#api-inspector).
Traceable currently discovers paths for OpenAPI Spec documentation only.
#### Specification uploads limits
* Maximum file size: **100 MB**
* Maximum number of files: **100**
You can upload individual files or an entire folder. Traceable processes all files included in the upload.
#### API Referencing
If you upload a directory or multiple specifications, Traceable goes through the main specification file (parent spec) and searches for references (`$ref`). Based on the files you upload, Traceable resolves the paths with their respective files. Based on these references, Traceable creates a reference tree that is visible when you edit any existing documentation or in the documentation detailed view, as shown below.
Reference Tree in the Edit and Detailed View
{% hint style="info" %}
* While uploading the files, you must ensure that the files are structured under a single directory such that Traceable can identify the specification’s location.
* API referencing is available for the *Open API Spec* documentation type only.
{% endhint %}
Traceable highlights the unresolved references with a red dot at the top right of the file or folder on the API Documentation page, for example, `paths.yaml` folder in the above image. This mainly occurs when the file is missing. At that time, you can edit the API document and do either of the following in the **Reference Tree** section:
Upload missing documentation
* Click the **Upload** icon and upload the missing documentation.
* Click the missing document field and select an existing one from the drop-down.
If you select from the existing specifications, Traceable moves that file to the path mentioned in the main specification (parent specification) file.
Traceable tries to resolve the references based on the above documents. If it is unable to do so due to issues with the documents, you can repeat the above step.
***
## API Inspector
The API Inspector is a code analyzer of the Open API documentation that you upload. If you enable this feature, Traceable goes through the documentation and produces a result at the path level. Traceable performs these checks once a day, and as soon as you update or upload the API documentation.
{% hint style="info" %}
The API Inspector feature is available for the *Open API Spec* documentation type only.
{% endhint %}
The API inspector checks for issues in three areas:
* **Security** — This category checks for potential security issues, such as weak authentication mechanisms, missing headers, inaccurate references, etc, that can expose APIs to attacks.
* **Format** — This category verifies whether the API paths adhere to the expected structure and formatting rules outlined in the OpenAPI document, ensuring proper syntax and compliance with API standards.
* **Data Validation** — This category verifies whether the data types and structures defined in the OpenAPI document are properly implemented, ensuring that inputs and outputs conform to the expected formats, constraints, and value ranges.
Each of the above categories has multiple checks associated with it. Traceable provides these checks out-of-the-box and executes them on each path present in the OpenAPI specification and calculates an API Inspector score. The score is calculated for each path and for the entire uploaded API documentation. The audit score ranges from 0-100, with 100 being the highest. A higher score represents better compliance.
API Inspector
Traceable also shows the following detailed information for each path. To view this information, navigate to the detailed view page of an API documentation, **Paths found in the OpenAPI spec** section, and click a path.
* API Inspector score for that path
* The list of checks performed on that path, along with the check name, category, description, severity, and status (fail or pass). You can also click each check to view its description and a detailed example of the possible issue. This example is context-sensitive, and you can use it to fix the issue in your uploaded document. Traceable also lists the potential vulnerabilities detected by that check.
If you fix either failed check in the OpenAPI document, Traceable runs the API inspector and updates its status accordingly.