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
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

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

{
  "_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

{
  "_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 collection of documents",
      "readOnly": true
    },
    "description": {
      "type": "string",
      "description": "A text describing the documents",
      "readOnly": true
    },
    "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."
    }
  }
}

Aide et commentaires

Recherchez les termes de gestion de projet dans notre dictionnaire

Afficher le glossaire

Si vous avez besoin de l’aide de la communauté ou si vous voulez aider les autres

Publier sur le forum OpenProject

Si vous êtes admissible à l’assistance professionnelle et que vous avez d’autres questions

Demander de l'aide

Si vous trouvez une erreur facile à corriger ou un besoin d’amélioration dans la documentation

Modifier cette page

Si vous souhaitez suggérer des mises à jour ou des améliorations plus importantes pour cette documentation

Créer un ticket

Si vous voulez contribuer à traduire cette documentation dans une autre langue

Traduire sur Crowdin

S’il y a quelque chose que vous n’aimez pas ou ne comprenez pas à propos de cette fonctionnalité

Créer un ticket

Si vous voulez proposer une nouvelle fonctionnalité qu’OpenProject n’offre pas encore

Soumettre une proposition de fonctionnalité

Pour aider OpenProject à façonner et à tester de nouvelles fonctionnalités

Rejoindre le bêta-test

Pour consulter les modules Enterprise d’OpenProject et les prix

Voir la page des prix

Si vous souhaitez essayer gratuitement tous les modules Enterprise de la version cloud d’OpenProject Enterprise pendant 14 jours

Essai gratuit de la version cloud d'OpenProject Enterprise

Si vous souhaitez essayer tous les modules Enterprise dans votre installation Community sur site gratuitement pendant 14 jours

Essai gratuit de la version sur site d'OpenProject Enterprise

API: Documents

Actions

Linked Properties

Local Properties

Methods

List documents

View document

Sujets les plus populaires