Reonic Tasks API

openapi: 3.2.0
info:
  title: Reonic REST Api v3 Tasks API
  description: The Reonic REST API v3 provides programmatic access to create and manage resources.
  version: 3.2.0
  contact:
    email: kontakt@reonic.de
    url: https://reonic.com
    name: Reonic GmbH
servers:
- url: '{apiBaseUrl}/rest/v3/'
security:
- X-Authorization: []
tags:
- name: Tasks
  description: 'To-do items attached to a project or contact, with due dates, assignees, and completion state.


    > [!warning]

    > **Beta:** These endpoints are in beta and may change as the service evolves. Please report issues or unexpected behavior to our team.'
  x-displayName: Tasks (BETA)
paths:
  /tasks/tags:
    get:
      description: 'Get task tags


        **Allowed API keys:** Read-only, Read and Write'
      summary: Get task tags
      tags:
      - Tasks
      x-badges:
      - name: BETA
        position: before
        color: '#ea580c'
      parameters:
      - schema:
          type: string
          example: no-cache
        required: false
        name: Reonic-Cache-Control
        in: header
        description: Set to 'no-cache' to bypass the 1-hour response cache and force a fresh read. The fresh response is then written back to the cache for subsequent callers. Forced refreshes count against the uncached rate-limit bucket (30/min); only cache hits count against the cached bucket (500/min).
      responses:
        '200':
          description: Task tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          example: 123e4567-e89b-12d3-a456-426614174000
                        name:
                          type: string
                        position:
                          type: number
                        textColor:
                          type: string
                        backgroundColor:
                          type: string
                      required:
                      - id
                      - name
                      - position
                      - textColor
                      - backgroundColor
                    description: List of items
                required:
                - data
      operationId: getTasksTags
      x-operation-id-source: derived
  /tasks/count:
    get:
      description: 'Get task counts and stats for a parent entity


        **Allowed API keys:** Read-only, Read and Write'
      summary: Get task counts
      tags:
      - Tasks
      x-badges:
      - name: BETA
        position: before
        color: '#ea580c'
      parameters:
      - schema:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        required: true
        name: parentId
        in: query
      - schema:
          type: string
          enum:
          - contact
          - user
          - residentialProject
          - commercialProject
          description: The type of the parent entity.
          example: residentialProject
        required: true
        description: The type of the parent entity.
        name: parentType
        in: query
      - schema:
          type: string
          example: no-cache
        required: false
        name: Reonic-Cache-Control
        in: header
        description: Set to 'no-cache' to bypass the 1-hour response cache and force a fresh read. The fresh response is then written back to the cache for subsequent callers. Forced refreshes count against the uncached rate-limit bucket (30/min); only cache hits count against the cached bucket (500/min).
      responses:
        '200':
          description: Task counts for the parent entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  outstandingTasks:
                    type: number
                  completedTasks:
                    type: number
                  totalTasks:
                    type: number
                  overdueTasks:
                    type: number
                  nextDueDate:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    example: '2026-01-01T15:30:00.000Z'
                  nextDueDateIsToday:
                    type: boolean
                required:
                - outstandingTasks
                - completedTasks
                - totalTasks
                - overdueTasks
                - nextDueDate
      operationId: getTasksCount
      x-operation-id-source: derived
  /tasks:
    get:
      description: 'List tasks with filters and pagination. `parentId` and `parentType` must be provided together (or omitted together).


        **Examples:**

        - Open tasks for a residential project: `GET /tasks?parentId=&parentType=residentialProject&completed=false&orderBy=dueAt&sort=asc`

        - All tasks due this week: `GET /tasks?dueFrom=2026-04-27T00:00:00Z&dueTo=2026-05-04T00:00:00Z&completed=false`

        - Tasks assigned to specific users: `GET /tasks?userIds=&userIds=&completed=false`


        **Allowed API keys:** Read-only, Read and Write'
      summary: List tasks
      tags:
      - Tasks
      x-badges:
      - name: BETA
        position: before
        color: '#ea580c'
      parameters:
      - schema:
          type: string
          format: uuid
        required: false
        name: parentId
        in: query
      - schema:
          type: string
          enum:
          - contact
          - user
          - residentialProject
          - commercialProject
          description: The type of the parent entity.
          example: residentialProject
        required: false
        description: The type of the parent entity.
        name: parentType
        in: query
      - schema:
          type: string
          maxLength: 100
        required: false
        name: search
        in: query
      - schema:
          type: string
          format: date-time
          example: '2026-01-01T15:30:00.000Z'
        required: false
        name: dueFrom
        in: query
      - schema:
          type: string
          format: date-time
          example: '2026-01-01T15:30:00.000Z'
        required: false
        name: dueTo
        in: query
      - schema:
          type: string
          format: date-time
          example: '2026-01-01T15:30:00.000Z'
        required: false
        name: completedFrom
        in: query
      - schema:
          type: string
          format: date-time
          example: '2026-01-01T15:30:00.000Z'
        required: false
        name: completedTo
        in: query
      - schema:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
          maxItems: 50
          description: Comma-separated list or repeated query param.
        required: false
        description: Comma-separated list or repeated query param.
        name: userIds
        in: query
      - schema:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
          maxItems: 50
          description: Comma-separated list or repeated query param.
        required: false
        description: Comma-separated list or repeated query param.
        name: teamIds
        in: query
      - schema:
          type:
          - boolean
          - 'null'
        required: false
        name: completed
        in: query
      - schema:
          type: string
          enum:
          - title
          - dueAt
        required: false
        name: orderBy
        in: query
      - schema:
          type: string
          enum:
          - asc
          - desc
        required: false
        name: sort
        in: query
      - schema:
          type: integer
          minimum: 1
          default: 1
          description: 'Page number, starting from 1. Default: 1.'
        required: false
        description: 'Page number, starting from 1. Default: 1.'
        name: page
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
          description: 'Number of items per page. Default: 50. Max: 200.'
        required: false
        description: 'Number of items per page. Default: 50. Max: 200.'
        name: itemsPerPage
        in: query
      - schema:
          type: string
          example: no-cache
        required: false
        name: Reonic-Cache-Control
        in: header
        description: Set to 'no-cache' to bypass the 1-hour response cache and force a fresh read. The fresh response is then written back to the cache for subsequent callers. Forced refreshes count against the uncached rate-limit bucket (30/min); only cache hits count against the cached bucket (500/min).
      responses:
        '200':
          description: Paginated tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                        minimum: 1
                        description: Current page number
                      perPage:
                        type: integer
                        minimum: 1
                        description: Number of items per page
                      total:
                        type: integer
                        minimum: 0
                        description: Total number of items across all pages
                      totalPages:
                        type: integer
                        minimum: 1
                      next:
                        type:
                        - string
                        - 'null'
                        description: Path to the next page, or null if there is no next page
                      prev:
                        type:
                        - string
                        - 'null'
                        description: Path to the previous page, or null if there is no previous page
                    required:
                    - page
                    - perPage
                    - total
                    - totalPages
                    - next
                    - prev
                required:
                - data
                - pagination
      operationId: getTasks
      x-operation-id-source: derived
  /tasks/create:
    post:
      description: 'Create a task


        **Allowed API keys:** Read and Write'
      summary: Create task
      tags:
      - Tasks
      x-badges:
      - name: BETA
        position: before
        color: '#ea580c'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  example: 123e4567-e89b-12d3-a456-426614174000
                  description: Optional client-generated UUID for optimistic updates. If omitted, the server assigns one.
                parentId:
                  type: string
                  format: uuid
                  example: 123e4567-e89b-12d3-a456-426614174000
                parentType:
                  type: string
                  enum:
                  - contact
                  - user
                  - residentialProject
                  - commercialProject
                  description: The type of the parent entity.
                  example: residentialProject
                commercialProjectInput:
                  type: object
                  properties:
                    laneId:
                      type: string
                      format: uuid
                      example: 123e4567-e89b-12d3-a456-426614174000
                  required:
                  - laneId
                  additionalProperties: false
                title:
                  type: string
                  minLength: 1
                  maxLength: 500
                description:
                  type: string
                  maxLength: 20000
                assignedUserIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  maxItems: 50
                assignedTeamIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  maxItems: 50
                tagIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  maxItems: 50
                dueAt:
                  type:
                  - string
                  - 'null'
                  format: date-time
                  example: '2026-01-01T15:30:00.000Z'
                checklistItems:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        example: 123e4567-e89b-12d3-a456-426614174000
                      position:
                        type: integer
                        minimum: 0
                        maximum: 10000
                      text:
                        type: string
                        minLength: 1
                        maxLength: 500
                      checked:
                        type: boolean
                        default: false
                    required:
                    - id
                    - position
                    - text
                    additionalProperties: false
                  maxItems: 200
              required:
              - parentId
              - parentType
              additionalProperties: false
      responses:
        '201':
          description: The created task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
      operationId: postTasksCreate
      x-operation-id-source: derived
  /tasks/{taskId}:
    get:
      description: 'Get a single task by its ID


        **Allowed API keys:** Read-only, Read and Write'
      summary: Get task
      tags:
      - Tasks
      x-badges:
      - name: BETA
        position: before
        color: '#ea580c'
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: taskId
        in: path
      - schema:
          type: string
          example: no-cache
        required: false
        name: Reonic-Cache-Control
        in: header
        description: Set to 'no-cache' to bypass the 1-hour response cache and force a fresh read. The fresh response is then written back to the cache for subsequent callers. Forced refreshes count against the uncached rate-limit bucket (30/min); only cache hits count against the cached bucket (500/min).
      responses:
        '200':
          description: The task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
      operationId: getTasksByTaskId
      x-operation-id-source: derived
  /tasks/{taskId}/update:
    post:
      description: 'Update a task


        **Allowed API keys:** Read and Write'
      summary: Update task
      tags:
      - Tasks
      x-badges:
      - name: BETA
        position: before
        color: '#ea580c'
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: taskId
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 500
                description:
                  type: string
                  maxLength: 20000
                assignedUserIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  maxItems: 50
                assignedTeamIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  maxItems: 50
                tagIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  maxItems: 50
                dueAt:
                  type:
                  - string
                  - 'null'
                  format: date-time
                  example: '2026-01-01T15:30:00.000Z'
                sendReminderAt:
                  type:
                  - string
                  - 'null'
                  format: date-time
                  example: '2026-01-01T15:30:00.000Z'
                checklistItems:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        example: 123e4567-e89b-12d3-a456-426614174000
                      position:
                        type: integer
                        minimum: 0
                        maximum: 10000
                      text:
                        type: string
                        minLength: 1
                        maxLength: 500
                      checked:
                        type: boolean
                        default: false
                    required:
                    - id
                    - position
                    - text
                    additionalProperties: false
              additionalProperties: false
      responses:
        '200':
          description: The updated task
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Task'
                required:
                - data
      operationId: postTasksByTaskIdUpdate
      x-operation-id-source: derived
  /tasks/{taskId}/complete:
    post:
      description: 'Complete a task


        **Allowed API keys:** Read and Write'
      summary: Complete task
      tags:
      - Tasks
      x-badges:
      - name: BETA
        position: before
        color: '#ea580c'
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: taskId
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type:
              - object
              - 'null'
              properties:
                note:
                  type:
                  - string
                  - 'null'
                  maxLength: 2000
              additionalProperties: false
      responses:
        '200':
          description: The completed task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
      operationId: postTasksByTaskIdComplete
      x-operation-id-source: derived
  /tasks/{taskId}/uncomplete:
    post:
      description: 'Uncomplete a task


        **Allowed API keys:** Read and Write'
      summary: Uncomplete task
      tags:
      - Tasks
      x-badges:
      - name: BETA
        position: before
        color: '#ea580c'
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: taskId
        in: path
      responses:
        '200':
          description: The uncompleted task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
      operationId: postTasksByTaskIdUncomplete
      x-operation-id-source: derived
  /tasks/{taskId}/delete:
    post:
      description: 'Delete a task


        **Allowed API keys:** Read and Write'
      summary: Delete task
      tags:
      - Tasks
      x-badges:
      - name: BETA
        position: before
        color: '#ea580c'
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: taskId
        in: path
      responses:
        '200':
          description: Delete result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        example: 123e4567-e89b-12d3-a456-426614174000
                    required:
                    - id
                required:
                - data
      operationId: postTasksByTaskIdDelete
      x-operation-id-source: derived
