--- title: "Downloading API Documentation" slug: "download-api-spec" description: "Learn to download API documentation (OpenAPI, JSON, WSDL) via Traceable's APIs. Generate specs for domains, services, or environments in 3 steps: trigger, check status, and download." tags: ["OpenAPI spec", "public APIs"] updated: 2025-12-16T05:18:53Z published: 2025-12-16T05:18:53Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # Downloading API Documentation ##### Updates (January 2025 to March 2025) - *February 2025* — Updated the page to add information about downloading the specification for SOAP APIs in the WSDL format. API Catalog lets you view and download an API endpoint's Traceable-discovered documentation (specification). #### How does Traceable facilitate downloading API specifications? Traceable provides GraphQL and REST APIs for downloading the specifications for all the API endpoints. #### What can I download the specifications for? You can download the specifications for all endpoints under the following: - Domain - Environment - Service - Label #### What formats can I download the specification in? You can download this specification in either of the following formats: - Open API YAML - Open API JSON - WSDL (for *SOAP* API types only) #### What are the steps to download the specification? There are three steps to generate and download the specification using Traceable's APIs: - [Step 1 - Trigger the specification generation](/v1/docs/openapi-spec-ops#step-1-trigger-the-specification-generation) - [Step 2 - View the specification generation status](/v1/docs/openapi-spec-ops#step-2-view-the-specification-generation-status) - [Step 3 - Download the specification](/v1/docs/openapi-spec-ops#step-3-download-the-specification) You can complete steps 1 and 2 using a GraphQL client, such as Altair. To complete step 3, you must use a browser or any REST API client. --- ## Step 1 - Trigger the Specification Generation You can use the Traceable Platform to download the specification for an API Endpoint. For more information, see the **Overview** tab on the [Endpoint Details](https://docs.traceable.ai/docs/endpoint-details#openapi-spec) page. This step discusses how to trigger the specification generation for all API endpoints under a domain, environment, service, or label. [Step 2](/v1/docs/download-api-spec#step-2-view-the-specification-generation-status) discusses the link to download the specification. To trigger the process of OpenAPI specification generation, use the following API endpoint. As part of specification generation, you can include high-level information about endpoints that are under learning or exclude. For more information, see the Request Parameters section under Endpoint Details below. The following sections discuss: - The API endpoint details, schema, and request parameters - The steps to retrieve the credentials based on the asset you wish to generate the specification for - Sample requests and responses that you can use to make the API request ### Endpoint Details The Endpoint URL is — `https://<traceable_public_api_url>/graphql` . In this URL, replace `<traceable_public_api_url>` accordingly, for example, `https://api.traceable.ai/graphql`. The endpoint URL, along with the following metrics, is required to trigger the specification generation: | **Field** | `createApiDefinition` | | --- | --- | | **Type** | mutation | | **Allowed role(s)** | Account owner, Security Admin, and Security Analyst. For more information on Traceable roles, see [Teams and roles](/docs/rbac). | | **Authorization** | Requires Traceable Platform token. For more information, see [Public APIs](https://docs.traceable.ai/docs/public-apis#step-1-copy-the-platform-api-token). | ##### Schema You can access the schema by following the [Public APIs](https://docs.traceable.ai/docs/public-apis) document. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_openapispec_schema.png) ##### Request Parameters The following table lists the different parameters that you can use in the API request: | GraphQL Argument | GraphQL Field | Type | Required | Default Behavior (if required) | Possible Values and Their Meaning | | --- | --- | --- | --- | --- | --- | | apiDefinitionSpec | learningEndpointStrategy | Enum | Optional | MENTION | - **MENTION** — Use `MENTION` if you wish to include high-level details of the Endpoints being learned as part of the specification. - **EXCLUDE** — Use `EXCLUDE` if you do not wish to include the Endpoints being learned as part of the specification. | | format | Enum | Required | - | - **OPEN_API_YAML** — Use `OPEN_API_YAML` if you wish to download the API specification in YAML format. - **OPEN_API_JSON** — Use `OPEN_API_JSON` if you wish to download the API specification in JSON format. - **WSDL** (for **SOAP** APIs only) — Use `WSDL` if you wish to download the API specification in WSDL format. | ### Retrieve Credentials You must have either of the following credentials to start generating the: | Specification for… | Description | | --- | --- | | **Domain ID** | When you want to generate the specification for all the API endpoints under a domain. | | **Service ID** | When you want to generate the specification for all the API endpoints under a service. | | **Label Name(s)** | When you want to generate the specification for all the API endpoints with one or more labels. | | **Environment Name** | When you want to generate the specification for all the API endpoints under an environment. | Refer to the following tabs for the steps to retrieve these credentials. Domain IDService IDLabel Name(s)Environment Name Complete the following steps to retrieve the domain ID: 1. Log in to the Traceable Platform and navigate to **Catalog**→ **Inventory → Domains**tab. 2. Click the domain for which you want to retrieve the domain ID. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_catalog_open_api_spec_domain_id(1)(1).png) 3. Copy the domain ID (hexadecimal ID) from the URL. For example, in the above screenshot, the domain ID is `0267a887-5c8d-57b5-a08e-41cca8ec5196`. Complete the following steps to retrieve the service ID: 1. Log in to the Traceable Platform and navigate to **Catalog**→ **Inventory → Services**tab. 2. Click the service for which you want to retrieve the service ID. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_catalog_open_api_spec_service_id(1).png) 3. Copy the service ID (hexadecimal ID) from the URL. For example, in the above screenshot, the service ID is `837ce000-71fd-3335-b709-7486c7525949`. You can generate the specification for one or more labels. To generate the specification for multiple labels, you must specify the label names within square brackets, with each label name separated by a comma. See Examples. Complete the following steps to retrieve the label name(s): 1. Log in to the Traceable platform and navigate to **Settings** → **Label Management**→ **Labels** tab. 2. Copy the label name(s) you want to generate the specification for. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_catalog_open_api_label_name.png) Complete the following steps to retrieve the environment name: 1. Log in to the Traceable platform and navigate to **Catalog**. 2. Copy the environment name from the **Environments** drop-down in the page’s top right corner. ### Sample Requests and Responses You can refer to The following sample requests and responses for generating the specification. You can expand the sections according to your requirements. ##### **Domains** **Example request** ```actionscript mutation CreateApiDefinition {  createApiDefinition(    apiDefinitionSpec: { format: OPEN_API_YAML, domainId: "b721093e-3870-55ca-a03c-d4fe721b6708", learningEndpointStrategy: MENTION }  ) {    id  } } ``` **Example response** ```actionscript {  "data": {    "getApiDefinition": {      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"    }  } } ``` ##### **Services** **Example request** ```actionscript mutation CreateApiDefinition {  createApiDefinition(    apiDefinitionSpec: { format: OPEN_API_YAML, serviceId: "b721093e-3870-55ca-a03c-d4fe721b6708", learningEndpointStrategy: MENTION }  ) {    id  } } ``` **Example response** ```actionscript {  "data": {    "getApiDefinition": {      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"    }  } } ``` ##### **Labels** **Example request** ```actionscript mutation CreateApiDefinition {  createApiDefinition(    apiDefinitionSpec: { format: OPEN_API_YAML, labels: ["label1", "label2", "label3"] }  ) {    id  } } ``` **Example response** ```actionscript {  "data": {    "getApiDefinition": {      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"    }  } } ``` ##### **Environment** **Example request** ```actionscript mutation CreateApiDefinition {  createApiDefinition(    apiDefinitionSpec: { format: OPEN_API_YAML, environment: "environment_name" }  ) {    id  } } ``` **Example response** ```actionscript {  "data": {    "getApiDefinition": {      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"    }  } } ``` > [!NOTE] > Note > > Make a note of the ID returned in the response. It is required to view the status of the specification generation. --- ## Step 2 - View the Specification Generation Status This step discusses how you can view the status of the specification generation. While the following API endpoint displays the status of the specification generation, it provides a URL that you can use to download the specification. The steps to download the specification are discussed in [Step 3](/v1/docs/openapi-spec-ops#step-3-download-the-specification). You can use the **API's Field metric** to view whether the specification generation is successful or has failed. The response displays the message appropriately. If the specification generation is successful, the response is sent with the URL to download the specification. The following sections discuss: - The prerequisites for viewing the specification generation status - The API endpoint details, schema, and request parameters - Sample request and response that you can use to make the API request ### Before you Begin You must have the ID generated as part of the [Step 1](/v1/docs/openapi-spec-ops#step-1-trigger-the-specification-generation). You can view the ID in the sample response provided in the previous section. ### Endpoint Details The Endpoint URL is — `https://<traceable_public_api_url>/graphql` . In this URL, replace `<traceable_public_api_url>` accordingly, for example, `https://api.traceable.ai/graphql`. The endpoint URL along with the following metrics is required to view the specification generation status: | **Field** | `getApiDefinition` | | --- | --- | | **Type** | query | | **Allowed role(s)** | Account owner, Security Admin, Developer, and Security Analyst. For more information on Traceable roles, see [Teams and roles](/docs/rbac). | | **Authorization** | Requires Traceable Platform token. For more information, see [Public APIs](https://docs.traceable.ai/docs/public-apis#step-1-copy-the-platform-api-token). | ##### Schema You can access the schema by following the [Public APIs](https://docs.traceable.ai/docs/public-apis) document. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_openapispec_viewstatus_schema.png) ### Sample Request and Response Following is a sample request and response to view the status of the specification generation. You must use the ID generated when you triggered the specification generation. | Request | Response | | --- | --- | | ```actionscript query GetApiDefinition { getApiDefinition(id: "6f93e41b-0bc5-5787-9e07-ba085b1c5e46") { downloadUrl status statusUpdatedTimestamp messages } } ``` | ```actionscript { "data": { "getApiDefinition": { "downloadUrl": "https://app.traceable.ai/rest/download?id=6f93e41b-0bc5-5787-9e07-ba085b1c5e46", "status": "JOB_STATUS_SUCCESS", "statusUpdatedTimestamp": "2025-01-11T08:54:40.902Z" "messages": [] } } } ``` | --- ## Step 3 - Download the Specification You can use this API to download the generated OpenAPI specification. To do so, you can directly open the download URL that you get as part of Step 2 (see Example response) in a browser. If authentication is required, you will be redirected to the login page. As part of the response to the request in Step 2, Traceable sends a `downloadUrl` field. You can open this URL in a browser and download the specification directly. While downloading, if any authentication is required, you are redirected to the Traceable login page. Additionally, you can use the following API to download the specification. > [!NOTE] > Note > > Only learned API endpoints are listed in the OpenAPI specification. The following sections discuss: - The API endpoint details, request parameters, and request format - A Sample request that you can use to make the API request ### Endpoint Details The Endpoint URL is — `https://<traceable_url>/rest/download` . In this URL, replace `<traceable_url>` accordingly, for example, `https://api.traceable.ai/rest/download`. The endpoint URL along with the following metrics is required to download the specification: | **Method** | GET | | --- | --- | | **Response formats** | A downloadable `*.zip` file. | ##### Request Parameters The following table lists the parameters that you can use in the API request: | **Name** | **Required** | **Description** | **Example** | | --- | --- | --- | --- | | id (query parameter) | Mandatory | Specification ID | `2684a49b-d3ce-58cb-8abc-102c8be6b424` | ##### Request Format The following is the request format that you can use in the API request: ```actionscript curl '' \ --header 'Authorization: ' \ --output ``` ### Sample Request Following is a sample request that downloads the specification: ```actionscript curl 'https://api.traceable.ai/rest/download?id=2684a49b-d3ce-58cb-a8cb-102c8be6b424' \ --header 'Authorization: 2a3bcd1a02a317fe3a09c413e1234a863f33a235f637679a21da181f224b1f8ecd6216d94019d7289625d2d5f766b80bf82ea8d663e282a5a118b26abcde29af' \ --output open-api-spec.zip ``` ## Related - [Public APIs](/public-apis.md) - [Endpoint Details](/endpoint-details.md)