# Add DSV Named Items to a Document

Adds one or more named items to the specified document by ID. 
These items define the document's structure and hierarchy (e.g., sections or headings) 
for display or navigation purposes within the Document Structure View (DSV).


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "PandaDoc Public API",
    "description": "PandaDoc API spans a broad range of functionality to help you build incredible documents automation experiences inside your product.\n\nPandaDoc API is organized around REST. Our API has predictable resource-oriented URLs and uses standard HTTP response codes, authentication, and verbs.\n\n## Getting started\n\nYou can start testing PandaDoc API with a sandbox key on our [Enterprise](https://www.pandadoc.com/pricing/) plan, either active or in trial.\n\nGenerate your [sandbox key](https://developers.pandadoc.com/reference/sandbox-key) on the Developer Dashboard with predefined [rate limits](https://developers.pandadoc.com/reference/limits). Or contact our solutions expert if you work with high-transaction volumes.\n\n## Guides\n\nIf you’re just getting started with PandaDoc, you may want to jump straight into one of our [getting started guides](https://developers.pandadoc.com/docs/getting-started) for the feature you’re most interested in, whether that’s:\n\n- [Create from template](https://developers.pandadoc.com/docs/create-send-document),\n- [Upload and send a local PDF](https://developers.pandadoc.com/docs/upload-and-send-a-local-pdf),\n- or [Listening for changes in document status](https://developers.pandadoc.com/docs/listen-document-status-changes).\n\nWe also recommend you to discover our dynamic content generation on a fly: [Create from a template with content placeholder](https://developers.pandadoc.com/docs/create-with-content-placeholders-from-template).\n",
    "termsOfService": "https://www.pandadoc.com/master-services-agreement/",
    "contact": {
      "name": "PandaDoc API Support",
      "url": "https://developers.pandadoc.com/",
      "email": "api-track@pandadoc.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/PandaDoc/pandadoc-openapi-specification/blob/main/LICENSE"
    },
    "version": "7.18.2"
  },
  "servers": [
    {
      "url": "https://api.pandadoc.com",
      "description": "Public API"
    }
  ],
  "security": [
    {
      "apiKey": []
    },
    {
      "oauth2": []
    }
  ],
  "tags": [
    {
      "name": "Document Structure View",
      "description": "Operations related to managing the structure and hierarchy of documents within the Document Structure View (DSV)."
    }
  ],
  "paths": {
    "/public/v2/dsv/{document_id}/add-named-items": {
      "post": {
        "tags": [
          "Document Structure View"
        ],
        "summary": "Add DSV Named Items to a Document",
        "description": "Adds one or more named items to the specified document by ID. \nThese items define the document's structure and hierarchy (e.g., sections or headings) \nfor display or navigation purposes within the Document Structure View (DSV).\n",
        "operationId": "addDsvNamedItems",
        "x-internal": true,
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique identifier of the document to which the DSV named items will be added.",
            "example": "BhVzRcxH9Z2LgfPPGXFUBa"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "examples": {
                "Add a DSV Named Items": {
                  "value": {
                    "items": [
                      {
                        "name": "First Section",
                        "level": 0,
                        "page_name": "page_name_1"
                      },
                      {
                        "name": "Second Section",
                        "level": 0,
                        "page_name": "page_name_2"
                      }
                    ]
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/AddDsvNamedItemsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully created DSV named items.",
            "content": {
              "application/json": {
                "examples": {
                  "Add a DSV Item": {
                    "value": {
                      "results": [
                        {
                          "id": "0da526b8-0535-4a5c-9913-431ed252a6f5",
                          "name": "First Section",
                          "level": 0,
                          "page_name": "page_name_1",
                          "page_uuid": "8dcc8dcc-b5bd-4431-9885-1a60e829cdaf"
                        },
                        {
                          "id": "30dc3914-fd05-4b09-9eca-99a067b8767b",
                          "name": "Second Section",
                          "level": 0,
                          "page_name": "page_name_2",
                          "page_uuid": "4ae4e8ef-f2e8-4fe3-a47f-0833af49f31f"
                        }
                      ],
                      "count": 2
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/AddDsvNamedItemsResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "description": "The `Authorization` header must contain the API key. The value should be prefixed with `API-Key` followed by a space and the actual API key.\n",
        "x-default": "API-Key 3039ba033eb1410caa0a2227158d63c9d6502cd8"
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.pandadoc.com/oauth2/authorize",
            "tokenUrl": "https://api.pandadoc.com/oauth2/access_token",
            "refreshUrl": "https://api.pandadoc.com/oauth2/access_token",
            "scopes": {
              "read+write": "Use `read+write` to create, send, delete, and download documents, and `read` to view templates and document details."
            }
          }
        },
        "description": "Send the authenticating user to the PandaDoc OAuth2 request URL. We recommend a button or a link titled\n\"Connect to PandaDoc\" if you are connecting users from a custom application. Users will see the \"Authorize Application\" screen.\nWhen the user clicks \"Authorize\", PandaDoc redirects the user back to your site with an authorization code inside the URL.\n\nhttps://app.pandadoc.com/oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope=read+write&response_type=code\n\n`client_id` and `redirect_uri` values should match your application settings.\n"
      }
    },
    "schemas": {
      "AddDsvNamedItemsRequest": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "description": "List of named items representing structural elements of the document.",
            "items": {
              "type": "object",
              "required": [
                "name",
                "level",
                "page_name"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "description": "The display name of the item (e.g., \"Introduction\", \"Chapter 1\")."
                },
                "level": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Hierarchical level of the item. \nLevel 0 is the highest (top-level), with increasing numbers for nested structures.\n"
                },
                "page_name": {
                  "type": "string",
                  "description": "Internal reference or identifier for the page this item is associated with."
                }
              }
            }
          }
        }
      },
      "AddDsvNamedItemsResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "description": "List of DSV named items that were created.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Unique identifier for the created DSV item."
                },
                "name": {
                  "type": "string",
                  "description": "The display name of the item."
                },
                "level": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "The hierarchy level of the item."
                },
                "page_name": {
                  "type": "string",
                  "description": "Internal reference name for the page."
                },
                "page_uuid": {
                  "type": "string",
                  "format": "uuid",
                  "description": "UUID of the associated page."
                }
              },
              "required": [
                "id",
                "name",
                "level",
                "page_name",
                "page_uuid"
              ]
            }
          },
          "count": {
            "type": "number",
            "format": "integer",
            "minimum": 0,
            "description": "Total number of items created."
          }
        },
        "required": [
          "results",
          "count"
        ]
      }
    }
  }
}
```