SoftSync AI Notes API

openapi: 3.2.0
info:
  title: Softsync Notes API
  description: '## Introduction


    The Softsync Platform API


    This API lets you read and write your Softsync data from your own applications. Authenticate with a personal API key created in **Settings → API Keys**, sent as the `x-api-key` header.


    **New here?** Read **Concepts** first, then **Authentication**, then **Quickstart: full cycle** — it walks the whole thing end to end. **Objects**, **Records**, **Groups & Views** and **Notes** cover each area in depth, and **Code Generation** shows how to turn this document into a typed client.


    To try a request from this page, paste your API key into the **Authentication** panel on the right.


    ## Support


    If you need help with API access or integration details, contact contact@softsync.ai.'
  version: 0.1.0
  contact: {}
servers: []
security:
- x-api-key: []
tags:
- name: Notes
paths:
  /notes/integrations:
    post:
      description: Returns existing integration or creates a new one for public notes or private notes
      operationId: getNotesIntegrations
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Integration retrieved or created successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IntegrationDto'
      security:
      - bearer: []
      summary: Get or create integration for notes
      tags:
      - Notes
      x-feature: notes
  /notes:
    post:
      description: Creates a new note (public or private) with mentions and attachments
      operationId: createNote
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNoteDto'
      responses:
        '201':
          description: Note created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDataDto'
      security:
      - bearer: []
      summary: Create a note
      tags:
      - Notes
      x-feature: notes
  /notes/{noteId}:
    patch:
      description: Updates note content and re-processes mentions
      operationId: editNote
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: noteId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNoteDto'
      responses:
        '200':
          description: Note updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDataDto'
      security:
      - bearer: []
      summary: Edit a note
      tags:
      - Notes
      x-feature: notes
    delete:
      description: Soft deletes a note
      operationId: deleteNote
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: noteId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: Note deleted successfully
      security:
      - bearer: []
      summary: Delete a note
      tags:
      - Notes
      x-feature: notes
  /notes/{noteId}/visibility:
    put:
      description: Toggles note between private and public
      operationId: switchVisibility
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: noteId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Note visibility updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDataDto'
      security:
      - bearer: []
      summary: Switch note visibility
      tags:
      - Notes
      x-feature: notes
components:
  schemas:
    UpdateNoteDto:
      type: object
      properties:
        content:
          description: Note content
          allOf:
          - $ref: '#/components/schemas/NoteContentDto'
        files:
          description: Updated file attachments (replaces existing list)
          type: array
          items:
            $ref: '#/components/schemas/FileAttachment'
      required:
      - content
    NoteContentDto:
      type: object
      properties:
        content:
          type: string
      required:
      - content
    MessageRecordLinkDto:
      type: object
      properties:
        id:
          type: string
        record:
          $ref: '#/components/schemas/RecordInfoDto'
        kind:
          type: string
      required:
      - id
      - record
      - kind
    CreateNoteDto:
      type: object
      properties:
        content:
          description: Note content
          allOf:
          - $ref: '#/components/schemas/NoteContentDto'
        isPrivate:
          type: boolean
          description: Whether this is a private note
        replyToMessageId:
          type: string
          description: Reply to another message ID
        attachedRecordIds:
          description: Record IDs to attach to this note
          type: array
          items:
            type: string
        files:
          description: Optional file attachments
          type: array
          items:
            $ref: '#/components/schemas/FileAttachment'
      required:
      - content
      - isPrivate
    IntegrationDto:
      type: object
      properties:
        id:
          type: string
          description: Integration identifier
        type:
          type: string
          description: Integration type (e.g. notes, private_notes)
        visibility:
          type: string
          description: Integration visibility (private or shared)
        ownerId:
          type: string
          description: Owner user ID for private integrations
        canManage:
          type: boolean
          description: Whether the caller connected it and may change or disconnect it; false for a mailbox a teammate shared with them
        metadata:
          type: object
        config:
          type: object
      required:
      - id
      - type
      - visibility
      - canManage
    RecordInfoDto:
      type: object
      properties:
        id:
          type: string
        table:
          type: string
        groups:
          type: array
          items:
            type: string
        data:
          type: object
          description: Raw data keyed by field ID
        metadata:
          $ref: '#/components/schemas/RecordMetadata'
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
        createdBy:
          type: string
      required:
      - id
      - table
      - data
      - createdAt
      - updatedAt
    UserInfoDto:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        avatarUrl:
          type: string
      required:
      - id
      - email
    MessageMessageLinkDto:
      type: object
      properties:
        id:
          type: string
        linkedMessage:
          $ref: '#/components/schemas/LinkedMessageDto'
        kind:
          type: string
      required:
      - id
      - linkedMessage
      - kind
    MessageDataDto:
      type: object
      properties:
        id:
          type: string
        integrationId:
          type: string
        integrationType:
          type: string
        content:
          type: object
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileAttachment'
        metadata:
          type: object
        searchableText:
          type: string
        timestamp:
          format: date-time
          type: string
        workspaceId:
          type: string
          description: The organization the message is in. Set only when reading across organizations.
        createdAt:
          format: date-time
          type: string
        recordLinks:
          type: array
          items:
            $ref: '#/components/schemas/MessageRecordLinkDto'
        userLinks:
          type: array
          items:
            $ref: '#/components/schemas/MessageUserLinkDto'
        messageLinks:
          type: array
          items:
            $ref: '#/components/schemas/MessageMessageLinkDto'
      required:
      - id
      - integrationId
      - integrationType
      - content
      - files
      - timestamp
      - createdAt
      - recordLinks
      - userLinks
      - messageLinks
    LinkedMessageDto:
      type: object
      properties:
        id:
          type: string
        integrationId:
          type: string
        integrationType:
          type: string
        content:
          type: object
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileAttachment'
        metadata:
          type: object
        searchableText:
          type: string
        timestamp:
          format: date-time
          type: string
        workspaceId:
          type: string
          description: The organization the message is in. Set only when reading across organizations.
        createdAt:
          format: date-time
          type: string
        recordLinks:
          type: array
          items:
            $ref: '#/components/schemas/MessageRecordLinkDto'
        userLinks:
          type: array
          items:
            $ref: '#/components/schemas/MessageUserLinkDto'
      required:
      - id
      - integrationId
      - integrationType
      - content
      - files
      - timestamp
      - createdAt
      - recordLinks
      - userLinks
    RecordMetadata:
      type: object
      properties:
        viewOrders:
          type: object
          additionalProperties:
            type: number
          description: Orders in different views (viewId -> order)
        avatarUrl:
          type: string
          description: Avatar file path stored in record metadata
        formulaOverrides:
          description: Calculated-default fields a person typed over; they are no longer recalculated
          type: array
          items:
            type: string
        ruleIssues:
          type: array
          items:
            type: object
          description: Rules this record breaks, saved by a change that may not be refused (e.g. a public booking). Cleared by the next save that passes.
        source:
          type: object
          additionalProperties: true
          description: The feature that made this record when no person did (a booking page, a form…)
    FileAttachment:
      type: object
      properties:
        id:
          type: string
        path:
          type: string
        fileName:
          type: string
        fileSize:
          type: number
        mime:
          type: string
        isInline:
          type: boolean
        contentId:
          type: string
        url:
          type: string
      required:
      - id
      - path
      - fileName
      - fileSize
      - mime
    MessageUserLinkDto:
      type: object
      properties:
        id:
          type: string
        user:
          $ref: '#/components/schemas/UserInfoDto'
        kind:
          type: string
      required:
      - id
      - user
      - kind
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key