For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
SupportDeveloper ForumLogin
  • Overview
    • Introduction
    • Getting Started
    • Integration Example (PSA)
    • Authentication
    • Error Handling
    • Pagination
    • Filtering
    • Ordering
    • Rate Limits
    • Permissions
    • Webhooks
    • MCP Server
    • Versioning
    • Changelog
    • Support
  • API v1 Reference
    • Projects Overview
    • Tasks Overview
    • Time Tracking Overview
    • Documents Overview
    • Search Overview
    • Companies Overview
    • Users Overview
    • Files & Images Overview
    • Custom Fields Overview
    • Workload & Planning Overview
    • Project Templates Overview
    • Workflows Overview
    • Login & Access Overview
    • API Management Overview
LogoLogo
SupportDeveloper ForumLogin
On this page
  • OpenAPI Specification
  • Request Structure
  • CRUD Requests vs. Business Operations
  • Deleted vs. Archived
Overview

Getting Started

Was this page helpful?
Edit this page
Previous

Integration Example: PSA

Next
Built with

OpenAPI Specification

The complete OpenAPI specification for the awork API is available at: https://api.awork.com/openapi/v1

You can use this specification to explore all available endpoints, request/response schemas, and generate API clients for your preferred programming language.

Request Structure

The awork API is available via HTTPS endpoints and follows a RESTful endpoint structure where resources are selected with text and id segments in the URL. Typically, ids are in Guid format, i.e. a hexadecimal representation of a 128-bit integer separated by hyphens. Other values are usually sent in the body of the request, which are generally accepted in JSON format (content type: application/json).

The URL of our API is composed of three different segments:

  • The base URL: https://api.awork.com/api/v1
  • The content/resource URL: /users
  • The filter query (optional): ?page=1&pageSize=50

The complete URL would then looks like this: https://api.awork.com/api/v1/users?page=1&pageSize=50

CRUD Requests vs. Business Operations

Most API requests contain simple CRUD endpoints to handle the data manipulation for that particular entity. In some cases the default POST, PUT, or DELETE routes are replaced by so-called business operations. This separation is because actions do not only manipulate the entity itself but also affect other entities or even trigger further actions, workflows, or events in other parts of awork. An example of this would be an automatic task creation triggered by the status change of a project.

Business operations can be identified by an additional segment in the URL, which usually begins with a verb. For example:

  • setArchived
  • removeProjectMember
  • renameTag
  • setStatus

Deleted vs. Archived

In some cases, deleting an object can have unintended side effects because of the dependencies of other objects. An example of this is the project type. Once you’ve linked projects to a particular type, it can be complicated to delete the type because you will have to move all projects using that specific type to another type. For these cases, you can set that particular object to archived, which is a form of soft-deletion. Once flagged as archived, it can no longer be used but still exists for the legacy data that it is already linked to.