Downloading API Documentation

  • Updated on Apr 3, 2025
  • Published on Jun 2, 2022
  • 7 minute(s) read
Prev Next
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:

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 page.

This step discusses how to trigger the specification generation for all API endpoints under a domain, environment, service, or label. Step 2 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.

Authorization

Requires Traceable Platform token. For more information, see Public APIs.

Schema

You can access the schema by following the Public APIs document.

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.

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.

  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.

  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.

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

mutation CreateApiDefinition {
  createApiDefinition(
    apiDefinitionSpec: { format: OPEN_API_YAML, domainId: "b721093e-3870-55ca-a03c-d4fe721b6708", learningEndpointStrategy: MENTION }
  ) {
    id
  }
}

Example response

{
  "data": {
    "getApiDefinition": {
      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"
    }
  }
}
Services

Example request

mutation CreateApiDefinition {
  createApiDefinition(
    apiDefinitionSpec: { format: OPEN_API_YAML, serviceId: "b721093e-3870-55ca-a03c-d4fe721b6708", learningEndpointStrategy: MENTION }
  ) {
    id
  }
}

Example response

{
  "data": {
    "getApiDefinition": {
      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"
    }
  }
}
Labels

Example request

mutation CreateApiDefinition {
  createApiDefinition(
    apiDefinitionSpec: { format: OPEN_API_YAML, labels: ["label1", "label2", "label3"] }
  ) {
    id
  }
}

Example response

{
  "data": {
    "getApiDefinition": {
      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"
    }
  }
}
Environment

Example request

mutation CreateApiDefinition {
  createApiDefinition(
    apiDefinitionSpec: { format: OPEN_API_YAML, environment: "environment_name" }
  ) {
    id
  }
}

Example response

{
  "data": {
    "getApiDefinition": {
      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"
    }
  }
}

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. 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. 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.

Authorization

Requires Traceable Platform token. For more information, see Public APIs.

Schema

You can access the schema by following the Public APIs document.

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

query GetApiDefinition {
  getApiDefinition(id: "6f93e41b-0bc5-5787-9e07-ba085b1c5e46") {
    downloadUrl
    status
    statusUpdatedTimestamp
    messages
  }
}
{
  "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

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:

curl '<URL_from_the_previous_step>' \
--header 'Authorization: <Platform_API_Token>' \
--output <Desired_ZIP_file_name>

Sample Request

Following is a sample request that downloads the specification:

curl 'https://api.traceable.ai/rest/download?id=2684a49b-d3ce-58cb-a8cb-102c8be6b424' \
--header 'Authorization: 2a3bcd1a02a317fe3a09c413e1234a863f33a235f637679a21da181f224b1f8ecd6216d94019d7289625d2d5f766b80bf82ea8d663e282a5a118b26abcde29af' \
--output open-api-spec.zip

Related articles