-
+
## Core Concepts
diff --git a/fern/pages/api/api.mdx b/fern/pages/api/api.mdx
index 0b12d5a..108a239 100644
--- a/fern/pages/api/api.mdx
+++ b/fern/pages/api/api.mdx
@@ -4,4 +4,81 @@ description: API Management related endpoints Reference.
slug: api
---
-These endpoints allow you to manage interactions with the awork API. Please see the individual endpoint documentation for more information.
\ No newline at end of file
+These endpoints let administrators manage the credentials and delivery mechanisms used by integrations: API users, OAuth client applications, and webhooks. They require an administrator role or the corresponding `workspace-manage-config` permission.
+
+## Creating an API user
+
+API users are non-human accounts for server-to-server integrations. Assign a least-privileged role with `roleId`; omitting it creates an administrator, which is rarely appropriate for production:
+
+```sh title="Create an API user"
+curl -X POST 'https://api.awork.com/api/v1/apiusers' \
+ -H 'Authorization: Bearer {token}' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "name": "Billing sync",
+ "roleId": "323e4567-e89b-12d3-a456-426614174002",
+ "clientId": "billing-sync"
+ }'
+```
+
+The response contains the API user's id and the role it was assigned:
+
+```json title="Response"
+{
+ "id": "423e4567-e89b-12d3-a456-426614174003",
+ "name": "Billing sync",
+ "roleId": "323e4567-e89b-12d3-a456-426614174002",
+ "clientId": "billing-sync",
+ "createdOn": "2026-09-12T09:00:00Z"
+}
+```
+
+Use `GET /apiusers` to audit existing API users. API users also appear in `GET /users?showArchived=true`; store the returned id with your integration configuration.
+
+## Registering an OAuth client
+
+For an interactive integration, register a client application and provide the exact redirect URI used by your OAuth callback. Set `isConfidential` to `true` only when the client secret can be kept on a server:
+
+```sh title="Register an OAuth client"
+curl -X POST 'https://api.awork.com/api/v1/clientapplications' \
+ -H 'Authorization: Bearer {token}' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "clientId": "northstar-reporting",
+ "displayName": "Northstar Reporting",
+ "redirectUris": ["https://reports.example.com/oauth/callback"],
+ "isConfidential": true
+ }'
+```
+
+```json title="Response"
+{
+ "clientId": "northstar-reporting",
+ "displayName": "Northstar Reporting",
+ "redirectUris": ["https://reports.example.com/oauth/callback"],
+ "isConfidential": true,
+ "clientSecret": "store-this-secret-securely"
+}
+```
+
+The response contains the registered `clientId` and, for confidential clients, a `clientSecret`. Treat the secret like a password. See [Authentication](/authentication) for the authorization-code flow.
+
+## Receiving changes with a webhook
+
+First list valid event names with `GET /webhooks/eventtypes`. Then create a webhook. The receiver type is inferred from the URI; any non-Slack URI is treated as a custom webhook:
+
+```sh title="Create a webhook"
+curl -X POST 'https://api.awork.com/api/v1/webhooks' \
+ -H 'Authorization: Bearer {token}' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "name": "Project changes",
+ "uri": "https://integrations.example.com/awork/events",
+ "events": "project_added,project_updated",
+ "isActive": true,
+ "authenticationType": "header",
+ "authentication": "X-Integration-Key=replace-with-secret"
+ }'
+```
+
+Use `GET /webhooks/{webhookId}/logs` to troubleshoot deliveries. Webhook payloads are sent to the configured URI and include the event metadata and the entity that changed; see the [Webhooks guide](/webhooks) for payload details.
diff --git a/fern/pages/api/companies.mdx b/fern/pages/api/companies.mdx
index 824f47e..f75924c 100644
--- a/fern/pages/api/companies.mdx
+++ b/fern/pages/api/companies.mdx
@@ -6,14 +6,74 @@ slug: companies
Companies (Clients in the awork UI) are the contacts or organizations that you work with. Projects are usually connected to Companies.
+Most company integrations follow the same pattern: create or find the company, store its id in your system, then add contact information and link projects to it. Company endpoints require the `company-master-data` permission (or an administrator role).
+
## Creating a company
Creating a company is easy. The only required field for creating a company is the `name`.
```sh title="Request" {4}
curl -X POST "https://api.awork.com/api/v1/companies" \
+ -H "Authorization: Bearer {token}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Northstar Creative",
+ "description": "Brand and product design partner",
+ "industry": "Design agency"
+ }'
+```
+
+Save the returned company `id` for subsequent requests:
+
+```json title="Response"
+{
+ "id": "123e4567-e89b-12d3-a456-426614174000",
+ "name": "Northstar Creative",
+ "description": "Brand and product design partner",
+ "industry": "Design agency",
+ "projectsCount": 0,
+ "projectsInProgressCount": 0
+}
+```
+
+## Finding and updating a company
+
+Use the list endpoint to find companies by name or another field with the standard [filtering](/filtering) and [pagination](/pagination) parameters:
+
+```sh title="List companies"
+curl 'https://api.awork.com/api/v1/companies?page=1&pageSize=25&filterby=name%20eq%20%22Northstar%20Creative%22' \
+ -H "Authorization: Bearer {token}"
+```
+
+Update only the fields you want to change. The `name` remains required on the update form:
+
+```sh title="Update a company"
+curl -X PUT "https://api.awork.com/api/v1/companies/123e4567-e89b-12d3-a456-426614174000" \
+ -H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
- "name": "My first company"
+ "name": "Northstar Creative GmbH",
+ "industry": "Brand agency"
}'
-```
\ No newline at end of file
+```
+
+## Adding contact information
+
+Contact information is managed separately from the company. For example, add a billing address and then retrieve all contact records with `GET /companies/{companyId}/contactinfo`:
+
+```sh title="Add a billing address"
+curl -X POST "https://api.awork.com/api/v1/companies/123e4567-e89b-12d3-a456-426614174000/contactinfo" \
+ -H "Authorization: Bearer {token}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "type": "address",
+ "subType": "invoice",
+ "addressLine1": "Torstraße 140",
+ "zipCode": "10119",
+ "city": "Berlin",
+ "country": "DE",
+ "isAddress": true
+ }'
+```
+
+See the [Companies API reference](/apiv1/companies) for contact-info update and delete operations.
diff --git a/fern/pages/api/customfields.mdx b/fern/pages/api/customfields.mdx
index 76c6586..196e266 100644
--- a/fern/pages/api/customfields.mdx
+++ b/fern/pages/api/customfields.mdx
@@ -32,6 +32,7 @@ To create a custom field, you need to send a POST request to the custom field de
```sh title="Create a text custom field"
curl -X POST https://api.awork.com/api/v1/customfielddefinitions \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "Service Level",
@@ -48,6 +49,7 @@ Next, the custom field must be linked to a project before a value can be set for
```sh title="Link a custom field to a project"
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/linkcustomfielddefinition \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000",
@@ -63,6 +65,7 @@ Finally, you can set a value for the custom field for a task. To do so, you need
```sh title="Set a custom field value for a task"
curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/setcustomfields \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '[
{
@@ -80,6 +83,7 @@ To get the values of custom fields of a task, you simply need to fetch the task.
```sh title="Get the custom field values of a task"
curl -X GET https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000 \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json"
```
```json title="Response"
diff --git a/fern/pages/api/documents.mdx b/fern/pages/api/documents.mdx
index 4a22001..dd538c2 100644
--- a/fern/pages/api/documents.mdx
+++ b/fern/pages/api/documents.mdx
@@ -7,6 +7,8 @@ slug: 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.
@@ -44,6 +46,7 @@ Here's an example creating a document in a document space:
```sh title="Request"
curl -X POST "https://api.awork.com/api/v1/documents" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: multipart/form-data" \
-F "Name=My New Document" \
-F "DocumentSpaceId=123e4567-e89b-12d3-a456-426614174000" \
@@ -55,6 +58,7 @@ To create a document in a document space, include the `DocumentSpaceId`:
```sh title="Request"
curl -X POST "https://api.awork.com/api/v1/documents" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: multipart/form-data" \
-F "Name=My New Document" \
-F "DocumentSpaceId=123e4567-e89b-12d3-a456-426614174000" \
@@ -66,6 +70,7 @@ To create a document in a project, include the `ProjectId``:
```sh title="Request"
curl -X POST "https://api.awork.com/api/v1/documents" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: multipart/form-data" \
-F "Name=My New Document" \
-F "ProjectId=123e4567-e89b-12d3-a456-426614174000" \
@@ -77,6 +82,7 @@ Private documents are only visible to you and users you explicitly share them wi
```sh title="Request"
curl -X POST "https://api.awork.com/api/v1/documents" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: multipart/form-data" \
-F "Name=My Private Document" \
-F "IsPrivate=true" \
@@ -88,6 +94,7 @@ To retrieve a document's content, use the following endpoint:
```sh title="Request"
curl -X GET "https://api.awork.com/api/v1/documents/123e4567-e89b-12d3-a456-426614174000/content" \
+-H "Authorization: Bearer {token}"
```
By default, this returns a JSON object with the content as a string:
@@ -102,6 +109,7 @@ 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:
```sh title="Request"
curl -X GET "https://api.awork.com/api/v1/documents/123e4567-e89b-12d3-a456-426614174000/content?streamAsFile=true" \
+-H "Authorization: Bearer {token}"
```
### Permissions and Sharing
@@ -120,6 +128,7 @@ For workspace access, there is also the `None`- option, which is the default, ca
```sh title="Request"
curl -X POST "https://api.awork.com/api/v1/documents/123e4567-e89b-12d3-a456-426614174000/contributors" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '[
{
@@ -136,6 +145,7 @@ curl -X POST "https://api.awork.com/api/v1/documents/123e4567-e89b-12d3-a456-426
#### Sharing a Document with Teams
```sh title="Request"
curl -X POST "https://api.awork.com/api/v1/documents/123e4567-e89b-12d3-a456-426614174000/teams" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '[
{
@@ -150,6 +160,7 @@ Documents can be nested within other documents, creating a hierarchical structur
```sh title="Request"
curl -X POST "https://api.awork.com/api/v1/documents" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: multipart/form-data" \
-F "Name=Nested Document" \
-F "ParentId=123e4567-e89b-12d3-a456-426614174000" \
@@ -162,13 +173,15 @@ Documents can be moved to trash and later restored or permanently deleted.
#### Deleting a Document, moving it to the Trash
```sh title="Request"
-curl -X DELETE "https://api.awork.com/api/v1/documents/123e4567-e89b-12d3-a456-426614174000"
+curl -X DELETE "https://api.awork.com/api/v1/documents/123e4567-e89b-12d3-a456-426614174000" \
+-H "Authorization: Bearer {token}"
```
#### Restoring a Document from the Trash
```sh title="Request"
-curl -X POST "https://api.awork.com/api/v1/documents/trash/123e4567-e89b-12d3-a456-426614174000/restore"
+curl -X POST "https://api.awork.com/api/v1/documents/trash/123e4567-e89b-12d3-a456-426614174000/restore" \
+-H "Authorization: Bearer {token}"
```
## Document Spaces
@@ -178,6 +191,7 @@ Document spaces provide a way to organize workspace-wide documents. They act as
```sh title="Request"
curl -X POST "https://api.awork.com/api/v1/documentSpaces" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketing Team",
@@ -185,4 +199,4 @@ curl -X POST "https://api.awork.com/api/v1/documentSpaces" \
"color": "purple",
"workspaceAccessLevel": "read"
}'
-```
\ No newline at end of file
+```
diff --git a/fern/pages/api/files.mdx b/fern/pages/api/files.mdx
index 2030f5a..cdf7b99 100644
--- a/fern/pages/api/files.mdx
+++ b/fern/pages/api/files.mdx
@@ -15,6 +15,7 @@ Uploading a file takes three steps.
```sh title="Generate Upload URL"
curl -X POST https://api.awork.com/api/v1/files/generateUploadURL \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json'
```
@@ -37,6 +38,7 @@ curl -X PUT https://upload.awork.com/... \
Once that is done, link the uploaded file with a task:
```sh title="Link File with Task"
curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/files/byUploadId \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"uploadId": "123e4567-e89b-12d3-a456-426614174000",
@@ -50,6 +52,7 @@ Several entities in awork support profile images. This is how you can upload an
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/files/images/projects/123e4567-e89b-12d3-a456-426614174000 \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: multipart/form-data' \
-F 'File=@/path/to/file.png'
```
diff --git a/fern/pages/api/login.mdx b/fern/pages/api/login.mdx
index c52c38a..e1124c1 100644
--- a/fern/pages/api/login.mdx
+++ b/fern/pages/api/login.mdx
@@ -4,4 +4,53 @@ description: Login & Access API Reference.
slug: login
---
+
+
+The Login & Access endpoints help you identify the current account, invite workspace members, and inspect the roles and permissions that control API access. Use the [Authentication guide](/authentication) to obtain the Bearer token before calling these endpoints.
+
+## Inspecting the current user's access
+
+Start with `GET /me/permissions` to discover the features available to the authenticated user. This is useful for integrations that enable or hide functionality based on workspace permissions:
+
+```sh title="Get current user permissions"
+curl 'https://api.awork.com/api/v1/me/permissions' \
+ -H 'Authorization: Bearer {token}'
+```
+
+To identify the user and workspace the token belongs to, call `GET /users/me`:
+
+```sh title="Get current user and workspace"
+curl 'https://api.awork.com/api/v1/users/me' \
+ -H 'Authorization: Bearer {token}'
+```
+
+```json title="Response"
+{
+ "id": "123e4567-e89b-12d3-a456-426614174000",
+ "workspace": {
+ "id": "223e4567-e89b-12d3-a456-426614174001",
+ "name": "Northstar Creative",
+ "url": "https://northstar.awork.com"
+ }
+}
+```
+
+## Inviting a workspace member
+
+Invitations are one of the few API calls that require an explicit `workspaceId`. Get that id from `/users/me`, then provide the role that the new member should receive:
+
+```sh title="Invite a user"
+curl -X POST 'https://api.awork.com/api/v1/invitations' \
+ -H 'Authorization: Bearer {token}' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "email": "carla.creative@example.com",
+ "invitationFlow": "invite",
+ "workspaceId": "223e4567-e89b-12d3-a456-426614174001",
+ "roleId": "323e4567-e89b-12d3-a456-426614174002"
+ }'
+```
+
+The caller must have permission to invite users. Use `GET /roles` to list valid role ids before creating the invitation. The recipient completes the process with the invitation link; integrations do not need to handle the acceptance request themselves.
+
Learn more about awork's [permission management](https://support.awork.com/en/articles/permissions-management-in-awork-qVeVCScCl9db).
diff --git a/fern/pages/api/projects.mdx b/fern/pages/api/projects.mdx
index 570e53e..d7cfbcd 100644
--- a/fern/pages/api/projects.mdx
+++ b/fern/pages/api/projects.mdx
@@ -6,6 +6,8 @@ slug: projects
Projects are one of the core entities in the awork API. They represent a collection of tasks and other resources that are related to a specific project. Projects can be used to organize work, track progress, and collaborate with others in awork.
+
+
## How to work with projects
There are two major ways for creating a project in awork: using a project template or from scratch. See the [Project Template](./projecttemplates.mdx) endpoint for more information on how to manage project templates.
@@ -14,8 +16,9 @@ There are two major ways for creating a project in awork: using a project templa
Creating a project from scratch is easy. The only required field for creating a project is the `name`.
-```sh title="Request" {4}
+```sh title="Request" {5}
curl -X POST "https://api.awork.com/api/v1/projects" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "My new project"
@@ -27,8 +30,9 @@ curl -X POST "https://api.awork.com/api/v1/projects" \
You can create and link a project to a workflow directly in `POST /projects` by passing `workflowId`.
If needed, you can also pass a valid `projectStatusId` from that workflow.
-```sh title="Request" {5-6}
+```sh title="Request" {6-7}
curl -X POST "https://api.awork.com/api/v1/projects" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "My workflow-based project",
@@ -42,11 +46,13 @@ curl -X POST "https://api.awork.com/api/v1/projects" \
Before creating a project with `workflowId`, fetch the workflow statuses and pick a valid `projectStatusId`.
```sh title="Get workflow project statuses"
-curl -X GET "https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/projectstatuses"
+curl -X GET "https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/projectstatuses" \
+-H "Authorization: Bearer {token}"
```
```sh title="Get workflow task statuses"
-curl -X GET "https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/taskstatuses"
+curl -X GET "https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/taskstatuses" \
+-H "Authorization: Bearer {token}"
```
### Getting valid statuses for an existing project
@@ -55,19 +61,22 @@ Use project-scoped endpoints to fetch the statuses that are valid for one specif
These endpoints already return the correct set, including workflow-inherited statuses when the project is linked to a workflow.
```sh title="Get valid project statuses for a project"
-curl -X GET "https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/projectstatuses"
+curl -X GET "https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/projectstatuses" \
+-H "Authorization: Bearer {token}"
```
```sh title="Get valid task statuses for a project"
-curl -X GET "https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/taskstatuses"
+curl -X GET "https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/taskstatuses" \
+-H "Authorization: Bearer {token}"
```
### Creating a project from a template
To create a project from a project template, the `projectTemplateId` has to be passed in the `POST /projects` request.
-```sh title="Request" {5}
+```sh title="Request" {6}
curl -X POST "https://api.awork.com/api/v1/projects" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "My new project from a template",
@@ -96,6 +105,7 @@ Project comments allow for discussions and communication about projects. You can
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/comments \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"message": "This is a comment on the project"
@@ -108,6 +118,7 @@ You can mention users in comments by using a special syntax with the user's Id.
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/comments \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"message": "~[userId:123e4567-e89b-12d3-a456-426614174000] Take a look at this project
" @@ -122,6 +133,7 @@ In addition to mentioning specific users, you can notify all members of a projec ```sh title="Request" curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/comments \ +-H "Authorization: Bearer {token}" \ -H 'Content-Type: application/json' \ -d '{ "message": "~[project] This will notify all users in this project
" diff --git a/fern/pages/api/projecttemplates.mdx b/fern/pages/api/projecttemplates.mdx index b37d371..edf0e11 100644 --- a/fern/pages/api/projecttemplates.mdx +++ b/fern/pages/api/projecttemplates.mdx @@ -4,6 +4,8 @@ description: Project Templates API Reference. slug: projecttemplates --- +
+
Learn more about [project templates](https://support.awork.com/en/articles/project-templates-DhvJCSuVBExv).
## Workflows and project templates
@@ -16,8 +18,9 @@ The flow is:
### Creating a project template
-```sh title="Create a project template" {4}
+```sh title="Create a project template" {5}
curl -X POST https://api.awork.com/api/v1/projecttemplates \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Client Delivery Template"
@@ -26,8 +29,9 @@ curl -X POST https://api.awork.com/api/v1/projecttemplates \
### Linking a project template to a workflow
-```sh title="Link template to workflow" {4}
+```sh title="Link template to workflow" {5}
curl -X POST https://api.awork.com/api/v1/projecttemplates/123e4567-e89b-12d3-a456-426614174000/linkworkflow \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"workflowId": "223e4567-e89b-12d3-a456-426614174000",
@@ -52,6 +56,7 @@ curl -X POST https://api.awork.com/api/v1/projecttemplates/123e4567-e89b-12d3-a4
```sh title="Unlink template from workflow"
curl -X POST https://api.awork.com/api/v1/projecttemplates/123e4567-e89b-12d3-a456-426614174000/unlinkworkflow \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json'
```
@@ -73,8 +78,9 @@ When a task bundle is applied to a project, it creates actual task lists and tas
The only required field for creating a task bundle is the `name`:
-```sh title="Create a new task bundle" {4}
+```sh title="Create a new task bundle" {5}
curl -X POST https://api.awork.com/api/v1/taskbundles \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Website Launch",
@@ -87,8 +93,9 @@ curl -X POST https://api.awork.com/api/v1/taskbundles \
Once you have a task bundle, you can create task list templates within it:
-```sh title="Create a task list template" {4}
+```sh title="Create a task list template" {5}
curl -X POST https://api.awork.com/api/v1/taskbundles/123e4567-e89b-12d3-a456-426614174000/tasklisttemplates \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Design",
@@ -100,8 +107,9 @@ curl -X POST https://api.awork.com/api/v1/taskbundles/123e4567-e89b-12d3-a456-42
Create task templates within a task bundle:
-```sh title="Create a task template" {4-8}
+```sh title="Create a task template" {5-9}
curl -X POST https://api.awork.com/api/v1/taskbundles/123e4567-e89b-12d3-a456-426614174000/tasktemplates \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Create wireframe mockups",
@@ -118,6 +126,7 @@ Assign task templates to specific task list templates:
```sh title="Assign task templates to a list"
curl -X POST https://api.awork.com/api/v1/taskbundles/123e4567-e89b-12d3-a456-426614174000/tasklisttemplates/456e4567-e89b-12d3-a456-426614174000/addtasktemplates \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '[
{
@@ -134,8 +143,9 @@ When a task bundle is applied:
- **Tasks** are always created in the project
- **Task lists** are merged based on their name (existing lists with matching names are reused)
-```sh title="Apply task bundle to project" {4}
+```sh title="Apply task bundle to project" {5}
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/addtaskbundle \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"taskBundleId": "123e4567-e89b-12d3-a456-426614174000"
diff --git a/fern/pages/api/search.mdx b/fern/pages/api/search.mdx
index 600f835..8f121a7 100644
--- a/fern/pages/api/search.mdx
+++ b/fern/pages/api/search.mdx
@@ -4,6 +4,76 @@ description: Search API Reference.
slug: search
---
-The search endpoint allows you to find entities by text in awork.
+The search endpoint allows you to find entities by text in awork. It searches across the entities the authenticated user can access and ranks matches by relevance.
+
+## Searching the workspace
+
+Pass the search text in `searchTerm`. Limit the search to one or more entity types with the comma-separated `searchTypes` parameter, and use `top` to control how many matches are returned. The default is 20 results. Include completed or closed records with `includeClosedAndStuck=true` when you need historical results.
+
+```sh title="Search projects and tasks"
+curl 'https://api.awork.com/api/v1/search?searchTerm=website%20launch&searchTypes=project,task&top=10' \
+ -H 'Authorization: Bearer {token}'
+```
+
+The response includes an overall count and grouped result collections. Each result contains the matching entity and its relevance score:
+
+```json title="Response"
+{
+ "totalCount": 2,
+ "maxScore": 0.93,
+ "top": [
+ {
+ "type": "project",
+ "score": 0.93,
+ "entity": {
+ "id": "123e4567-e89b-12d3-a456-426614174000",
+ "name": "Website Launch"
+ }
+ },
+ {
+ "type": "task",
+ "score": 0.81,
+ "entity": {
+ "id": "223e4567-e89b-12d3-a456-426614174001",
+ "name": "Review launch checklist"
+ }
+ }
+ ],
+ "projectHits": {
+ "totalCount": 1,
+ "maxScore": 0.93,
+ "hasHits": true,
+ "hits": [
+ {
+ "type": "project",
+ "score": 0.93,
+ "entity": {
+ "id": "123e4567-e89b-12d3-a456-426614174000",
+ "name": "Website Launch",
+ "isOpen": true
+ }
+ }
+ ]
+ },
+ "taskHits": {
+ "totalCount": 1,
+ "maxScore": 0.81,
+ "hasHits": true,
+ "hits": [
+ {
+ "type": "task",
+ "score": 0.81,
+ "entity": {
+ "id": "223e4567-e89b-12d3-a456-426614174001",
+ "name": "Review launch checklist",
+ "isOpen": true
+ }
+ }
+ ]
+ }
+}
+```
+
+Supported search types include `task`, `project`, `user`, `company`, `comment`, `timeentry`, `timereport`, `file`, `document`, `tasklist`, and `dashboardnote`. Use `searchTypes=all` to search every supported type. `searchTerm` is required and may contain up to 50 characters.
[Learn more](https://support.awork.com/en/articles/the-main-menu-tEMWckKpWoHa) about how to search for your data in awork.
diff --git a/fern/pages/api/tasks.mdx b/fern/pages/api/tasks.mdx
index f7aab31..c24d2d8 100644
--- a/fern/pages/api/tasks.mdx
+++ b/fern/pages/api/tasks.mdx
@@ -6,6 +6,8 @@ slug: tasks
Tasks represent the smallest unit of work in awork. They are used to break down larger chunks of work, track progress, and collaborate with others.
+
+
## Types of Tasks
There are two types of tasks: project tasks and private tasks. This is identified by the `baseType` field in the task object, which can be either `projecttask` or `private`.
@@ -23,8 +25,9 @@ There are two types of tasks: project tasks and private tasks. This is identifie
The following properties are required when creating a task:
-```sh title="Request" {4-8}
+```sh title="Request" {5-9}
curl -X POST https://api.awork.com/api/v1/tasks \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "My first task",
@@ -39,8 +42,9 @@ curl -X POST https://api.awork.com/api/v1/tasks \
Subtasks have almost the same properties as tasks, but they also have a `parentId` property that references the parent task. This is how you can create a subtask:
-```sh title="Request" {9}
+```sh title="Request" {10}
curl -X POST https://api.awork.com/api/v1/tasks \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "My first task",
@@ -62,6 +66,7 @@ Each task comes with a checklist of simple items that can be checked off. This i
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/checklistItems \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "My first checklist item"
@@ -76,6 +81,7 @@ Tasks can be in one or several task lists. This is how you can add a task to a t
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/tasks/changelists \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '[
{
@@ -95,6 +101,7 @@ Task comments allow for discussions and communication about tasks. You can add c
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/comments \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"message": "This is a comment on the task"
@@ -107,6 +114,7 @@ You can mention users in comments by using a special syntax with the user's Id.
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/comments \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"message": "~[userId:123e4567-e89b-12d3-a456-426614174000] Take a look at this task
" @@ -121,6 +129,7 @@ In addition to mentioning specific users, you can notify all users watching a ta ```sh title="Request" curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/comments \ +-H "Authorization: Bearer {token}" \ -H 'Content-Type: application/json' \ -d '{ "message": "~[task] This will notify all users watching this task
" diff --git a/fern/pages/api/timetracking.mdx b/fern/pages/api/timetracking.mdx index 907f299..f12f285 100644 --- a/fern/pages/api/timetracking.mdx +++ b/fern/pages/api/timetracking.mdx @@ -6,6 +6,8 @@ slug: timetracking Time Tracking and the resulting Time Entries allow project progress to be tracked and ultimately billed to a client. +
+
## How to work with time tracking
Time Tracking in awork is based on Time Entries. Time Entries are created for a specific project and task and are always assigned to a user. There are two ways to create time entries: manually or using the timer.
@@ -14,8 +16,9 @@ Time Tracking in awork is based on Time Entries. Time Entries are created for a
There are multiple ways to create time entries. The easiest way is by specifying the `startDateUtc` and `duration`. The only other required fields for creating a time entry are the `timezone`, `typeOfWorkId` and `userId`.
-```sh title="Request" {4-8}
+```sh title="Request" {5-9}
curl -X POST "https://api.awork.com/api/v1/timeentries" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"timezone": "Europe/Berlin",
@@ -30,8 +33,9 @@ Alternatively, you can also specify the `startDateUtc` and `endDateUtc` fields t
Additionally, you can assign the time entry to a specific project and task by providing the `projectId` and `taskId` fields.
-```sh title="Request" {7-8}
+```sh title="Request" {8-9}
curl -X POST "https://api.awork.com/api/v1/timeentries" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"timezone": "Europe/Berlin",
@@ -50,6 +54,7 @@ The timer is a convenient way to track time while working on a task or project.
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/timetracking/start \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"timezone": "Europe/Berlin",
diff --git a/fern/pages/api/users.mdx b/fern/pages/api/users.mdx
index af07367..bb3f75e 100644
--- a/fern/pages/api/users.mdx
+++ b/fern/pages/api/users.mdx
@@ -6,12 +6,24 @@ slug: users
Users represent the people who are part of an awork workspace. They can be assigned to tasks, projects, and other resources. Users can have different roles and permissions in the workspace.
+Use `GET /users` when you need a directory, and `GET /users/me` when you need the identity and workspace associated with the current token. User ids returned by these endpoints are used when assigning work, inviting members, or adding contact information.
+
+## Listing users
+
+```sh title="List active users"
+curl 'https://api.awork.com/api/v1/users?page=1&pageSize=50' \
+ -H 'Authorization: Bearer {token}'
+```
+
+The list endpoint supports the standard [filtering](/filtering), [ordering](/ordering), and [pagination](/pagination) parameters. Archived users are omitted unless you set `showArchived=true`.
+
## Inviting Users
To invite a new user to an awork workspace, you need to make a request to `POST /invitations`. This is one of the few requests that requires a `workspaceId`.
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/invitations \
+ -H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
-d '{
"email": "carla.creative@ncnstn.com",
@@ -24,7 +36,8 @@ curl -X POST https://api.awork.com/api/v1/invitations \
You can find the workspace id of the current user by making a request to the `/users/me` endpoint.
```sh title="Request"
-curl -X GET https://api.awork.com/api/v1/users/me
+curl -X GET https://api.awork.com/api/v1/users/me \
+ -H 'Authorization: Bearer {token}'
```
```json title="Response" {4}
{
@@ -35,4 +48,27 @@ curl -X GET https://api.awork.com/api/v1/users/me
"url": "https://ncnstn.awork.com"
}
}
-```
\ No newline at end of file
+```
+
+## Updating a user
+
+Update profile fields with `PUT /users/{userId}`. Use the dedicated activate, deactivate, and archive operations for account state changes.
+
+```sh title="Update a user's profile"
+curl -X PUT 'https://api.awork.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000' \
+ -H 'Authorization: Bearer {token}' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "firstName": "Carla",
+ "lastName": "Creative",
+ "position": "Senior Designer",
+ "language": "en-GB"
+ }'
+```
+
+For example, temporarily disable a user without deleting their historical assignments:
+
+```sh title="Deactivate a user"
+curl -X POST 'https://api.awork.com/api/v1/users/123e4567-e89b-12d3-a456-426614174000/deactivate' \
+ -H 'Authorization: Bearer {token}'
+```
diff --git a/fern/pages/api/v2/timetracking.mdx b/fern/pages/api/v2/timetracking.mdx
index ddcbf7a..053138f 100644
--- a/fern/pages/api/v2/timetracking.mdx
+++ b/fern/pages/api/v2/timetracking.mdx
@@ -22,8 +22,9 @@ There are two ways to create time entries: manually or using the timer.
There are multiple ways to create time entries. The easiest way is by specifying the `startDate` and `duration`. The only other required fields for creating a time entry are the `timezone`, `typeOfWorkId` and `userId`.
-```sh title="Request" {4-8}
+```sh title="Request" {5-9}
curl -X POST "https://api.awork.com/api/v2/timeentries" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"timezone": "Europe/Berlin",
@@ -39,8 +40,9 @@ If you specify both `duration`and `endDate`, the `endDate` takes precedence and
Additionally, you can assign the time entry to a specific project and task by providing the `projectId` and `taskId` fields.
-```sh title="Request" {7-8}
+```sh title="Request" {8-9}
curl -X POST "https://api.awork.com/api/v2/timeentries" \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"timezone": "Europe/Berlin",
@@ -59,6 +61,7 @@ The timer is a convenient way to track time while working on a task or project.
```sh title="Request"
curl -X POST https://api.awork.com/api/v2/users/123e4567-e89b-12d3-a456-426614174000/timetracking/start \
+-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"timezone": "Europe/Berlin",
@@ -69,7 +72,8 @@ curl -X POST https://api.awork.com/api/v2/users/123e4567-e89b-12d3-a456-42661417
To find the currently running time entry of a user, you can use the `GET /v2/users/:userId/timeentries/last` endpoint and check whether the returned time entry has a duration of 0, which indicates that the timer is running. If the duration is > 0, no timer is running.
```sh title="Request"
-curl -X GET https://api.awork.com/api/v2/users/123e4567-e89b-12d3-a456-426614174000/timeentries/last
+curl -X GET https://api.awork.com/api/v2/users/123e4567-e89b-12d3-a456-426614174000/timeentries/last \
+-H "Authorization: Bearer {token}"
```
You can additionally specify the project and task to start the timer for. You can then also pause, resume and stop the timer. There can only be one active timer per user. Timers are automatically stopped after 24h or when the time entry reaches the maximum allowed time for that user and day.
@@ -88,5 +92,6 @@ Breaks cannot be created/updated/deleted manually. They are only created when th
If you want to remove the breaks, you can do so by making a request to `POST /v2/timeentries/:timeEntryId/removeBreaks`.
```sh title="Request"
-curl -X POST https://api.awork.com/api/v2/timeentries/123e4567-e89b-12d3-a456-426614174000/removeBreaks
+curl -X POST https://api.awork.com/api/v2/timeentries/123e4567-e89b-12d3-a456-426614174000/removeBreaks \
+-H "Authorization: Bearer {token}"
```
diff --git a/fern/pages/api/workflows.mdx b/fern/pages/api/workflows.mdx
index 4f5c98c..45cd3a8 100644
--- a/fern/pages/api/workflows.mdx
+++ b/fern/pages/api/workflows.mdx
@@ -4,7 +4,7 @@ description: Workflows API Reference.
slug: workflows
---
-
+
Workflows are reusable process definitions that let you share project statuses and task statuses across multiple projects. Instead of maintaining statuses per project, you can manage them once in a workflow and keep linked projects aligned.
@@ -20,6 +20,7 @@ Create a reusable workflow in your workspace.
```sh title="Create a workflow"
curl -X POST https://api.awork.com/api/v1/workflows \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Client Delivery Workflow",
@@ -31,8 +32,9 @@ curl -X POST https://api.awork.com/api/v1/workflows \
Linking applies workflow-controlled statuses to the project. If the project already has statuses, provide mappings to migrate safely.
-```sh title="Link workflow to a project" {4}
+```sh title="Link workflow to a project" {5}
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/linkworkflow \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"workflowId": "223e4567-e89b-12d3-a456-426614174000",
@@ -59,6 +61,7 @@ Use an existing project as a blueprint and optionally link that project to the n
```sh title="Create workflow from project configuration"
curl -X POST https://api.awork.com/api/v1/workflows/fromproject/123e4567-e89b-12d3-a456-426614174000 \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Workflow from Consulting Template",
@@ -76,6 +79,7 @@ You can manage workflow-level statuses, which are then shared across linked proj
```sh title="Create task status in a workflow"
curl -X POST https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/taskstatuses \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Client Feedback",
@@ -87,6 +91,7 @@ curl -X POST https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-4266
```sh title="Create project status in a workflow"
curl -X POST https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/projectstatuses \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Blocked by Client",
@@ -100,5 +105,6 @@ Unlinking decouples the project from workflow sync and clones workflow statuses
```sh title="Unlink workflow from project"
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/unlinkworkflow \
+-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json'
```
diff --git a/fern/pages/api/workload.mdx b/fern/pages/api/workload.mdx
index b590cb0..77e1bc7 100644
--- a/fern/pages/api/workload.mdx
+++ b/fern/pages/api/workload.mdx
@@ -4,4 +4,41 @@ description: Workload & Planning API Reference.
slug: workload
---
+
+
+Workload data shows how much capacity users have available for planned work on each day. The calculation includes assigned and scheduled tasks, time bookings, calendar events, recurring tasks, weekly availability, and absences.
+
+