<< Back to GForge REST API

Entity: Docman

GET

getBinary

Get raw file contents.

Parameters (3)

Name Type Description
id int Unique identifier for the file object. This is part of the URL route
version int (Optional) number of the version being requested. Defaults to the current version.
open mixed (Optional) If any non-"falsy" value is included, open the binary content in the browser. Otherwise, download as a file.

Return: mixed

The file contents

getBundle

Retrieves a folder with its contents (files and versions) in a zip file

Parameters (1)

Name Type Description
id int ID of the folder that is being requested

Return: mixed

file in zip format

Example 1

http://api.mygforge.tld/api/docman/115/bunde

getFile

Retrieves a file with its file versions and folders

Parameters (2)

Name Type Description
id string ID of the file to be retrieved
rel string Comma-separated list of related entities to embed (e.g. versions,folders,monitoring,downloads)

Return: \gforge\plugins\docman\models\api\DocmanFileDetail

Name Type Description
id int Unique database identifier for the Docman file
description string File description
isMonitored string 'Y' if monitored, 'N' otherwise
rel array A flexible set of related data

Example 1

Get file information 

GET /api/docman/6064/file?rel=versions,folders,monitoring,downloads

{
    "id": 6064,
    "description": "Screenshot at Jul 16 14-17-47.png",
    "isLocked": "N",
    "lockedBy": {
        "id": 8388,
        "unixName": "someuser",
        "password": null,
        "firstname": "John",
        "lastname": "Doe",
        "email": "someuser@gforgegroup.com",
        "timezone": "America/New_York",
        "status": 1,
        "externalId": null,
        "isGroup": "N",
        "ccode": "AR",
        "language": "en",
        "theme": 1,
        "img_url": "/api/user/someuser/avatar",
        "html_url": "/user/someuser",
        "details_url": "/api/user/someuser/details",
        "isSiteAdmin": true,
        "api_url": "/api/user/someuser"
    },
    "isMonitored": null,
    "rel": {
        "folders": [
            {
                "id": 69,
                "folderName": "incoming",
                "isPublic": "N",
                "parentFolderId": 0,
                "isMonitored": null,
                "docCount": -22,
                "project": {
                    "id": 138,
                    "name": "GForge AS",
                    "unixName": "gforge5",
                    "description": "We Believe in Great Software.  For over two decades GForge has helped software organizations deliver their ideas to market faster using their own process.  The project is the core GForge project and it has two active efforts.  The first is maintenance on the existing GForge product and the second is delivering the next generation of GForge.  ",
                    "homepageUrl": "/gf/project/gforge5/",
                    "createDate": "2005-10-10 06:37:46 +0000",
                    "isPublic": "Y",
                    "status": 1,
                    "isTemplate": "N",
                    "templateProjectId": 0,
                    "parentProjectId": 2720,
                    "averageRating": 5
                }
            }
        ],
        "versions": [
            {
                "id": 3400,
                "createDate": "2020-07-31T20:17:23+0000",
                "changes": null,
                "versionNumber": 1,
                "isApproved": "Y",
                "docmanFile": null,
                "user": {
                    "id": 8388,
                    "unixName": "someuser",
                    "password": null,
                    "firstname": "John",
                    "lastname": "Doe",
                    "email": "someuser@gforgegroup.com",
                    "timezone": "America/New_York",
                    "status": 1,
                    "externalId": null,
                    "isGroup": "N",
                    "ccode": "AR",
                    "language": "en",
                    "theme": 1,
                    "img_url": "/api/user/someuser/avatar",
                    "html_url": "/user/someuser",
                    "details_url": "/api/user/someuser/details",
                    "isSiteAdmin": true,
                    "api_url": "/api/user/someuser"
                },
                "url": "/api/docman/6064/binary/Screenshot+at+Jul+16+14-17-47.png?version=1",
                "filesystem": {
                    "id": 38140,
                    "fileName": "Screenshot at Jul 16 14-17-47.png",
                    "section": "docmanfileversion",
                    "refId": 3400,
                    "fileNameSafe": "Screenshot at Jul 16 14-17-47.png",
                    "fileType": "image/png; charset=binary",
                    "fileSize": "20768",
                    "postedBy": {
                        "id": 8388,
                        "unixName": "someuser",
                        "password": null,
                        "firstname": "John",
                        "lastname": "Doe",
                        "email": "someuser@gforgegroup.com",
                        "timezone": "America/New_York",
                        "status": 1,
                        "externalId": null,
                        "isGroup": "N",
                        "ccode": "AR",
                        "language": "en",
                        "theme": 1,
                        "img_url": "/api/user/someuser/avatar",
                        "html_url": "/user/someuser",
                        "details_url": "/api/user/someuser/details",
                        "isSiteAdmin": true,
                        "api_url": "/api/user/someuser"
                    },
                    "downloadCount": 0,
                    "uploadedOn": "2020-07-31T20:17:23+0000",
                    "thumbnailUrl": "/core/img/filetypes/256/PNG.png",
                    "attachmentUrl": "/api/docman/3400/filesystem",
                    "md5Hash": "a1e08d10d26f0cdeae4b5aa1df417e00"
                }
            },
            {
                "id": 3401,
                "createDate": "2020-07-31T20:17:29+0000",
                "changes": null,
                "versionNumber": 2,
                "isApproved": "Y",
                "docmanFile": null,
                "user": {
                    "id": 8388,
                    "unixName": "someuser",
                    "password": null,
                    "firstname": "John",
                    "lastname": "Doe",
                    "email": "someuser@gforgegroup.com",
                    "timezone": "America/New_York",
                    "status": 1,
                    "externalId": null,
                    "isGroup": "N",
                    "ccode": "AR",
                    "language": "en",
                    "theme": 1,
                    "img_url": "/api/user/someuser/avatar",
                    "html_url": "/user/someuser",
                    "details_url": "/api/user/someuser/details",
                    "isSiteAdmin": true,
                    "api_url": "/api/user/someuser"
                },
                "url": "/api/docman/6064/binary/Screenshot+at+Jul+16+14-17-47.png?version=2",
                "filesystem": {
                    "id": 38141,
                    "fileName": "Screenshot at Jul 16 14-17-47.png",
                    "section": "docmanfileversion",
                    "refId": 3401,
                    "fileNameSafe": "Screenshot at Jul 16 14-17-47.png",
                    "fileType": "image/png; charset=binary",
                    "fileSize": "20768",
                    "postedBy": {
                        "id": 8388,
                        "unixName": "someuser",
                        "password": null,
                        "firstname": "John",
                        "lastname": "Doe",
                        "email": "someuser@gforgegroup.com",
                        "timezone": "America/New_York",
                        "status": 1,
                        "externalId": null,
                        "isGroup": "N",
                        "ccode": "AR",
                        "language": "en",
                        "theme": 1,
                        "img_url": "/api/user/someuser/avatar",
                        "html_url": "/user/someuser",
                        "details_url": "/api/user/someuser/details",
                        "isSiteAdmin": true,
                        "api_url": "/api/user/someuser"
                    },
                    "downloadCount": 0,
                    "uploadedOn": "2020-07-31T20:17:29+0000",
                    "thumbnailUrl": "/core/img/filetypes/256/PNG.png",
                    "attachmentUrl": "/api/docman/3401/filesystem",
                    "md5Hash": "a1e08d10d26f0cdeae4b5aa1df417e00"
                }
            }
        ],
        "monitoring": [],
        "downloads": []
    }
}

