Documents
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.
Types of Documents
There are three primary types of documents in awork.
Space documents
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 documents
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 documents
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.
Working with Documents
Creating a Document
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.
Document Content Requirements
The Content field for now must be provided as a file with the proper encoding to ensure special characters display correctly:
- For HTML content, use
text/html; charset=utf-8 - For plain text, use
text/plain; charset=utf-8 - For JSON content, use
application/json; charset=utf-8
Here’s an example creating a document with proper file content:
Creating a Document in a Space
To create a document in a document space, include the DocumentSpaceId:
Creating a Document in a Project
To create a document in a project, include the `ProjectId“:
Creating a Private Document
Private documents are only visible to you and users you explicitly share them with:
Retrieving a Document’s Content
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:
Permissions and Sharing
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.
Sharing a Document with Users
Sharing a Document with Teams
Document Structure and Nesting
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:
Document Trash Management
Documents can be moved to trash and later restored or permanently deleted.
Deleting a Document, moving it to the Trash
Restoring a Document from the Trash
Document Spaces
Document spaces provide a way to organize workspace-wide documents. They act as containers for related documents and can have their own permission settings.