API: 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 | Condition |
|---|---|---|---|---|---|
| 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 | Condition |
|---|---|---|---|---|---|
| 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 |
Methods
List documents
The documents returned depend on the provided parameters and also on the requesting user’s permissions.
offset
integer
optional query
Page number inside the requested collection.
Default:1
Example:25
pageSize
integer
optional query
Number of elements to display per page.
Example:25
sortBy
string
optional query
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
Example:[["created_at", "asc"]]
200
OK
{
"_embedded": {
"elements": [
{
"_links": {
"addAttachment": {
"href": "/api/v3/documents/1/attachments",
"method": "post"
},
"attachments": {
"href": "/api/v3/documents/1/attachments"
},
"project": {
"href": "/api/v3/projects/19",
"title": "Some project"
},
"self": {
"href": "/api/v3/documents/1",
"title": "Some document"
}
},
"_type": "Document",
"createdAt": "2018-12-10T20:53:39.184Z",
"description": {
"format": "markdown",
"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>",
"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."
},
"id": 1,
"title": "Some other document"
},
{
"_links": {
"addAttachment": {
"href": "/api/v3/documents/2/attachments",
"method": "post"
},
"attachments": {
"href": "/api/v3/documents/2/attachments"
},
"project": {
"href": "/api/v3/projects/29",
"title": "Some other project"
},
"self": {
"href": "/api/v3/documents/2",
"title": "Some other document"
}
},
"_type": "Document",
"createdAt": "2018-12-10T20:55:54.049Z",
"description": {
"format": "markdown",
"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>",
"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."
},
"id": 2,
"title": "Some other document"
}
]
},
"_links": {
"changeSize": {
"href": "/api/v3/documents?offset=1&pageSize=%7Bsize%7D",
"templated": true
},
"jumpTo": {
"href": "/api/v3/documents?offset=%7Boffset%7D&pageSize=30",
"templated": true
},
"self": {
"href": "/api/v3/documents?offset=1&pageSize=30"
}
},
"_type": "Collection",
"count": 2,
"offset": 1,
"pageSize": 30,
"total": 2
}
DocumentsModel{
"type": "object",
"example": {
"_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:39.966Z",
"_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:54.886Z",
"_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
}
}
}
}
400
Returned if the client sends invalid request parameters e.g. filters
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": [
"Filters Invalid filter does not exist."
]
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client is not logged in and login is required.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to view this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
View document
id
integer
required path
Document id
Example:1
200
OK
{
"_embedded": {
"attachments": {
"_embedded...": {
"elements": []
},
"_links": {
"self": {
"href": "/api/v3/documents/1/attachments"
}
},
"_type": "Collection",
"count": 2,
"total": 2
},
"project": {
"_type": "Project..."
}
},
"_links": {
"addAttachment": {
"href": "/api/v3/documents/1/attachments",
"method": "post"
},
"attachments": {
"href": "/api/v3/documents/1/attachments"
},
"project": {
"href": "/api/v3/projects/19",
"title": "Some project"
},
"self": {
"href": "/api/v3/documents/1",
"title": "Some document"
}
},
"_type": "Document",
"createdAt": "2018-12-10T20:53:39.698Z",
"description": {
"format": "markdown",
"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>",
"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."
},
"id": 1,
"title": "Some other document"
}
DocumentModel{
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Document's id",
"readOnly": true,
"exclusiveMinimum": 0
},
"title": {
"type": "string",
"description": "The title chosen for the document"
},
"description": {
"type": "string",
"description": "A text describing the document"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The time the document was created at",
"readOnly": true
},
"_links": {
"type": "object",
"required": [
"self",
"project",
"attachments"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This document\n\n**Resource**: Document",
"readOnly": true
}
]
},
"project": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The project the document is in\n\n**Resource**: Project"
}
]
},
"attachments": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The attachments belonging to the document\n\n**Resource**: []Attachment"
}
]
}
}
}
},
"example": {
"_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:39.539Z",
"_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..."
},
"attachments": {
"_type": "Collection",
"total": 2,
"count": 2,
"_embedded...": {
"elements": []
},
"_links": {
"self": {
"href": "/api/v3/documents/1/attachments"
}
}
}
}
}
}
404
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
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Update document
Updates a document’s attributes.
id
integer
required path
Document id
Example:1
200
OK
{
"_embedded": {
"attachments": {
"_embedded...": {
"elements": []
},
"_links": {
"self": {
"href": "/api/v3/documents/1/attachments"
}
},
"_type": "Collection",
"count": 2,
"total": 2
},
"project": {
"_type": "Project..."
}
},
"_links": {
"addAttachment": {
"href": "/api/v3/documents/1/attachments",
"method": "post"
},
"attachments": {
"href": "/api/v3/documents/1/attachments"
},
"project": {
"href": "/api/v3/projects/19",
"title": "Some project"
},
"self": {
"href": "/api/v3/documents/1",
"title": "Updated document title"
}
},
"_type": "Document",
"createdAt": "2018-12-10T20:53:39.698Z",
"description": {
"format": "markdown",
"html": "<p>Updated description content</p>",
"raw": "Updated description content"
},
"id": 1,
"title": "Updated document title"
}
DocumentModel{
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Document's id",
"readOnly": true,
"exclusiveMinimum": 0
},
"title": {
"type": "string",
"description": "The title chosen for the document"
},
"description": {
"type": "string",
"description": "A text describing the document"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The time the document was created at",
"readOnly": true
},
"_links": {
"type": "object",
"required": [
"self",
"project",
"attachments"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This document\n\n**Resource**: Document",
"readOnly": true
}
]
},
"project": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The project the document is in\n\n**Resource**: Project"
}
]
},
"attachments": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The attachments belonging to the document\n\n**Resource**: []Attachment"
}
]
}
}
}
},
"example": {
"_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:39.539Z",
"_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..."
},
"attachments": {
"_type": "Collection",
"total": 2,
"count": 2,
"_embedded...": {
"elements": []
},
"_links": {
"self": {
"href": "/api/v3/documents/1/attachments"
}
}
}
}
}
}
400
Returned if the request body is invalid.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:BadRequest",
"message": "The request body was invalid."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the user does not have permission to edit the document.
Required permission manage documents in the project the document belongs to
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
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
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if the request body contains validation errors.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Title can't be blank.",
"_embedded": {
"details": {
"attribute": "title"
}
}
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