getFolder

Retrieves a folder with its contents (files and versions)

Parameters (5)

Name Type Description
id string ID or name of the requested folder
projectId string ID or unix name of the project; required when searching by folder name
sort_field string Field to sort folder files by. Allowed values: folderName. Default is description.
sort_dir string Sort direction. Allowed values: asc, desc. Default is asc.
rel string Comma-separated list of related entities to embed in the response (e.g. currentfiles).
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.

Related Entities (1)

rel= Type Description
currentfiles \gforge\plugins\docman\models\api\DocmanFileVersion The list of files that reside in the requested folder (current version of each file)

Return: \gforge\plugins\docman\models\api\DocmanFolderBasic

The requested folder API object

Name Type Description
id int Unique database identifier for the docman folder
folderName string Folder name
isPublic \char 'Y' when is approved
project int
parentFolderId int
isMonitored string 'Y' if monitored, 'N' otherwise
docCount int

Example 1

http://api.mygforge.tld/api/docman/115/folder?rel=currentfiles 

{
    "id": 115,
    "folderName": "Build Docs",
    "isPublic": "N",
    "parentFolderId": 0,
    "isMonitored": null,
    "docCount": 0,
    "project": {
        "id": 138,
        "name": "GForge AS",
        "unixName": "gforge5",
        "description": "We Believe in Great Software.  For over two decades GForge has helped software organizations deliver their ideas to market faster using their own process.  The project is the core GForge project and it has two active efforts.  The first is maintenance on the existing GForge product and the second is delivering the next generation of GForge.  ",
        "homepageUrl": "/gf/project/gforge5/",
        "createDate": "2005-10-10 06:37:46 +0000",
        "isPublic": "Y",
        "status": 1,
        "isTemplate": "N",
        "templateProjectId": 0,
        "parentProjectId": 2720,
        "averageRating": 5
    },
    "rel": {
        "currentfiles": [
            {
                "id": 2294,
                "createDate": "2013-04-12T19:47:02+0000",
                "changes": "",
                "versionNumber": 2,
                "isApproved": "Y",
                "docmanFile": {
                    "id": 3067,
                    "description": "AgileStats.odt File!",
                    "isLocked": "N",
                    "lockedBy": {
                        "id": 100,
                        "unixName": "None",
                        "password": null,
                        "firstname": "Nobody",
                        "lastname": " ",
                        "email": "noreply@gforge.org",
                        "timezone": "GMT",
                        "status": 1,
                        "externalId": null,
                        "isGroup": "N",
                        "ccode": "US",
                        "language": "en",
                        "theme": 1,
                        "img_url": "/api/user/None/avatar",
                        "html_url": "/user/None",
                        "details_url": "/api/user/None/details",
                        "isSiteAdmin": false,
                        "api_url": "/api/user/None"
                    },
                    "isMonitored": "N",
                    "rel": []
                },
                "user": {
                    "id": 5945,
                    "unixName": "mtutty",
                    "password": null,
                    "firstname": "Michael",
                    "lastname": "Tutty",
                    "email": "MTUTTY@gforgegroup.com",
                    "timezone": "America/Chicago",
                    "status": 1,
                    "externalId": null,
                    "isGroup": "N",
                    "ccode": "US",
                    "language": "en",
                    "theme": 1,
                    "img_url": "/api/user/mtutty/avatar",
                    "html_url": "/user/mtutty",
                    "details_url": "/api/user/mtutty/details",
                    "isSiteAdmin": true,
                    "api_url": "/api/user/mtutty"
                },
                "url": "/api/docman/3067/binary/AgileStats.odt?version=2",
                "filesystem": {
                    "id": 18182,
                    "fileName": "AgileStats.odt",
                    "section": "docmanfileversion",
                    "refId": 2294,
                    "fileNameSafe": "AgileStats.odt",
                    "fileType": "application/vnd.oasis.opendocument.text; charset=binary",
                    "fileSize": "16856",
                    "postedBy": {
                        "id": 5945,
                        "unixName": "mtutty",
                        "password": null,
                        "firstname": "Michael",
                        "lastname": "Tutty",
                        "email": "MTUTTY@gforgegroup.com",
                        "timezone": "America/Chicago",
                        "status": 1,
                        "externalId": null,
                        "isGroup": "N",
                        "ccode": "US",
                        "language": "en",
                        "theme": 1,
                        "img_url": "/api/user/mtutty/avatar",
                        "html_url": "/user/mtutty",
                        "details_url": "/api/user/mtutty/details",
                        "isSiteAdmin": true,
                        "api_url": "/api/user/mtutty"
                    },
                    "downloadCount": 1,
                    "uploadedOn": "",
                    "thumbnailUrl": "/core/img/filetypes/256/BLANK.png",
                    "attachmentUrl": "/api/docman/2294/filesystem",
                    "md5Hash": "1a844eca118c066292de1f7f4c17e815"
                }
            },
                      }
        ]
    }
}