components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        title:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        dueAt:
          type:
          - string
          - 'null'
          format: date-time
          example: '2026-01-01T15:30:00.000Z'
        sendReminderAt:
          type:
          - string
          - 'null'
          format: date-time
          example: '2026-01-01T15:30:00.000Z'
        checklist:
          type: object
          properties:
            started:
              type: boolean
            completed:
              type: boolean
            nrOfCompletedItems:
              type: number
            nrOfItems:
              type: number
            items:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 123e4567-e89b-12d3-a456-426614174000
                  checkedAt:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    example: '2026-01-01T15:30:00.000Z'
                  checked:
                    type: boolean
                  position:
                    type: number
                  text:
                    type: string
                required:
                - id
                - checkedAt
                - checked
                - position
                - text
          required:
          - started
          - completed
          - nrOfCompletedItems
          - nrOfItems
          - items
          additionalProperties: false
        completed:
          type: boolean
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
          example: '2026-01-01T15:30:00.000Z'
        completedNote:
          type:
          - string
          - 'null'
        completedById:
          type:
          - string
          - 'null'
          format: uuid
        assignedUserIds:
          type: array
          items:
            type: string
            format: uuid
        assignedTeamIds:
          type: array
          items:
            type: string
            format: uuid
        tagIds:
          type: array
          items:
            type: string
            format: uuid
        parent:
          type: object
          properties:
            parentId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            parentType:
              type: string
              enum:
              - contact
              - user
              - residentialProject
              - commercialProject
              description: The type of the parent entity.
              example: residentialProject
            parentName:
              type: string
            parentObjectLink:
              type:
              - string
              - 'null'
          required:
          - parentId
          - parentType
          - parentName
          additionalProperties: false
        stageAndLane:
          type:
          - object
          - 'null'
          properties:
            laneId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            lanePosition:
              type: number
            lane:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  example: 123e4567-e89b-12d3-a456-426614174000
                name:
                  type: string
                position:
                  type: number
                archivedAt:
                  type:
                  - string
                  - 'null'
                  format: date-time
                  example: '2026-01-01T15:30:00.000Z'
              required:
              - id
              - name
              - position
              - archivedAt
          required:
          - laneId
          - lanePosition
          - lane
          additionalProperties: false
      required:
      - id
      - completed
      - assignedUserIds
      - assignedTeamIds
      - tagIds
      additionalProperties: false
  securitySchemes:
    X-Authorization:
      type: apiKey
      in: header
      name: X-Authorization
x-tagGroups:
- name: People
  tags:
  - Contacts
  - Users
  - Teams
- name: Projects
  tags:
  - Residential Projects
  - Commercial Projects
- name: Working on a project
  tags:
  - Notes
  - Tasks
  - Files
  - File Folders
  - Activities
  - Time Tracking
  - Checklists
  - Checklist Templates
  - Signature Requests
- name: Calendar
  tags:
  - Calendars
  - Calendar Categories
  - Appointments
- name: Catalog
  tags:
  - Components
  - Planning Templates
  - Planning Packages
  - Offer Templates
- name: Workspace setup
  tags:
  - Kanban Boards
  - Kanban Columns
  - Tags
  - Lead Sources
- name: Wiki
  tags:
  - Wiki
- name: Services
  tags:
  - Photogrammetry
- name: API helpers
  tags:
  - Upload
  - Links
- name: Integrations
  tags:
  - Webhooks
- name: Guides
  tags:
  - Migrating from API v2 to v3
  - Changelog