---
post:

  summary: Move one or more documents to Trash

  tags:
    - Modify

  description: |
    Move one or more documents to Trash.

    *OAuth Privileges required: `DOC_SEND`*

  parameters:
    - name: document_ids
      in: formData
      type: string
      format: application/json
      required: true

      description: |
        List of document IDs to trash.

      schema:
        type: array
        default: []
        example: ["3","4"]
        items:
          type: string

  responses:
    200:
      description: |
        A JSON object containing the total number of `trashed` documents, and an array of documents.
    409:
      description: Pending documents can not be trashed or deleted.
      # FIXME It is possible to add a schema here, although APIError is too general
    # TODO Add document_state_error; The document is in Trash already.