getFolders

Retrieves all folders on a given project

Parameters (2)

Name Type Description
id string Unique database identifier or unix name of the project
root string When any non-empty value is provided, returns only root-level folders

Return: \gforge\plugins\docman\models\api\DocmanFolderBasic[]

Zero or more DocmanFolderBasic objects

Name Type Description
id int Unique database identifier for the docman folder
folderName string Folder name
isPublic \char 'Y' when is approved
project int
parentFolderId int
isMonitored string 'Y' if monitored, 'N' otherwise
docCount int

Example 1

http://api.mygforge.tld/api/docman/138/folders 

{
    "paging": {
        "page_size": 20,
        "page_num": 1,
        "sort_field": "id",
        "sort_dir": "asc"
    },
    "items": [
        {
            "id": 115,
            "folderName": "Build Docs",
            "isPublic": "N",
            "parentFolderId": 0,
            "isMonitored": "N",
            "docCount": 0,
            "project": {
                "id": 138,
                "name": "GForge AS",
                "unixName": "gforge5",
                "description": "We Believe in Great Software.  For over two decades GForge has helped software organizations deliver their ideas to market faster using their own process.  The project is the core GForge project and it has two active efforts.  The first is maintenance on the existing GForge product and the second is delivering the next generation of GForge.  ",
                "homepageUrl": "/gf/project/gforge5/",
                "createDate": "2005-10-10 06:37:46 +0000",
                "isPublic": "Y",
                "status": 1,
                "isTemplate": "N",
                "templateProjectId": 0,
                "parentProjectId": 2720,
                "averageRating": 5
            }
        },
        {
            "id": 50,
            "folderName": "Developer documentation",
            "isPublic": "N",
            "parentFolderId": 0,
            "isMonitored": "N",
            "docCount": -1,
            "project": {
                "id": 138,
                "name": "GForge AS",
                "unixName": "gforge5",
                "description": "We Believe in Great Software.  For over two decades GForge has helped software organizations deliver their ideas to market faster using their own process.  The project is the core GForge project and it has two active efforts.  The first is maintenance on the existing GForge product and the second is delivering the next generation of GForge.  ",
                "homepageUrl": "/gf/project/gforge5/",
                "createDate": "2005-10-10 06:37:46 +0000",
                "isPublic": "Y",
                "status": 1,
                "isTemplate": "N",
                "templateProjectId": 0,
                "parentProjectId": 2720,
                "averageRating": 5
            }
        },
    ],
    "links": [],
    "meta": []
}

