Documents (Docs) provide a collaborative space for creating, sharing, and managing content. They allow teams to maintain a central knowledge base, create project documentation, and collaborate on content in real-time.
There are three primary types of documents in awork.
Spaces can be seen as folders within a workspace. These are where docs are managed and organized within a specific workspace. You can create multiple spaces within one workspace, and each doc can only exist in one space at a time. Docs can be moved from spaces to spaces or even into a project.
Project docs are connected to a specific project and can only be accessed through that project. These docs are always linked to the project and will remain there until they are moved to a space or made private. This ensures that all project-related docs are easily accessible and organized within the project. Project docs have special features regarding that project, like linking a task to a doc for status tracking.
Private docs are the default when creating a new document in the app and are similar to private projects in that they can only be seen by you until you choose to share them with another user or move them to a space or project. These docs are only accessible to you and are not visible to anyone else in your workspace.
To create a new document, you need to provide at least a name. Documents must be created using multipart/form-data (not JSON) to allow proper handling of the document content.
Documents can be created in a document space, within a project, or as private documents.
A document can always either belong to a space, a project or be private.
If you don’t specify a space id or project id, the document will be created as a private document by default.
The Content field must be provided as a file with the proper encoding to ensure special characters display correctly:
text/html; charset=utf-8text/plain; charset=utf-8application/json; charset=utf-8Here’s an example creating a document in a document space:
To create a document in a document space, include the DocumentSpaceId:
To create a document in a project, include the `ProjectId“:
Private documents are only visible to you and users you explicitly share them with:
To retrieve a document’s content, use the following endpoint:
By default, this returns a JSON object with the content as a string:
To stream the document content as a file instead, use the streamAsFile query parameter:
Documents can be shared with specific users or teams, and different access levels can be assigned. Documents can also be shared with the whole workspace by setting the workspaceAccessLevel on a document.
Documents support the following access levels:
For workspace access, there is also the None- option, which is the default, can be overridden by more explicit permission settings and grants the whole workspace no access.
Documents can be nested within other documents, creating a hierarchical structure. To create a nested document, specify the id of the document’s parent - the ParentId:
Documents can be moved to trash and later restored or permanently deleted.
Document spaces provide a way to organize workspace-wide documents. They act as containers for related documents and can have their own permission settings.