<< Back to GForge REST API

Entity: Docman

GET

getBinary

Get raw file contents. URL: /api/docman/[file-id]/binary?version=[version-number]

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: (none)

No return type is defined

getBundle

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

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: \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 (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: \api\DocmanFileDetail

No return type is defined

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 (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Related Entities (1)

Return: \api\DocmanFolderDetail

No return type is defined

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 (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: \api\DocmanFolderBasic[]

Zero or more DocmanFolderBasic objects

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 (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: array

Array with API location to attachment

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 (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

No return type is defined

Example 1

Locks a file
POST /api/docman/2212/file

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

postFolder

Creates or a updates a folder The following fields can be set:

  • id
  • - ID of the folder, 0 if it's a new folder
  • folderName
  • - Name of the folder
  • isPublic
  • - True if the folder has public access, false otherwise
  • parentFolderId
  • - ID of the parent folder
  • parentFolderName
  • - Name of the parent folder
  • project/li> - ID of the project

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: \api\DocmanFolderBasic[]

Zero or more DocmanFolderBasic objects

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
request \mvcnphp\RequestParameters Request object

Return: (none)

No return type is defined

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 (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

No return type is defined

Example 1

Request to unzip a given file
POST /api/docman/70/unzip

postVersion

Updates a file version changes description

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

No return type is defined

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
request \mvcnphp\RequestParameters Request object

Return: (none)

No return type is defined

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
request \mvcnphp\RequestParameters Request object

Return: (none)

No return type is defined

Example 1

Delete folder with ID 12345

DELETE /api/docman/12345/folder
                                                            

deleteVersion

Deletes a file version

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: (none)

No return type is defined

Example 1

Deletes version of a file, where the file version id is 341
POST /api/docman/341/version