POST

postBinary

Processes a binary file upload to a given folder. If a file with the same name already exists, it creates a new version of the file

Parameters (4)

Name Type Description
folderId int ID of the folder to which the uploaded file is attached
fileName string Name of the file being uploaded
fileType string MIME type of the file being uploaded
hash string Chunk-upload hash token used to locate the staged file data

Return: void

Example 1

Update an existing file, or create a new one, under the folder with ID = 70 

POST /api/docman/70/binary

postFile

Updates or creates a new file. This is used to lock/unlock a file, or update its description. To add/update a file use postBinary

Parameters (4)

Name Type Description
id int Zero for a new file, or the database ID of the file to update
description string Description of the file
isLocked string Y to lock the file for updates, N to unlock it
rel array Optional related entities; when rel.folders is present, updates folder associations

Return: \gforge\plugins\docman\models\api\DocmanFileDetail

Name Type Description
id int Unique database identifier for the Docman file
description string File description
isMonitored string 'Y' if monitored, 'N' otherwise
rel array A flexible set of related data

Example 1

Locks a file 

POST /api/docman/2212/file

{
 "id":6064,
 "isLocked":"Y"
}

postFolder

Creates or a updates a folder.

Parameters (6)

Name Type Description
id int Unique ID for the folder, 0 for a new folder
folderName string Name of the folder
isPublic bool True if the folder has public access, false otherwise
parentFolderId int ID of the parent folder
parentFolderName string Name of the parent folder
project int ID of the project

