Rhythms teams API

openapi: 3.0.0
info:
  title: Rhythms (params in:body) access_requests teams API
  description: '

    <p># RhythmsAI API</p>


    <p>The RhythmsAI API provides a comprehensive platform for team productivity, goal tracking, and workflow automation. Built with multi-tenant architecture, it enables organizations to manage objectives, track progress, and integrate with popular productivity tools.</p>


    <p>## API Structure</p>

    <ul><li>

    <p>**RESTful Design**: Clean, predictable REST endpoints following industry standards</p>

    </li><li>

    <p><strong>Multi-tenant</strong>: All data is automatically scoped to your organization’s tenant</p>

    </li><li>

    <p><strong>Authentication</strong>: Secure authentication with proper authorization controls</p>

    </li><li>

    <p><strong>Pagination</strong>: Efficient data retrieval with built-in pagination support</p>

    </li><li>

    <p><strong>Filtering</strong>: Advanced filtering capabilities using Ransack query DSL</p>

    </li></ul>


    <p>## Getting Started</p>


    <p>All API endpoints require authentication. Once authenticated, your requests will be automatically scoped to your organization’s data. The API supports JSON request/response format and follows standard HTTP status codes for success and error handling.</p>


    <p>For integration support and detailed examples, refer to the specific endpoint documentation below.</p>

    '
  version: '1.0'
  x-copyright: null
