--- title: "Managing Documentation using APIs" slug: "managing-api-documentation" description: "Learn how to manage API documentation in Traceable using REST and GraphQL APIs. This guide explains how to upload, re-upload, update, and delete OpenAPI, Postman, GraphQL, and WSDL specifications in an automated way." updated: 2025-12-16T05:22:17Z published: 2025-12-16T05:22:17Z --- > ## 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. # Managing Documentation using APIs API Documentation in Traceable refers to specifications that describe your APIs. Traceable supports the following documentation types: - OpenAPI specs - Postman Collections - Postman Environments - GraphQL schemas - WSDLs You can manage these specifications using the following API operations to automate management, without using the Traceable platform user interface: - **Upload** — Add new documentation (spec file) and trigger discovery or naming rules, optionally. - **Re-upload** — Replace an existing spec file with a new version using the same spec ID and path. - **Update** — Modify the metadata, such as name and discovery flags, for an existing API documentation without changing the file. - **Delete** — Permanently remove the API documentation and its associated metadata. For more information on performing these operations, see [API Documentation Operations](/docs/managing-api-documentation#api-documentation-operations). > [!NOTE] > Note > > Traceable provides all operations except deletion through the Upload REST API. Deletion requires a GraphQL mutation followed by a REST API call. --- ## What will you learn in this topic? By the end of this topic, you will understand: - The supported operations on the API documentation files. - The sample API calls to upload, re-upload, update, and delete the API documentation files. - The limitations and best practices associated with the above operations. --- ## Before you begin Make a note of the following before you proceed with the operations: - Make sure you have the Traceable platform API token for authenticated access. For more information, see [Public APIs](/docs/public-apis#step-1-–-copy-the-platform-api-token). - Make sure you have the spec file you wish to upload. - Make sure you have a unique path for each spec. - (For re-upload, update, and delete operations only) Make sure you have the ID of the spec you wish to operate on. --- ## API Documentation Operations The following sections highlight the details for performing the available operations on your spec files. **API URL** ```actionscript POST https://api.traceable.ai/rest/upload ``` **Headers** ```actionscript Content-Type: multipart/form-data   Authorization: Bearer //Replace the placeholder with the token from your Traceable account ``` **Form-data** - `uploadConfiguration` — The JSON metadata describing the operation. - `<configKey>` — You must attach the actual spec file. The key must match the `configKey` in the configuration. **Spec Types** The following spec types are supported in the operations: - OpenAPI specs — `SPEC_TYPE_OPEN_API_SPEC` - Postman Collections — `SPEC_TYPE_POSTMAN_COLLECTION` - Postman Environments — `SPEC_TYPE_POSTMAN_ENVIRONMENT` - GraphQL schemas — `SPEC_TYPE_GRAPHQL_SCHEMA` - WSDLs — `SPEC_TYPE_WSDL` ### Upload API Documentation This operation allows you to add new API documentation to your Traceable account. Traceable supports uploading OpenAPI, Postman, GraphQL, or WSDL specs. Optionally, you can enable API discovery and naming for the specs. #### Sample Upload Configuration In the example configuration below, you upload two API documentation files (GraphQL schema and OpenAPI spec) using the `file_0` and `file_1` config keys. You must upload the spec files to the corresponding config keys in the `form-data` section of your REST API client. ```actionscript {    "uploadOperation": [     //List of upload operations. Multiple specs can be uploaded in one call.        {            "apiDocumentUploadOperation": {     //First spec upload                "name": "graphql_schema.graphql",     //Name of the file to be uploaded                "specPath": "/development/OAS/graphql_schema.graphql",     //Path of the file on disk                "specType": "SPEC_TYPE_GRAPHQL_SCHEMA",     // Type of specification (GraphQL schema in this case)                "postUploadOperations": [],     //Optional operations to trigger after upload                "configKey": "file_0",     //Unique identifier to map this file in form-data                "apiNamingEnabled": false,     //Whether or not API naming rules should be generated                "apiDiscoveryEnabledV2": false.    //Whether or not API discovery should run after upload            }        },        {            "apiDocumentUploadOperation": {                "name": "bare-min.json",                "specPath": "/development/OAS/bare-min.json",                "specType": "SPEC_TYPE_OPEN_API_SPEC",                "postUploadOperations": [],                "configKey": "file_1",                "apiNamingEnabled": false,                "apiDiscoveryEnabledV2": false            }        }    ] } ``` #### Sample Response ```actionscript [    {        "docId": "ec262345-643d-4539-870f-02c123456c96",        "jobIds": [],        "messages": [],        "uploadStatus": "PARSING_SUCCESSFUL"    },    {        "docId": "3e789b70-be64-4b7c-8ab9-56bf123ffa34",        "jobIds": [],        "messages": [],        "uploadStatus": "PARSING_SUCCESSFUL"    } ] ``` > [!NOTE] > Note > > In the above response, the `docId` refers to the `specId` generated for the uploaded documentation. You can use this spec ID to re-upload, update, and delete the API documentation. ### Re-upload API Documentation You can use this operation to replace an existing file with a new version. You can re-upload a file using the `specId` or `specPath`. Upon re-upload, Traceable deletes the existing file and uploads the updated one to the platform. #### Sample Re-upload Configuration ```actionscript {    "uploadOperation": [        {            "apiDocumentUploadOperation": {                "specId": "ec262335-643d-4539-870f-02c418993c96",     //The docId corresponding to the spec                "name": "graphql_schema.graphql",     //Name of the file to be re-uploaded                "specPath": "/development/OAS/graphql_schema.graphql",     //Path of the file on disk                "specType": "SPEC_TYPE_GRAPHQL_SCHEMA",     // Type of specification (GraphQL schema in this case)                "postUploadOperations": [],     //Optional operations to trigger after upload                "configKey": "file_0",     //Unique identifier to map this file in form-data                "apiNamingEnabled": false,     //Whether or not API naming rules should be generated                "apiDiscoveryEnabledV2": false    //Whether or not API discovery should run after upload            }        }    ] } ``` #### Sample Response ```actionscript [    {        "docId": "ec262335-643d-4539-870f-02c418993c96",        "jobIds": [],        "messages": [],        "uploadStatus": "PARSING_SUCCESSFUL"    } ] ``` ### Update API Documentation You can use this operation to modify the metadata of an existing API documentation; however, you must include the file in the request, even if it has no changes. #### Sample Update Configuration ```actionscript {    "uploadOperation": [        {            "apiDocumentUploadOperation": {                "specId": "3e882b70-be64-4b7c-8ab9-59bf958ffa34",     //The docId corresponding to the spec                "name": "bare-minimum-spec-1.json",     //Name of the file to be updated                "specPath": "/development/OAS/bare-min.json",     //Path of the file on disk                "specType": "SPEC_TYPE_OPEN_API_SPEC",     // Type of specification (Open API spec in this case)                "postUploadOperations": [],     //Optional operations to trigger after update                "configKey": "file_0",     //Unique identifier to map this file in form-data                "apiNamingEnabled": true,     //Whether or not API naming rules should be generated                "apiDiscoveryEnabledV2": false    //Whether or not API discovery should run after update            }        }    ] } ``` #### Sample Response ```actionscript [    {        "docId": "3e882b70-be64-4b7c-8ab9-59bf958ffa34",        "jobIds": [],        "messages": [],        "uploadStatus": "PARSING_SUCCESSFUL"    } ] ``` ### Delete API Documentation This operation can permanently delete API documentation from your Traceable account. Deletion is a two-step process: 1. [Removing the spec configuration using GraphQL](/docs/managing-api-documentation#step-1-—-removing-the-spec-configuration-using-graphql) 2. [Deleting the file using the REST API](/docs/managing-api-documentation#step-2-—-deleting-the-file-using-rest-api) > [!NOTE] > Note > > Traceable allows the deletion of API documentation on a one-by-one basis, meaning you cannot delete multiple documents in a single operation. This ensures that each deletion is intentional and minimizes the risk of accidentally removing the wrong documentation. #### Step 1 — Removing the Spec Configuration using GraphQL ##### Sample API Request ```actionscript mutation {  deleteApiSpec(input: { id: "3e123b70-be65-4b5c-8ab9-59bf987ffa34" }) {    success  } } ``` ##### Sample API Response ```actionscript [    {        "data": {            "deleteApiSpec": {                "success": true            }        }    } ] ``` If the above response contains `”success”: true`, complete the step below. #### Step 2 — Deleting the File using REST API **Method Type** — `DELETE` **URL** — `https://app-dev.traceable.ai/rest/v1/delete/documentation/openapi` **Content-Type** — `application/json` ##### Sample API Request ```actionscript {  "docId": "3e876b70-be65-4b7c-8ab9-59bf987ffa34" } ``` ##### Sample API Response ```actionscript {  "success": true } ```