Documents

A document is a file containing a list of attachments.

Please note, that the endpoint is only a stub for now.

Actions

None yet

Linked Properties

Link	Description	Type	Constraints	Supported operations
self	This document	Document	not null	READ
project	The project the document is in	Project	not null	READ / WRITE
attachments	The attachments belonging to the document	[]Attachment	not null	READ / WRITE

Local Properties

Property	Description	Type	Constraints	Supported operations
id	Document’s id	Integer	x > 0	READ
title	The title chosen for the collection of documents	String	max 60 characters	READ
description	A text describing the documents	String		READ
createdAt	The time the document was created at	DateTime		READ

Document

View document

GET

/api/v3/documents/{id}

Parameters
id
integer (required) Example: 1
document id

Response 200Toggle details

Headers

Content-Type: application/hal+json

Body

{
    "_type": "Document",
    "id": 1,
    "title": "Some other document",
    "description": {
        "format": "markdown",
        "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.",
        "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
    },
    "createdAt": "2018-12-10T20:53:39Z",
    "_links": {
        "attachments": {
            "href": "/api/v3/documents/1/attachments"
        },
        "addAttachment": {
            "href": "/api/v3/documents/1/attachments",
            "method": "post"
        },
        "self": {
            "href": "/api/v3/documents/1",
            "title": "Some document",
        },
        "project": {
            "href": "/api/v3/projects/19",
            "title": "Some project"
        }
    },
    "_embedded": {
        "project": {
            "_type": "Project",
            <-- omitted for brevity -->
            }
        },
        attachments": {
            "_type": "Collection",
            "total": 2,
            "count": 2,
            "_embedded": {
                <-- omitted for brevity -->
            },
            "_links": {
                "self": {
                    "href": "/api/v3/documents/1/attachments"
                }
            }
        },
    }
}

Response 404Toggle details

Returned if the document does not exist or if the user does not have permission to view it.

Required permission view documents in the project the document belongs to

Headers

Content-Type: application/hal+json

Body

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

Documents

List Documents

GET

/api/v3/documents{?offset,pageSize,sortBy}

The documents returned depend on the provided parameters and also on the requesting user’s permissions.

Parameters
offset
integer (optional) Default: 1 Example: 25
Page number inside the requested collection.

pageSize
integer (optional) Example: 25
Number of elements to display per page.

sortBy
string (optional) Example: [["created_at", "asc"]]
JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:
- id: Sort by primary key
- created_at: Sort by document creation datetime

Response 200Toggle details

Headers

Content-Type: application/hal+json

Body

{
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "pageSize": 30,
    "offset": 1,
    "_embedded": {
        "elements": [
            {
                "description": {
                    "format": "markdown",
                    "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.",
                    "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
                },
                "_type": "Document",
                "id": 1,
                "title": "Some other document",
                "createdAt": "2018-12-10T20:53:39Z",
                "_links": {
                    "attachments": {
                        "href": "/api/v3/documents/1/attachments"
                    },
                    "addAttachment": {
                        "href": "/api/v3/documents/1/attachments",
                        "method": "post"
                    },
                    "self": {
                        "href": "/api/v3/documents/1",
                        "title": "Some document",
                    },
                    "project": {
                        "href": "/api/v3/projects/19",
                        "title": "Some project"
                    }
                }
            },
            {
                "description": {
                    "format": "markdown",
                    "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.",
                    "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
                },
                "_type": "Document",
                "id": 2,
                "title": "Some other document",
                "createdAt": "2018-12-10T20:55:54Z",
                "_links": {
                    "attachments": {
                        "href": "/api/v3/documents/2/attachments"
                    },
                    "addAttachment": {
                        "href": "/api/v3/documents/2/attachments",
                        "method": "post"
                    },
                    "self": {
                        "href": "/api/v3/documents/2",
                        "title": "Some other document"
                    },
                    "project": {
                        "href": "/api/v3/projects/29",
                        "title": "Some other project"
                    }
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "/api/v3/documents?offset=1&pageSize=30"
        },
        "jumpTo": {
            "href": "/api/v3/documents?offset=%7Boffset%7D&pageSize=30",
            "templated": true
        },
        "changeSize": {
            "href": "/api/v3/documents?offset=1&pageSize=%7Bsize%7D",
            "templated": true
        }
    }
}

Response 400Toggle details

Returned if the client sends invalid request parameters e.g. filters

Headers

Content-Type: application/hal+json

Body

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
  "message": [
    "Filters Invalid filter does not exist."
  ]
}

Response 403Toggle details

Returned if the client is not logged in and login is required.

Headers

Content-Type: application/hal+json

Body

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to view this resource."
}

Help and feedback