Improve API overview examples and visuals

fern/pages/api/agents.mdx

@@ -6,9 +6,7 @@ slug: agents-overview
 
 Agents are AI teammates in awork. They can answer questions, prepare reports, and work on tasks and projects using the context of your workspace. Every user has a personal agent (the awork Agent), and workspaces can create custom agents with their own prompt, model configuration, capabilities, and connectors.
 
-<Frame>
-    <img src="/assets/api/agents01.jpg" alt="The Agents home in awork" />
-</Frame>
+<img src="/assets/api/agents01.jpg" alt="The Agents home in awork" />
 
 ## Core Concepts
 

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

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"
          }'
-```
+```
+
+## 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.

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"

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.
 
+<img src="/assets/api/documents-overview.png" alt="awork Docs project document with collaboration and comments" width="80%" align="center" />
+
 ## 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,11 +191,12 @@ 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",
            "emoji": "📚",
            "color": "purple",
            "workspaceAccessLevel": "read"
          }'
-```
+```

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

fern/pages/api/login.mdx

@@ -4,4 +4,53 @@ description: Login & Access API Reference.
 slug: login
 ---
 
+<img src="/assets/api/login-access-overview.png" alt="awork permissions and access illustration" width="212" align="center" />
+
+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).