Rhythms documents API

openapi: 3.0.0
info:
  title: Rhythms (params in:body) access_requests documents 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: documents
paths:
  /documents:
    get:
      tags:
      - documents
      operationId: get_documents
      summary: List documents
      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: explicitly_shared
        in: query
        description: Filter to show only explicitly shared documents
        schema:
          type: boolean
      - 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 documents for the current tenant.



        This endpoint supports filtering and pagination through query parameters. Available ransackable attributes: uuid, name, view_uuid, name, creator_uuid, layout_uuid, playbook_uuid, status, content_type, created_at, updated_at.'
    post:
      tags:
      - documents
      operationId: post_documents
      summary: Create a new document
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Document name
                content_type:
                  type: string
                  description: 'Type of document to create: ''document'' (default) or ''layout'''
                layout_uuid:
                  type: string
                  description: UUID of an existing layout to base this document on
                playbook_uuid:
                  type: string
                  description: UUID of the playbook this document was created for
                playbook_run_uuid:
                  type: string
                  description: UUID of the playbook run this document was created during
              additionalProperties: false
              required:
              - name
      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 document or layout. Optionally base it on an existing layout.
  /documents/{uuid}:
    get:
      tags:
      - documents
      operationId: get_documents_uuid
      summary: Get a specific document
      parameters:
      - name: uuid
        in: path
        required: true
        description: <tenant_uuid>_<document_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: Retrieves a document with content fetched from Tiptap collaboration server. Falls back to database content if Tiptap is unavailable.
    put:
      tags:
      - documents
      operationId: put_documents_uuid
      summary: Update document properties
      parameters:
      - name: uuid
        in: path
        required: true
        description: <tenant_uuid>_<document_uuid>
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Document name
                instructions:
                  type: string
                  description: Instructions content for the document. Changing this triggers content regeneration.
                status:
                  type: string
                  description: 'Document status: ''completed'', ''draft'', ''published'', or ''archived''.'
                content_type:
                  type: string
                  description: 'Document type: ''document'' or ''layout'''
                layout_uuid:
                  type: string
                  description: Simple UUID of the layout to associate with this document
              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: 'Update document properties including status, name, instructions, and layout association.


        Use this endpoint to:

        - Update the document name

        - Update instructions

        - Change the document status (completed, draft, published, archived)

        - Associate the document with a layout (e.g., after saving a new layout from a custom document)


        At least one parameter (name, instructions, status, or layout_uuid) must be provided.

        '
  /documents/{uuid}/activities:
    get:
      tags:
      - documents
      operationId: get_documents_uuid_activities
      summary: List a document's smart activity log
      parameters:
      - name: uuid
        in: path
        required: true
        description: <tenant_uuid>_<document_uuid>
        schema:
          type: string
      - name: limit
        in: query
        description: Max entries per page (default 100, newest first)
        schema:
          type: number
      - name: page
        in: query
        description: Page number (1-based) for older entries
        schema:
          type: number
      - name: since
        in: query
        description: ISO-8601 timestamp; only entries at or after this time are returned
        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: Returns the grouped change/refresh activity entries for a document, newest first. Paginated via `limit`/`page` (default 100 newest); pass `since` (ISO-8601) to scope to recent activity (e.g. 'what changed in the last few days').
  /documents/{uuid}/refresh:
    post:
      tags:
      - documents
      operationId: post_documents_uuid_refresh
      summary: Trigger an on-demand refresh of a document
      parameters:
      - name: uuid
        in: path
        required: true
        description: <tenant_uuid>_<document_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: 'Triggers an on-demand refresh of the target document. Opens an ephemeral

        Chat::Thread, posts a refresh prompt, and kicks off the universal chat

        agent which invokes the `document_refresh` skill. Returns immediately

        with a `thread_uuid` tracking handle; callers poll the thread or re-read

        the document to see the refresh outcome.

        '