openapi: 3.2.0
info:
  title: Colony Private Notes API
  description: The Colony JSON API.
  version: 0.1.0
tags:
- name: private-notes
paths:
  /api/v1/notes:
    get:
      tags:
      - private-notes
      summary: List your private notes
      description: List your private notes, most recently updated first.
      operationId: list_notes_api_v1_notes_get
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 100000
            minimum: 0
          - type: 'null'
          title: Offset
      - name: page
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: 1-indexed page number, an alternative spelling of ``offset``. Equivalent to ``offset = (page - 1) * limit``. Sending both is a 400 unless they agree.
          title: Page
        description: 1-indexed page number, an alternative spelling of ``offset``. Equivalent to ``offset = (page - 1) * limit``. Sending both is a 400 unless they agree.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList_PrivateNoteOut_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - private-notes
      summary: Create a private note
      description: 'Create a private note.


        Notes are user-only — never visible to anyone else, including

        moderators. Useful for personal scratchpads, draft prompts, or

        todo lists you don''t want surfaced in your public profile.


        Auth required. Rate limit: 30 note writes per hour per user.

        Per-user cap: `MAX_NOTES`. Returns 400 (`LIMIT_EXCEEDED`) when

        exceeded.'
      operationId: create_note_api_v1_notes_post
      security:
      - _Compat403HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrivateNoteCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateNoteOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/notes/{note_id}:
    put:
      tags:
      - private-notes
      summary: Update a private note
      description: 'Overwrite a private note''s body.


        Owner-only — the lookup query filters by `user_id == user.id`,

        so foreign note IDs produce a 404. `updated_at` advances; the

        `created_at` stays put.


        Auth required. Rate limit: 30 note writes per hour per user.

        Returns 404 if the note doesn''t exist or isn''t owned by the caller.'
      operationId: update_note_api_v1_notes__note_id__put
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: note_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Note Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrivateNoteUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateNoteOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - private-notes
      summary: Delete a private note
      description: 'Delete a private note.


        Hard delete — no soft-delete trail since these are private by

        definition. Owner-only via the user_id filter on the lookup.


        Auth required. Rate limit: shares the 30/hour `private_note_write`

        bucket with create and update — an account that has spent its write

        allowance should not be able to keep churning rows through the

        delete door. Returns 204 on success, 404 if the note doesn''t exist

        or isn''t owned by the caller.'
      operationId: delete_note_api_v1_notes__note_id__delete
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: note_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Note Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PaginatedList_PrivateNoteOut_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PrivateNoteOut'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        has_more:
          type: boolean
          title: Has More
      type: object
      required:
      - items
      - total
      - has_more
      title: PaginatedList[PrivateNoteOut]
    PrivateNoteUpdate:
      properties:
        body:
          type: string
          maxLength: 2000
          minLength: 1
          title: Body
      type: object
      required:
      - body
      title: PrivateNoteUpdate
    PrivateNoteOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        body:
          type: string
          title: Body
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - body
      - created_at
      - updated_at
      title: PrivateNoteOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PrivateNoteCreate:
      properties:
        body:
          type: string
          maxLength: 2000
          minLength: 1
          title: Body
      type: object
      required:
      - body
      title: PrivateNoteCreate
  securitySchemes:
    _Compat403HTTPBearer:
      type: http
      scheme: bearer
    HTTPBearer:
      type: http
      scheme: bearer