HackMD Team Notes API

openapi: 3.0.0
info:
  title: HackMD Open History Team Notes API
  version: 1.0.0
  description: HackMD OpenAPI
  license:
    name: UNLICENSED
  contact:
    name: HackMD Team
    email: support@hackmd.io
servers:
- url: /v1
  description: API Server
tags:
- name: Team Notes
  description: Operations related to notes within a team.
paths:
  /teams/{teampath}/notes:
    get:
      operationId: ListTeamNotes
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/NoteType'
                type: array
      description: List all notes for a team
      tags:
      - Team Notes
      security:
      - token: []
      parameters:
      - description: The path identifier for the team.
        in: path
        name: teampath
        required: true
        schema:
          type: string
    post:
      operationId: CreateTeamNote
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: {}
        '207':
          description: Multi-Status
      description: Create a new note for a team
      tags:
      - Team Notes
      security:
      - token: []
      parameters:
      - description: The path identifier for the team.
        in: path
        name: teampath
        required: true
        schema:
          type: string
      requestBody:
        description: The note content (string) or a JSON object with note properties (title, content, permissions, etc.).
        required: false
        content:
          application/json:
            schema:
              anyOf:
              - properties:
                  origin:
                    type: string
                  parentFolderId:
                    type: string
                  permalink:
                    type: string
                  noteFeatures:
                    $ref: '#/components/schemas/Partial_NoteFeatureValidPermissionRecordType_'
                  suggestEditPermission:
                    $ref: '#/components/schemas/SuggestEditPermissionType'
                  commentPermission:
                    $ref: '#/components/schemas/CommentPermissionType'
                  writePermission:
                    $ref: '#/components/schemas/NotePermissionRole'
                  readPermission:
                    $ref: '#/components/schemas/NotePermissionRole'
                  content:
                    type: string
                  description:
                    type: string
                  tags:
                    items:
                      type: string
                    type: array
                  title:
                    type: string
                type: object
              - type: string
              description: The note content (string) or a JSON object with note properties (title, content, permissions, etc.).
  /teams/{teampath}/notes/{noteId}:
    get:
      operationId: GetTeamNote
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema: {}
      description: Get a single note for a team
      tags:
      - Team Notes
      security:
      - token: []
      parameters:
      - description: The path identifier for the team.
        in: path
        name: teampath
        required: true
        schema:
          type: string
      - description: The ID of the note to retrieve.
        in: path
        name: noteId
        required: true
        schema:
          type: string
    patch:
      operationId: UpdateTeamNote
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema: {}
      description: Update a team note
      tags:
      - Team Notes
      security:
      - token: []
      parameters:
      - description: The path identifier for the team.
        in: path
        name: teampath
        required: true
        schema:
          type: string
      - description: The ID of the note to update.
        in: path
        name: noteId
        required: true
        schema:
          type: string
      requestBody:
        description: The properties to update on the team note (e.g., content, permissions, permalink, parentFolderId).
        required: true
        content:
          application/json:
            schema:
              properties:
                parentFolderId:
                  type: string
                  nullable: true
                permalink:
                  type: string
                writePermission:
                  $ref: '#/components/schemas/NotePermissionRole'
                readPermission:
                  $ref: '#/components/schemas/NotePermissionRole'
                content:
                  type: string
                description:
                  type: string
                tags:
                  items:
                    type: string
                  type: array
                title:
                  type: string
              type: object
              description: The properties to update on the team note (e.g., content, permissions, permalink, parentFolderId).
    delete:
      operationId: DeleteTeamNote
      responses:
        '204':
          description: No content
      description: Delete a team note
      tags:
      - Team Notes
      security:
      - token: []
      parameters:
      - description: The path identifier for the team.
        in: path
        name: teampath
        required: true
        schema:
          type: string
      - description: The ID of the note to delete.
        in: path
        name: noteId
        required: true
        schema:
          type: string
components:
  schemas:
    NoteType:
      properties:
        folderPaths:
          items:
            $ref: '#/components/schemas/FolderPath'
          type: array
        writePermission:
          $ref: '#/components/schemas/NotePermissionRole'
        readPermission:
          $ref: '#/components/schemas/NotePermissionRole'
        shortId:
          type: string
        publishLink:
          type: string
        permalink:
          type: string
          nullable: true
        teamPath:
          type: string
          nullable: true
        userPath:
          type: string
          nullable: true
        publishedAt:
          type: number
          format: double
          nullable: true
        publishType:
          $ref: '#/components/schemas/NotePublishType'
        lastChangeUser:
          allOf:
          - $ref: '#/components/schemas/SimpleUserProfile'
          nullable: true
        tagsUpdatedAt:
          type: number
          format: double
          nullable: true
        titleUpdatedAt:
          type: number
          format: double
          nullable: true
        createdAt:
          type: number
          format: double
        lastChangedAt:
          type: number
          format: double
        description:
          type: string
        tags:
          items:
            type: string
          type: array
        title:
          type: string
        id:
          type: string
      required:
      - writePermission
      - readPermission
      - shortId
      - publishLink
      - permalink
      - teamPath
      - userPath
      - publishedAt
      - publishType
      - lastChangeUser
      - tagsUpdatedAt
      - titleUpdatedAt
      - createdAt
      - lastChangedAt
      - description
      - tags
      - title
      - id
      type: object
    FolderPath:
      $ref: '#/components/schemas/Pick_FolderAttributes.id-or-name-or-icon-or-color-or-parentId-or-clientId_'
    SuggestEditPermissionType:
      enum:
      - disabled
      - forbidden
      - owners
      - signed_in_users
      type: string
    Pick_FolderAttributes.id-or-name-or-icon-or-color-or-parentId-or-clientId_:
      properties:
        id:
          allOf:
          - type: string
          - properties:
              undefined:
                type: boolean
                enum:
                - true
                nullable: false
            type: object
        name:
          type: string
        icon:
          allOf:
          - type: string
          - properties:
              undefined:
                type: boolean
                enum:
                - true
                nullable: false
            type: object
        color:
          allOf:
          - type: string
          - properties:
              undefined:
                type: boolean
                enum:
                - true
                nullable: false
            type: object
        parentId:
          allOf:
          - type: string
          - properties:
              undefined:
                type: boolean
                enum:
                - true
                nullable: false
            type: object
        clientId:
          type: string
      required:
      - id
      - name
      - icon
      - color
      - parentId
      - clientId
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    SimpleUserProfile:
      properties:
        name:
          type: string
        userPath:
          type: string
        photo:
          type: string
        biography:
          type: string
          nullable: true
      required:
      - name
      - userPath
      - photo
      - biography
      type: object
      additionalProperties: false
    Partial_NoteFeatureValidPermissionRecordType_:
      properties: {}
      type: object
      description: Make all properties in T optional
    NotePermissionRole:
      enum:
      - owner
      - signed_in
      - guest
      type: string
    NotePublishType:
      enum:
      - edit
      - view
      - slide
      - book
      type: string
    CommentPermissionType:
      enum:
      - disabled
      - forbidden
      - owners
      - signed_in_users
      - everyone
      type: string
  securitySchemes:
    token:
      type: http
      scheme: bearer