Rhythms Time Periods API

openapi: 3.2.0
info:
  title: Rhythms (params in:body) Time Periods API
  description: '# RhythmsAI API


    The RhythmsAI API provides a comprehensive platform for team productivity, goal tracking, and workflow automation.'
  version: '1.0'
  x-copyright: null
servers:
- url: https://api.rhythms.ai
security: []
tags:
- name: Time Periods
paths:
  /okrs/time_periods:
    get:
      tags:
      - Time Periods
      operationId: get_okrs_time_periods
      summary: List all time periods
      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 time periods for the current tenant.


        Time periods are automatically ordered with active periods appearing first,

        followed by other periods in chronological order. Active time periods are

        determined by the current tenant''s OKR cycle settings.


        This endpoint supports filtering and pagination through query parameters. Available ransackable attributes: uuid, name.'
  /okrs/time_periods/{id}:
    put:
      tags:
      - Time Periods
      operationId: put_okrs_time_periods_id
      summary: Update a time period
      parameters:
      - name: id
        in: path
        required: true
        description: Time period UUID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                time_period:
                  type: object
                  properties:
                    name:
                      type: string
                      default: null
                      description: Name of the time period
                    start_date:
                      type: string
                      default: null
                      description: Start date of the time period (YYYY-MM-DD)
                    end_date:
                      type: string
                      default: null
                      description: End date of the time period (YYYY-MM-DD)
                    parent_uuid:
                      type: string
                      default: null
                      description: UUID of parent time period for hierarchical periods
                  additionalProperties: false
              additionalProperties: false
              required:
              - time_period
      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 time period with the specified attributes.


        Time periods help you organize your OKRs into different blocks of time.

        Optionally, you can update the parent-child relationship between time periods

        to form a hierarchy.'
    delete:
      tags:
      - Time Periods
      operationId: delete_okrs_time_periods_id
      summary: Delete a time period
      parameters:
      - name: id
        in: path
        required: true
        description: Time period 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 time period.


        A time period cannot be deleted if it is the last remaining time period,

        or if it has associated objectives, key results, or initiatives.'