Caliu Notes API

openapi: 3.2.0
info:
  title: Caliu Notes API
  version: 1.0.0
  description: 'API-first notes app. Access your notes programmatically using an API key.


    Create an API key in the app settings, then pass it as `Authorization: Bearer caliu_xxx` header.'
  contact:
    name: Caliu
    url: https://caliuapp.com
servers:
- url: https://api.caliuapp.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Notes
paths:
  /notes:
    get:
      tags:
      - Notes
      summary: List notes
      description: List notes with pagination, search, and filtering. Use `since` for incremental sync.
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Full-text search query
        required: false
        description: Full-text search query
        name: q
        in: query
      - schema:
          type: string
          description: Filter by tag ID
        required: false
        description: Filter by tag ID
        name: tag
        in: query
      - schema:
          type: string
          description: Show only pinned notes
        required: false
        description: Show only pinned notes
        name: pinned
        in: query
      - schema:
          type: string
          description: Show only untagged notes
        required: false
        description: Show only untagged notes
        name: untagged
        in: query
      - schema:
          type: string
          description: ISO timestamp for incremental sync
        required: false
        description: ISO timestamp for incremental sync
        name: since
        in: query
      - schema:
          type: string
          description: Max notes to return (1-200, default 50)
        required: false
        description: Max notes to return (1-200, default 50)
        name: limit
        in: query
      - schema:
          type: string
          description: Cursor for keyset pagination
        required: false
        description: Cursor for keyset pagination
        name: cursor
        in: query
      responses:
        '200':
          description: List of notes
          content:
            application/json:
              schema:
                type: object
                properties:
                  notes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Note'
                  nextCursor:
                    type: string
                    nullable: true
                required:
                - notes
                - nextCursor
        '400':
          description: Search query too long
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: getNotes
      x-operation-id-source: derived
    post:
      tags:
      - Notes
      summary: Create note
      description: Create a new note. Accepts optional `id` for offline-created notes.
      security:
      - bearerAuth: []
      - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Client-provided ID for offline-created notes
                content:
                  type: string
                  description: Note content in markdown. Title is derived from the first line.
                is_pinned:
                  type: boolean
                tags:
                  type: array
                  items:
                    type: string
                  description: Tag IDs to associate. When provided, hashtag auto-extraction is skipped.
                auto_sync_tags:
                  type: boolean
                  description: 'Opt-in: extract #hashtags (including multi-word `#like this#`) from content and link tags server-side. Default false for backward compatibility.'
                auto_link_notes:
                  type: boolean
                  description: 'Opt-in: resolve bare [[Note Title]] wiki links against your existing notes and rewrite them to the canonical [[id|Title]] form. Unresolved titles are left as-is. Default false for backward compatibility.'
      responses:
        '201':
          description: Note created
          content:
            application/json:
              schema:
                type: object
                properties:
                  note:
                    $ref: '#/components/schemas/Note'
                required:
                - note
        '409':
          description: Note id already in use
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: postNotes
      x-operation-id-source: derived
  /notes/import:
    post:
      tags:
      - Notes
      summary: Import notes
      description: Bulk import notes from .md, .markdown, .txt, .zip, .bear2bk, .textpack, or .json files. Max 500 notes.
      security:
      - bearerAuth: []
      - cookieAuth: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  nullable: true
      responses:
        '200':
          description: Import results
          content:
            application/json:
              schema:
                type: object
                properties:
                  imported:
                    type: number
                  skipped:
                    type: number
                  warnings:
                    type: array
                    items:
                      type: string
                  source:
                    type: string
                required:
                - imported
                - skipped
                - warnings
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: postNotesImport
      x-operation-id-source: derived
  /notes/trash:
    get:
      tags:
      - Notes
      summary: List trashed notes
      security:
      - bearerAuth: []
      - cookieAuth: []
      responses:
        '200':
          description: Soft-deleted notes
          content:
            application/json:
              schema:
                type: object
                properties:
                  notes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Note'
                required:
                - notes
      operationId: getNotesTrash
      x-operation-id-source: derived
    delete:
      tags:
      - Notes
      summary: Empty trash
      description: Permanently delete all soft-deleted notes.
      security:
      - bearerAuth: []
      - cookieAuth: []
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
      operationId: deleteNotesTrash
      x-operation-id-source: derived
  /notes/archive:
    get:
      tags:
      - Notes
      summary: List archived notes
      description: List archived notes (most-recently-archived first, capped at 100). Archived notes are hidden from all other listings but never auto-removed. Keyset pagination is a planned follow-up; mirrors GET /notes/trash today.
      security:
      - bearerAuth: []
      - cookieAuth: []
      responses:
        '200':
          description: Archived notes
          content:
            application/json:
              schema:
                type: object
                properties:
                  notes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Note'
                required:
                - notes
      operationId: getNotesArchive
      x-operation-id-source: derived
  /notes/{id}:
    get:
      tags:
      - Notes
      summary: Get note
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      responses:
        '200':
          description: Note details
          content:
            application/json:
              schema:
                type: object
                properties:
                  note:
                    $ref: '#/components/schemas/Note'
                required:
                - note
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: getNotesById
      x-operation-id-source: derived
    put:
      tags:
      - Notes
      summary: Update note
      description: Update a note. Supports optimistic concurrency via `expected_updated_at`.
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: Note content in markdown. Title is derived from the first line.
                is_pinned:
                  type: boolean
                expected_updated_at:
                  type: string
                  description: For optimistic concurrency — rejected if server version is newer
                base_rev:
                  type: integer
                  minimum: 0
                  description: The `rev` of the note your content was edited from. With it, edits made since are kept and merged instead of answering 409.
                auto_sync_tags:
                  type: boolean
                  description: 'Opt-in: when content is provided, extract #hashtags and replace the note''s tags. Default false for backward compatibility — existing clients managing tags via /tags endpoints are unaffected.'
                auto_link_notes:
                  type: boolean
                  description: 'Opt-in: when content is provided, resolve bare [[Note Title]] wiki links against your existing notes and rewrite them to the canonical [[id|Title]] form. Unresolved titles are left as-is. Default false for backward compatibility.'
      responses:
        '200':
          description: Note updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  note:
                    $ref: '#/components/schemas/Note'
                required:
                - note
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '409':
          description: Conflict — note modified by another client
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  note:
                    $ref: '#/components/schemas/Note'
                required:
                - error
                - note
        '413':
          description: Content above 1,000,000 UTF-8 bytes
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: putNotesById
      x-operation-id-source: derived
    delete:
      tags:
      - Notes
      summary: Delete note (soft)
      description: Soft-delete a note. It can be restored from trash.
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      responses:
        '200':
          description: Note deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: deleteNotesById
      x-operation-id-source: derived
  /notes/{id}/history:
    get:
      tags:
      - Notes
      summary: Get note version history
      description: Return past snapshots of a note projected from the sync log, ordered newest first. Updates within a 5-minute compaction window collapse into one entry. `delete` (hard-delete) operations are excluded — they have no body. Use `cursor` (the `nextCursor` from the previous response) and `limit` (default 50, max 100) to paginate.
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      - schema:
          type: string
          description: Sync log version of the last entry from the previous page. Pass `nextCursor` from the prior response.
        required: false
        description: Sync log version of the last entry from the previous page. Pass `nextCursor` from the prior response.
        name: cursor
        in: query
      - schema:
          type: string
          description: Max entries to return (1-100, default 50).
        required: false
        description: Max entries to return (1-100, default 50).
        name: limit
        in: query
      responses:
        '200':
          description: Page of past versions
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    items:
                      type: object
                      properties:
                        version:
                          type: number
                        operation:
                          type: string
                          enum:
                          - create
                          - update
                          - soft-delete
                          - restore
                        createdAt:
                          type: string
                        title:
                          type: string
                        content:
                          type: string
                        isEncrypted:
                          type: boolean
                        encryptionHint:
                          type: string
                          nullable: true
                        editedBy:
                          type: object
                          properties:
                            userId:
                              type: string
                            name:
                              type: string
                              nullable: true
                          required:
                          - userId
                          - name
                          description: Who made this version, on a shared note
                      required:
                      - version
                      - operation
                      - createdAt
                      - title
                      - content
                      - isEncrypted
                      - encryptionHint
                  nextCursor:
                    type: integer
                    nullable: true
                required:
                - versions
                - nextCursor
        '402':
          description: Version history requires Caliu Pro
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: getNotesByIdHistory
      x-operation-id-source: derived
  /notes/{id}/restore:
    post:
      tags:
      - Notes
      summary: Restore note from trash
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      responses:
        '200':
          description: Note restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  note:
                    $ref: '#/components/schemas/Note'
                required:
                - note
        '404':
          description: Not found in trash
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: postNotesByIdRestore
      x-operation-id-source: derived
  /notes/{id}/archive:
    post:
      tags:
      - Notes
      summary: Archive note
      description: Archive a note. Archived notes are hidden from all listings but never auto-removed, and keep their tags so they can be unarchived losslessly.
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      responses:
        '200':
          description: Note archived
          content:
            application/json:
              schema:
                type: object
                properties:
                  note:
                    $ref: '#/components/schemas/Note'
                required:
                - note
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: postNotesByIdArchive
      x-operation-id-source: derived
  /notes/{id}/unarchive:
    post:
      tags:
      - Notes
      summary: Unarchive note
      description: Restore a note from the archive back to the active list.
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      responses:
        '200':
          description: Note unarchived
          content:
            application/json:
              schema:
                type: object
                properties:
                  note:
                    $ref: '#/components/schemas/Note'
                required:
                - note
        '404':
          description: Not found in archive
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: postNotesByIdUnarchive
      x-operation-id-source: derived
  /notes/{id}/permanent:
    delete:
      tags:
      - Notes
      summary: Permanently delete note
      description: Hard-delete a note. This cannot be undone.
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      responses:
        '200':
          description: Note permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: deleteNotesByIdPermanent
      x-operation-id-source: derived
  /notes/{id}/backlinks:
    get:
      tags:
      - Notes
      summary: Get backlinks
      description: Get notes that link to this note via [[wiki links]].
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      responses:
        '200':
          description: Backlinks
          content:
            application/json:
              schema:
                type: object
                properties:
                  backlinks:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        updated_at:
                          type: string
                      required:
                      - id
                      - title
                      - updated_at
                required:
                - backlinks
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: getNotesByIdBacklinks
      x-operation-id-source: derived
  /notes/{id}/links:
    get:
      tags:
      - Notes
      summary: Get outgoing links
      description: 'Notes this note mentions. A mention of a note the reader cannot open comes back as a private placeholder: `{ id, private: true, title: null, updatedAt: null }`, rendered as a "private note" chip. Mentions of notes that do not exist on the server are left out.'
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      responses:
        '200':
          description: Outgoing links
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    type: array
                    items:
                      $ref: '#/components/schemas/OutgoingLink'
                required:
                - links
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: getNotesByIdLinks
      x-operation-id-source: derived
  /notes/{id}/tags:
    post:
      tags:
      - Notes
      summary: Add tag to note
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tagId:
                  type: string
              required:
              - tagId
      responses:
        '200':
          description: Tag added
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: postNotesByIdTags
      x-operation-id-source: derived
  /notes/{id}/tags/sync:
    post:
      tags:
      - Notes
      summary: Sync note tags
      description: Replace all tags from a hashtag list. Upserts tags and removes orphans.
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Resource ID
          example: abc123
        required: true
        description: Resource ID
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Updated tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                      required:
                      - id
                      - name
                required:
                - tags
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: postNotesByIdTagsSync
      x-operation-id-source: derived
  /notes/{id}/tags/{tagId}:
    delete:
      tags:
      - Notes
      summary: Remove tag from note
      security:
      - bearerAuth: []
      - cookieAuth: []
      parameters:
      - schema:
          type: string
          description: Note ID
        required: true
        description: Note ID
        name: id
        in: path
      - schema:
          type: string
          description: Tag ID
        required: true
        description: Tag ID
        name: tagId
        in: path
      responses:
        '200':
          description: Tag removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: deleteNotesByIdTagsByTagId
      x-operation-id-source: derived
