Reonic Teams API

openapi: 3.1.0
info:
  title: Reonic REST Api v3 Activities Teams API
  description: 'The Reonic REST API v3 provides programmatic access to create and manage resources. The API follows REST principles and returns responses in JSON format. Authentication is required via an API key passed in the X-Authorization header.


    ## Errors


    All endpoints return errors with the same JSON shape:


    ```json

    { "message": "human-readable description" }

    ```


    `400` responses additionally include an `errors` field with per-field validation details.


    The HTTP status code identifies the cause:


    | Status  | Meaning | When |

    |--------|---------|------|

    | `400` | Bad Request | Path params, query string, or request body failed validation. Inspect `errors` for the field-level breakdown. |

    | `401` | Unauthorized | The `X-Authorization` header is missing, malformed, does not match an active API key, or belongs to a different API version. The response never indicates which check failed; check that the key matches the endpoint version. API v3 endpoints require a v3 key with the `rnc_v3_` prefix. |

    | `403` | Forbidden | The API key is read-only and the request targeted a write endpoint (`POST`). Issue a key with write access. |

    | `404` | Not Found | A resource referenced by a path id does not exist or is not visible to your workspace. |

    | `429` | Too Many Requests | The per-client rate limit was exceeded. See **Rate limiting** below. |

    | `500` | Internal Server Error | Unexpected failure. Safe to retry once; if it persists, contact support. |

    | `503` | Service Unavailable | A backing dependency is temporarily unavailable. Retry with exponential backoff. |


    ## Rate limiting


    Limits are shared across all API keys you hold and reset on a 1-minute window. Two buckets:


    | Bucket | Limit | Applies to |

    |--------|-------|------------|

    | `cached` | 500 / min | `GET` requests served from the response cache |

    | `uncached` | 30 / min | Cache misses, `GET` requests sent with `Reonic-Cache-Control: no-cache`, and all `POST` requests |


    Every response includes:


    - `X-RateLimit-Bucket` — `cached` or `uncached`

    - `X-RateLimit-Limit` — the bucket''s ceiling (`500` or `30`)

    - `X-RateLimit-Remaining` — calls left in the current window

    - `X-RateLimit-Reset` — Unix epoch seconds at which the window resets

    - `X-RateLimit-Policy` — `<limit>;w=60`


    `429` responses additionally set `Retry-After` (in seconds). Wait at least that long before retrying.


    ## Caching and Reonic-Cache-Control


    `GET` responses are cached for up to 1 hour. Identical requests (same path and query) on the same API key return the cached result. To force a fresh read, send `Reonic-Cache-Control: no-cache`; the response is then refreshed and re-cached. Forced refreshes count against the `uncached` rate-limit bucket.


    The standard `Cache-Control` header is not honored. Use `Reonic-Cache-Control` to control caching behavior.


    ## Authentication


    Every request must include your API key in the `X-Authorization` header:


    ```

    X-Authorization: <your-api-key>

    ```


    API keys are issued from the Reonic web app and look like `rnc_v3_…`. Send the full value, including the prefix.

    '
  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: Teams
  description: Groups of users. Teams can be assigned to projects and nested under one another.
paths:
  /teams:
    get:
      summary: List teams
      description: 'Lists teams. Use `parentId` for direct children or `ancestorId` for all descendants.


        **Allowed API keys:** Read-only, Read and Write'
      tags:
      - Teams
      parameters:
      - schema:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Only return direct children of this team. Mutually exclusive with `ancestorId`.
        required: false
        description: Only return direct children of this team. Mutually exclusive with `ancestorId`.
        name: parentId
        in: query
      - schema:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Returns all descendants of this team, not just direct children. Mutually exclusive with `parentId`.
        required: false
        description: Returns all descendants of this team, not just direct children. Mutually exclusive with `parentId`.
        name: ancestorId
        in: query
      - schema:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
          maxItems: 50
          description: Filter teams that include any of the specified user IDs as either team members or team leaders.
        required: false
        description: Filter teams that include any of the specified user IDs as either team members or team leaders.
        name: memberIds
        in: query
      - schema:
          type: string
          enum:
          - exclude
          - include
          - only
          default: exclude
          description: 'Controls whether archived teams appear in results. Default: exclude.'
        required: false
        description: 'Controls whether archived teams appear in results. Default: exclude.'
        name: archived
        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: List of all teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
                    description: List of items
                required:
                - data
  /teams/{teamId}:
    get:
      summary: Get team
      description: 'Get a single team by its ID.


        **Allowed API keys:** Read-only, Read and Write'
      tags:
      - Teams
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: teamId
        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: Team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
  /teams/create:
    post:
      summary: Create team
      description: 'Creates a new team.


        **Allowed API keys:** Read and Write'
      tags:
      - Teams
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamCreate'
      responses:
        '201':
          description: The created team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
  /teams/{teamId}/update:
    post:
      summary: Update team
      description: 'Updates a team by its ID.


        **Allowed API keys:** Read and Write'
      tags:
      - Teams
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: teamId
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamUpdate'
      responses:
        '200':
          description: The updated team
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Team'
                required:
                - data
components:
  schemas:
    Team:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        parentId:
          type:
          - string
          - 'null'
          format: uuid
          description: References the parent team by id.
          example: 123e4567-e89b-12d3-a456-426614174000
        leaderIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of users who are leaders of this team. Reference to [**Users**](#tag/users)
          example:
          - 123e4567-e89b-12d3-a456-426614174000
        memberIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of users who are members of this team. Reference to [**Users**](#tag/users)
          example:
          - 123e4567-e89b-12d3-a456-426614174000
        createdAt:
          type: string
          format: date-time
          example: '2026-01-01T15:30:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Last edited date
          example: '2026-01-01T15:30:00.000Z'
        archivedAt:
          type:
          - string
          - 'null'
          format: date-time
          example: '2026-01-01T15:30:00.000Z'
      required:
      - id
      - name
      - description
      - parentId
      - leaderIds
      - memberIds
      - createdAt
      - updatedAt
      - archivedAt
    TeamUpdate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 500
        description:
          type:
          - string
          - 'null'
          maxLength: 5000
        parentId:
          type:
          - string
          - 'null'
          format: uuid
          description: ID of the parent team. Pass `null` to move the team to the root level.
        leaderIds:
          type: array
          items:
            type: string
            format: uuid
          maxItems: 100
          description: Replaces the full set of leaders assigned to the team. Pass `[]` to clear. Reference to [**Users**](#tag/users)
        memberIds:
          type: array
          items:
            type: string
            format: uuid
          maxItems: 100
          description: Replaces the full set of members assigned to the team. Pass `[]` to clear. Reference to [**Users**](#tag/users)
        archived:
          type: boolean
          description: '`true` to archive the team, `false` to unarchive.'
      additionalProperties: false
    TeamCreate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 500
        description:
          type:
          - string
          - 'null'
          maxLength: 5000
        parentId:
          type:
          - string
          - 'null'
          format: uuid
          description: ID of the parent team. If provided, the new team will be created as a child of this team.
        leaderIds:
          type: array
          items:
            type: string
            format: uuid
          maxItems: 100
          description: IDs of users who should be leaders of this team. Reference to [**Users**](#tag/users)
        memberIds:
          type: array
          items:
            type: string
            format: uuid
          maxItems: 100
          description: IDs of users who should be members of this team. Reference to [**Users**](#tag/users)
      required:
      - name
      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