Return: \gforge\plugins\docman\models\api\DocmanFolderBasic

The created or updated folder

Name Type Description
id int Unique database identifier for the docman folder
folderName string Folder name
isPublic \char 'Y' when is approved
project int
parentFolderId int
isMonitored string 'Y' if monitored, 'N' otherwise
docCount int

Example 1

Update or create a new folder under the "GForge AS" folder 

POST /api/docman/0/folder
{
 "id": 0,
 "folderName": "test",
 "isPublic": "Y",
 "parentFolderId": 0,
 "parentFolderName": "GForge AS",
 "project": 138
}

postRestore

Restores a file version (makes it current version)

Parameters (1)

Name Type Description
id int ID of the file version to restore

Return: \gforge\plugins\docman\models\api\DocmanFileVersionBasic

Name Type Description
id int Version Unique Id
createDate string Date of upload
changes string
versionNumber int
isApproved \char 'Y' when is approved
docmanFile \models\base\DocmanFileDetail
user \coreapi\UserBasic
url string Url to download the file
filesystem string
tags array
folderPath string

Example 1

Restores a file version, where the file version id is 2212 

POST /api/docman/2212/restore

postUnzip

Unzips an existing file and recreates the directory/files structure in docman

Parameters (2)

Name Type Description
id int ID of the file version to unzip; must reference a ZIP file
folderId int ID of the parent folder under which the unzipped directory structure will be created

Return: void

Example 1

Request to unzip a given file 

POST /api/docman/70/unzip

postVersion

Updates a file version changes description

Parameters (3)

Name Type Description
id int Zero for a new version, or the database ID of the file version to update
changes string Description of the changes in this file version
docmanFile int Database ID of the parent docman file

Return: \gforge\plugins\docman\models\api\DocmanFileVersionBasic

Name Type Description
id int Version Unique Id
createDate string Date of upload
changes string
versionNumber int
isApproved \char 'Y' when is approved
docmanFile \models\base\DocmanFileDetail
user \coreapi\UserBasic
url string Url to download the file
filesystem string
tags array
folderPath string

Example 1

Updates file version changes description, where the file version id is 2212 

POST /api/docman/2212/version

{
  "id":2212,
  "changes":"some changes",
  "docmanFile":241
}

PUT

DELETE

deleteFile

Deletes a file (including all its versions)

Parameters (1)

Name Type Description
id int ID of the file to delete

Return: void

Example 1

Deletes a file, where the file id is 112 

POST /api/docman/112/file

deleteFolder

Deletes a folder, and subfolders and files in them

Parameters (1)

Name Type Description
id int ID of the folder to be deleted

Return: void

Example 1

Delete folder with ID 12345 

DELETE /api/docman/12345/folder

deleteVersion

Deletes a file version

Parameters (1)

Name Type Description
id int ID of the file version to delete

Return: void

Example 1

Deletes version of a file, where the file version id is 341 

POST /api/docman/341/version