openapi: 3.1.0
info:
  title: Documents
  description: 'Manage document folders and uploaded files. Use this API to create document

    folder hierarchies, retrieve the full folder tree structure, list all documents

    within a folder, and upload new documents using Base64-encoded file data.'
  version: 2.0.1
x-readme:
  headers: []
  explorer-enabled: true
  proxy-enabled: true
x-readme-fauxas: true
x-samples-languages:
- curl
- csharp
- java
- javascript
- node
- python
- php
- ruby
externalDocs:
  description: Learn more about Dotdigital APIs
  url: https://developer.dotdigital.com
servers:
- url: https://{region}-api.dotdigital.com
  variables:
    region:
      default: r1
      enum:
      - r1
      - r2
      - r3
      description: The Dotdigital region id your account belongs to
security:
- basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
paths:
  /v2/document-folders/{id}:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    post:
      summary: Create document folder
      deprecated: false
      description: Creates a new document folder
      operationId: create-document-folder
      tags:
      - Documents
      parameters:
      - name: id
        in: path
        description: The id of an existing folder to create the new folder within
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the folder being created, which can only be up to 20 characters in length and must consist of alphanumeric characters only, with hyphens and underscores if required
            examples:
              Request Example:
                value:
                  name: Events
                summary: Request Example
      responses:
        '201':
          description: '201'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    default: 0
                    examples:
                    - 2
                  name:
                    type: string
                    examples:
                    - Events
                  childFolders: {}
              examples:
                Result:
                  summary: Result
                  value:
                    id: 2
                    name: Events
                    childFolders: null
  /v2/document-folders:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get document folders
      deprecated: false
      description: Fetches the document folder tree structure
      operationId: get-document-folders
      tags:
      - Documents
      parameters: []
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      default: 0
                      examples:
                      - 1
                    name:
                      type: string
                      examples:
                      - Products
                    childFolders:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: integer
                            default: 0
                            examples:
                            - 2
                          name:
                            type: string
                            examples:
                            - New products
                          childFolders:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  default: 0
                                  examples:
                                  - 3
                                name:
                                  type: string
                                  examples:
                                  - Offers
                                childFolders: {}
              examples:
                Result:
                  summary: Result
                  value:
                  - id: 1
                    name: Products
                    childFolders:
                    - id: 2
                      name: New products
                      childFolders:
                      - id: 3
                        name: Offers
                        childFolders: null
  /v2/document-folders/{id}/documents:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get documents in folder
      deprecated: false
      description: Gets all uploaded documents in a folder
      operationId: get-documents-in-folder
      tags:
      - Documents
      parameters:
      - name: id
        in: path
        description: The id of an existing folder
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      default: 0
                      examples:
                      - 1
                    name:
                      type: string
                      examples:
                      - economics-full
                    fileName:
                      type: string
                      examples:
                      - /cmpdoc/2013/13/1_economics-full
                    fileSize:
                      type: integer
                      default: 0
                      examples:
                      - 15
                    dateCreated:
                      type: string
                      examples:
                      - '2019-12-01 09:40:18.527000+00:00'
                    dateModified:
                      type: string
                      examples:
                      - '2020-01-01 09:40:18.527000+00:00'
              examples:
                Result:
                  summary: Result
                  value:
                  - id: 1
                    name: economics-full
                    fileName: /cmpdoc/2013/13/1_economics-full
                    fileSize: 15
                    dateCreated: '2019-12-01 09:40:18.527000+00:00'
                    dateModified: '2020-01-01 09:40:18.527000+00:00'
                  - id: 4
                    name: finance
                    fileName: /cmpdoc/2013/13/4_finance
                    fileSize: 12
                    dateCreated: '2019-12-01 09:40:18.527000+00:00'
                    dateModified: '2020-01-01 09:40:18.527000+00:00'
    post:
      summary: Upload document
      deprecated: false
      description: Upload a document to a specified folder using form data
      operationId: upload-document
      tags:
      - Documents
      parameters:
      - name: id
        in: path
        description: The id of an existing folder to create the new folder within
        required: true
        example: 0
        schema:
          type: integer
          format: int32
          default: 0
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                RAW_BODY:
                  type: string
                  default: The document file to upload
                  format: binary
                fileName:
                  type: string
                  description: The filename of the file
                data:
                  type: string
                  description: The file data in [Base64](https://en.wikipedia.org/wiki/Base64)
            examples:
              Request Example:
                value:
                  FileName: Test.csv
                  Data: SWQsTmFtZSxTdXJuYW1lLE1vYmlsZQ0KbGFuY2Uub2Nvbm5lbGxAY29tYXBpLmNvbSxMYW5jZSxPJ0Nvbm5lbGwsNDQ3MTIzMTIzMTIzDQpkYXZlLmJhZGRlbGV5QGNvbWFwaS5jb20sRGF2ZSxCYWRkZWxleSw0NDIzNDIzNDIzNA==
                summary: Request Example
      responses:
        '201':
          description: '201'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    default: 0
                    examples:
                    - 2
                  name:
                    type: string
                    examples:
                    - Events
                  childFolders: {}
              examples:
                Result:
                  summary: Result
                  value:
                    id: 2
                    name: Events
                    childFolders: null