components:
  schemas:
    Note:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        content:
          type: string
        isPinned:
          type: boolean
        isEncrypted:
          type: boolean
        encryptionHint:
          type: string
          nullable: true
        wordCount:
          type: number
        createdAt:
          type: string
        updatedAt:
          type: string
        deletedAt:
          type: string
          nullable: true
        archivedAt:
          type: string
          nullable: true
        sharedAt:
          type: string
          nullable: true
        sortOrder:
          type: number
          nullable: true
        rev:
          type: number
          description: 'Content revision: one more for every accepted content change. Send it back as `base_rev` on `PUT /notes/{id}`.'
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
            required:
            - id
            - name
        role:
          type: string
          enum:
          - editor
          - viewer
          description: The requester's role, on notes shared with them (get and search).
        ownerId:
          type: string
          description: The owner, on notes shared with the requester.
      required:
      - id
      - title
      - content
      - isPinned
      - isEncrypted
      - encryptionHint
      - wordCount
      - createdAt
      - updatedAt
      - deletedAt
      - archivedAt
      - sharedAt
      - sortOrder
    OutgoingLink:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
          nullable: true
        updatedAt:
          type: string
          nullable: true
        private:
          type: boolean
      required:
      - id
      - title
      - updatedAt
      - private
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key (caliu_xxx) or session token
    cookieAuth:
      type: apiKey
      in: cookie
      name: caliu_session