Rhythms labels API

openapi: 3.0.0
info:
  title: Rhythms (params in:body) access_requests labels 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: labels
paths:
  /labels:
    get:
      tags:
      - labels
      operationId: get_labels
      summary: List labels
      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 the labels and label groups available


        This endpoint supports filtering and pagination through query parameters. Available ransackable attributes: uuid, name, parent_uuid, is_group.


        Available ransackable associations and their attributes:

        - parent: parent_uuid, parent_name, parent_parent_uuid, parent_is_group'
    post:
      tags:
      - labels
      operationId: post_labels
      summary: Create a new label
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Label name (unique within tenant)
                    description:
                      type: string
                      default: null
                      description: Label description
                    parent_uuid:
                      type: string
                      default: null
                      description: UUID of parent label (parent must be a group)
                    is_group:
                      type: boolean
                      default: false
                      description: Whether this label is a group (groups cannot have parents)
                    color:
                      type: string
                      default: null
                      description: 'Hex color code (e.g. #eb5757)'
                  additionalProperties: false
                  required:
                  - name
              additionalProperties: false
              required:
              - label
      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 label with the provided attributes. Labels can be regular labels or groups (used for categorization). Admins only. For a label group, set is_group=true and do not set parent_uuid. To add a label to a group, create a new label with parent_uuid set to the group UUID.
  /labels/{id}:
    put:
      tags:
      - labels
      operationId: put_labels_id
      summary: Update a label
      parameters:
      - name: id
        in: path
        required: true
        description: <tenant_uuid>_<label_uuid>
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: object
                  properties:
                    name:
                      type: string
                      default: null
                      description: Label name (unique within tenant)
                    description:
                      type: string
                      default: null
                      description: Label description
                    parent_uuid:
                      type: string
                      default: null
                      description: UUID of parent label group, or blank to move the label to the root
                    color:
                      type: string
                      default: null
                      description: 'Hex color code (e.g. #eb5757), or blank to clear'
                  additionalProperties: false
              additionalProperties: false
              required:
              - label
      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 an existing label or label group with the specified attributes. Admins only. Non-group labels can be moved between groups or back to the root by updating parent_uuid.
    delete:
      tags:
      - labels
      operationId: delete_labels_id
      summary: Delete a label
      parameters:
      - name: id
        in: path
        required: true
        description: Label UUID.
        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: Deletes a label or label group. Deleting a group also deletes its child labels. Admins only.