servers:
- url: https://api.rhythms.ai
security: []
tags:
- name: teams
paths:
  /teams:
    get:
      tags:
      - teams
      operationId: get_teams
      summary: List teams and include current owners
      parameters:
      - name: page
        in: query
        description: 'Page number for pagination (default: 1)'
        schema:
          type: number
          default: 1
      - name: per_page
        in: query
        description: 'Number of records per page (default: 20, max: 100)'
        schema:
          type: number
          default: 20
      - name: limit
        in: query
        description: Alias for per_page - number of records per page
        schema:
          type: number
          default: 20
      - name: limit_max
        in: query
        description: Maximum number of records per page (overrides limit if not set)
        schema:
          type: number
          default: null
      - name: count
        in: query
        description: Set to 'true' to include total count in pagy metadata (data.pagy.count). Use for count/total queries instead of paginating through all pages.
        schema:
          type: string
      - name: q
        in: query
        description: 'Ransack query parameters for filtering. In query strings, use bracket notation: q[name_cont]=john&q[status_eq]=active&q[s]=name+asc. Keys are attribute names with predicates: _cont (contains), _eq (equals), _in (array membership), _gteq (>=), _lteq (<=), _present (not null), _null (is null). The "s" key sorts results (e.g., q[s]=created_at+desc). Example query string: ?q[name_cont]=john&q[s]=name+asc filters names containing "john" sorted by name ascending.'
        required: false
        schema:
          type: object
          additionalProperties: true
      responses:
        '400':
          description: Bad Request - Invalid parameters or malformed request
        '401':
          description: Unauthorized - Invalid or missing authentication
        '403':
          description: Forbidden - User lacks permission to access this resource
        '404':
          description: Not Found - Resource does not exist
        '422':
          description: Unprocessable Entity - Invalid request parameters or validation errors
        '429':
          description: Too Many Requests - Rate limit exceeded
        '500':
          description: Internal Server Error - Unexpected server error
      description: 'Retrieves all teams. Use this to identify the correct team first; the serialized team data includes current owners. Combine this with the members endpoint when you need the full team roster.


        This endpoint supports filtering and pagination through query parameters. Available ransackable attributes: uuid, display_name, parent_uuid, status, display_name, is_org, parent_uuid, depth.


        Available ransackable associations and their attributes:

        - team_memberships: team_memberships_uuid, team_memberships_user_uuid'
    post:
      tags:
      - teams
      operationId: post_teams
      summary: Create a new team
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                team:
                  type: object
                  properties:
                    display_name:
                      type: string
                      description: Team display name
                    description:
                      type: string
                      default: null
                      description: Team description
                    parent_uuid:
                      type: string
                      default: null
                      description: Parent team UUID
                    owner_uuids:
                      type: array
                      items:
                        type: string
                      default: []
                      description: Array of user UUIDs to be team owners in the format ["uuid-1", "uuid-2"]
                    member_uuids:
                      type: array
                      items:
                        type: string
                      default: []
                      description: Array of user UUIDs to be team members in the format ["uuid-1", "uuid-2"]
                  additionalProperties: false
                  required:
                  - display_name
              additionalProperties: false
      responses:
        '400':
          description: Bad Request - Invalid parameters or malformed request
        '401':
          description: Unauthorized - Invalid or missing authentication
        '403':
          description: Forbidden - User lacks permission to access this resource
        '404':
          description: Not Found - Resource does not exist
        '422':
          description: Unprocessable Entity - Invalid request parameters or validation errors
        '429':
          description: Too Many Requests - Rate limit exceeded
        '500':
          description: Internal Server Error - Unexpected server error
      description: Creates a new team with the specified attributes, owners, and members
  /teams/{id}:
    put:
      tags:
      - teams
      operationId: put_teams_id
      summary: Update a team
      parameters:
      - name: id
        in: path
        required: true
        description: Team UUID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                team:
                  type: object
                  properties:
                    display_name:
                      type: string
                      default: null
                      description: Team display name
                    description:
                      type: string
                      default: null
                      description: Team description
                    parent_uuid:
                      type: string
                      default: null
                      description: Parent team UUID
                    status:
                      type: string
                      enum:
                      - active
                      - archived
                      default: null
                      description: Team status (active or archived)
                    owner_uuids:
                      type: array
                      items:
                        type: string
                      default: []
                      description: Complete list of user UUIDs to be team owners. REPLACES all existing owners - include ALL owners you want to keep.
                  additionalProperties: false
              additionalProperties: false
              required:
              - team
      responses:
        '400':
          description: Bad Request - Invalid parameters or malformed request
        '401':
          description: Unauthorized - Invalid or missing authentication
        '403':
          description: Forbidden - User lacks permission to access this resource
        '404':
          description: Not Found - Resource does not exist
        '422':
          description: Unprocessable Entity - Invalid request parameters or validation errors
        '429':
          description: Too Many Requests - Rate limit exceeded
        '500':
          description: Internal Server Error - Unexpected server error
      description: 'Updates team attributes and manages team owners.


        OWNER MANAGEMENT:

        - Pass owner_uuids to set the complete list of team owners

        - Users in the array become owners, users not in the array are removed as owners

        - To add an owner: include all existing owners plus the new one

        - To remove an owner: include all owners except the one to remove

        '
  /teams/{id}/add_members:
    put:
      tags:
      - teams
      operationId: put_teams_id_add_members
      summary: Add members to a team
      parameters:
      - name: id
        in: path
        required: true
        description: Team UUID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                member_uuids:
                  type: array
                  items:
                    type: string
                  description: Array of user UUIDs to add as members
              additionalProperties: false
              required:
              - member_uuids
      responses:
        '400':
          description: Bad Request - Invalid parameters or malformed request
        '401':
          description: Unauthorized - Invalid or missing authentication
        '403':
          description: Forbidden - User lacks permission to access this resource
        '404':
          description: Not Found - Resource does not exist
        '422':
          description: Unprocessable Entity - Invalid request parameters or validation errors
        '429':
          description: Too Many Requests - Rate limit exceeded
        '500':
          description: Internal Server Error - Unexpected server error
      description: Adds users as members to the team. Existing members are preserved. Use this for adding members without needing the full member list.
  /teams/{id}/remove_member/{member_uuid}:
    delete:
      tags:
      - teams
      operationId: delete_teams_id_remove_member_member_uuid
      summary: Remove one person from a team
      parameters:
      - name: id
        in: path
        required: true
        description: Team UUID
        schema:
          type: string
      - name: member_uuid
        in: path
        required: true
        description: UUID of member to remove
        schema:
          type: string
      responses:
        '400':
          description: Bad Request - Invalid parameters or malformed request
        '401':
          description: Unauthorized - Invalid or missing authentication
        '403':
          description: Forbidden - User lacks permission to access this resource
        '404':
          description: Not Found - Resource does not exist
        '422':
          description: Unprocessable Entity - Invalid request parameters or validation errors
        '429':
          description: Too Many Requests - Rate limit exceeded
        '500':
          description: Internal Server Error - Unexpected server error
      description: 'Removes a single person from the team.


        Use this for one-off removals without sending the full member list.

        For bulk removals, call this endpoint once per person.

        This endpoint can remove both regular members and owners.

        '
  /teams/{id}/owners:
    get:
      tags:
      - teams
      operationId: get_teams_id_owners
      summary: Get team owners only
      parameters:
      - name: id
        in: path
        required: true
        description: Team UUID
        schema:
          type: string
      - name: page
        in: query
        description: Page number
        schema:
          type: number
      - name: limit
        in: query
        description: Items per page
        schema:
          type: number
      responses:
        '200':
          description: ok
      description: 'Returns team owners with their UUIDs, names, and emails.


        This endpoint only returns owners.

        Combine it with the members endpoint when you need the full team roster

        or when the user asks to remove everyone including owners.

        '
  /teams/{id}/members:
    get:
      tags:
      - teams
      operationId: get_teams_id_members
      summary: Get regular team members only
      parameters:
      - name: id
        in: path
        required: true
        description: Team UUID
        schema:
          type: string
      - name: page
        in: query
        description: Page number
        schema:
          type: number
      - name: limit
        in: query
        description: Items per page
        schema:
          type: number
      responses:
        '200':
          description: ok
      description: 'Returns regular team members with their UUIDs, names, and emails.


        Owners are intentionally excluded from this response.

        Combine this endpoint with the team or owners endpoint when the user asks

        who is on the team or when you need the full team roster.

        '