openapi: 3.0.3
info:
  title: Velt Data (REST) API
  description: >-
    Server-side REST API for the Velt real-time collaboration platform. Velt is
    primarily a client SDK (React components and framework wrappers) that renders
    presence, live cursors, comments, notifications, huddles, recordings, and
    live selection inside applications. This Data API is the backend surface for
    that SDK: it lets servers read and write comments, users, organizations,
    folders, documents, notifications, and user groups, and manage workspace API
    keys, auth tokens, and webhook endpoints. All endpoints are HTTPS POST calls
    that take a JSON body wrapped in a top-level `data` object and are
    authenticated with the `x-velt-api-key` and `x-velt-auth-token` headers.
  termsOfService: https://velt.dev/terms
  contact:
    name: Velt Support
    url: https://velt.dev
  version: '2.0'
servers:
  - url: https://api.velt.dev/v2
    description: Velt Data API v2
security:
  - apiKeyAuth: []
    authToken: []
tags:
  - name: Comments
    description: Comment threads and annotations rendered by the SDK.
  - name: Users
    description: End users and user-group membership.
  - name: Organizations
    description: Top-level tenancy boundary.
  - name: Documents
    description: Documents and folders that collaboration attaches to.
  - name: Notifications
    description: Notifications and inbox/email configuration.
  - name: Webhooks
    description: Advanced webhook endpoints and event subscriptions.
  - name: Auth
    description: Workspace API keys and auth tokens.
paths:
  /comments/add:
    post:
      operationId: addComments
      tags:
        - Comments
      summary: Add comments
      description: Create one or more comment threads on a document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentAddRequest'
      responses:
        '200':
          description: Comments created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /comments/get:
    post:
      operationId: getComments
      tags:
        - Comments
      summary: Get comments
      description: Retrieve comment threads for one or more documents in an organization.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentScopedRequest'
      responses:
        '200':
          description: Comments returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /comments/update:
    post:
      operationId: updateComments
      tags:
        - Comments
      summary: Update comments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentAddRequest'
      responses:
        '200':
          description: Comments updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /comments/delete:
    post:
      operationId: deleteComments
      tags:
        - Comments
      summary: Delete comments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentScopedRequest'
      responses:
        '200':
          description: Comments deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /comments/annotations/get:
    post:
      operationId: getCommentAnnotations
      tags:
        - Comments
      summary: Get comment annotations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentScopedRequest'
      responses:
        '200':
          description: Annotations returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /comments/annotations/count/get:
    post:
      operationId: getCommentAnnotationsCount
      tags:
        - Comments
      summary: Get comment annotations count
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentScopedRequest'
      responses:
        '200':
          description: Annotation count returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /users/add:
    post:
      operationId: addUsers
      tags:
        - Users
      summary: Add users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAddRequest'
      responses:
        '200':
          description: Users added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /users/get:
    post:
      operationId: getUsers
      tags:
        - Users
      summary: Get users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationScopedRequest'
      responses:
        '200':
          description: Users returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /users/update:
    post:
      operationId: updateUsers
      tags:
        - Users
      summary: Update users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAddRequest'
      responses:
        '200':
          description: Users updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /users/delete:
    post:
      operationId: deleteUsers
      tags:
        - Users
      summary: Delete users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationScopedRequest'
      responses:
        '200':
          description: Users deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /user-groups/add:
    post:
      operationId: addUserGroups
      tags:
        - Users
      summary: Add user groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationScopedRequest'
      responses:
        '200':
          description: User group added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /user-groups/users/add:
    post:
      operationId: addUsersToGroups
      tags:
        - Users
      summary: Add users to groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationScopedRequest'
      responses:
        '200':
          description: Users added to group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /organizations/add:
    post:
      operationId: addOrganizations
      tags:
        - Organizations
      summary: Add organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationAddRequest'
      responses:
        '200':
          description: Organizations added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /organizations/get:
    post:
      operationId: getOrganizations
      tags:
        - Organizations
      summary: Get organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationScopedRequest'
      responses:
        '200':
          description: Organizations returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /organizations/update:
    post:
      operationId: updateOrganizations
      tags:
        - Organizations
      summary: Update organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationAddRequest'
      responses:
        '200':
          description: Organizations updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /organizations/delete:
    post:
      operationId: deleteOrganizations
      tags:
        - Organizations
      summary: Delete organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationScopedRequest'
      responses:
        '200':
          description: Organizations deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /folders/add:
    post:
      operationId: addFolder
      tags:
        - Documents
      summary: Add folder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationScopedRequest'
      responses:
        '200':
          description: Folder added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /folders/get:
    post:
      operationId: getFolders
      tags:
        - Documents
      summary: Get folders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationScopedRequest'
      responses:
        '200':
          description: Folders returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /documents/add:
    post:
      operationId: addDocuments
      tags:
        - Documents
      summary: Add documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentAddRequest'
      responses:
        '200':
          description: Documents added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /documents/get:
    post:
      operationId: getDocuments
      tags:
        - Documents
      summary: Get documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentScopedRequest'
      responses:
        '200':
          description: Documents returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /documents/update:
    post:
      operationId: updateDocuments
      tags:
        - Documents
      summary: Update documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentAddRequest'
      responses:
        '200':
          description: Documents updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /documents/move:
    post:
      operationId: moveDocuments
      tags:
        - Documents
      summary: Move documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentScopedRequest'
      responses:
        '200':
          description: Documents moved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /documents/delete:
    post:
      operationId: deleteDocuments
      tags:
        - Documents
      summary: Delete documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentScopedRequest'
      responses:
        '200':
          description: Documents deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /notifications/add:
    post:
      operationId: addNotifications
      tags:
        - Notifications
      summary: Add notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationAddRequest'
      responses:
        '200':
          description: Notifications added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /notifications/get:
    post:
      operationId: getNotifications
      tags:
        - Notifications
      summary: Get notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserScopedRequest'
      responses:
        '200':
          description: Notifications returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /notifications/update:
    post:
      operationId: updateNotifications
      tags:
        - Notifications
      summary: Update notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationAddRequest'
      responses:
        '200':
          description: Notifications updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /notifications/delete:
    post:
      operationId: deleteNotifications
      tags:
        - Notifications
      summary: Delete notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserScopedRequest'
      responses:
        '200':
          description: Notifications deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /notifications/config/get:
    post:
      operationId: getNotificationConfig
      tags:
        - Notifications
      summary: Get notification config
      description: >-
        Read inbox and email notification config for a user (or the organization
        when getOrganizationConfig is true), optionally scoped to up to 30
        documents.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationConfigGetRequest'
      responses:
        '200':
          description: Config returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /notifications/config/set:
    post:
      operationId: setNotificationConfig
      tags:
        - Notifications
      summary: Set notification config
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationConfigGetRequest'
      responses:
        '200':
          description: Config set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /webhooks/endpoints/create:
    post:
      operationId: createWebhookEndpoint
      tags:
        - Webhooks
      summary: Create advanced webhook endpoint
      description: >-
        Register a URL you control and select the collaboration event types to
        subscribe to. Deliveries are HMAC-signed and retried with exponential
        backoff.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointRequest'
      responses:
        '200':
          description: Webhook endpoint created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /webhooks/endpoints/get:
    post:
      operationId: getWebhookEndpoints
      tags:
        - Webhooks
      summary: Get advanced webhook endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationScopedRequest'
      responses:
        '200':
          description: Webhook endpoints returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /webhooks/endpoints/delete:
    post:
      operationId: deleteWebhookEndpoint
      tags:
        - Webhooks
      summary: Delete advanced webhook endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointRequest'
      responses:
        '200':
          description: Webhook endpoint deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /workspace/apikey/create:
    post:
      operationId: createApiKey
      tags:
        - Auth
      summary: Create API key
      description: Provision a new API key and its auth token for the workspace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataEnvelope'
      responses:
        '200':
          description: API key created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /workspace/apikey/get:
    post:
      operationId: getApiKeys
      tags:
        - Auth
      summary: Get API keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataEnvelope'
      responses:
        '200':
          description: API keys returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /workspace/apikey/auth-token/reset:
    post:
      operationId: resetAuthToken
      tags:
        - Auth
      summary: Reset auth token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataEnvelope'
      responses:
        '200':
          description: Auth token reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-velt-api-key
      description: Your Velt API key.
    authToken:
      type: apiKey
      in: header
      name: x-velt-auth-token
      description: Your Velt auth token that authorizes the API key.
  responses:
    Unauthorized:
      description: Missing or invalid API key / auth token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    DataEnvelope:
      type: object
      required:
        - data
      description: All Velt Data API requests wrap their payload in a top-level `data` object.
      properties:
        data:
          type: object
    OrganizationScopedRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizationId
          properties:
            organizationId:
              type: string
              description: Organization identifier.
    UserScopedRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizationId
            - userId
          properties:
            organizationId:
              type: string
            userId:
              type: string
    DocumentScopedRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizationId
          properties:
            organizationId:
              type: string
            documentId:
              type: string
              description: Single document identifier.
            documentIds:
              type: array
              items:
                type: string
              description: Up to 30 document identifiers.
    CommentAddRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizationId
            - documentId
          properties:
            organizationId:
              type: string
            documentId:
              type: string
            comments:
              type: array
              items:
                $ref: '#/components/schemas/Comment'
    Comment:
      type: object
      properties:
        commentId:
          type: string
        annotationId:
          type: string
        text:
          type: string
        from:
          $ref: '#/components/schemas/UserRef'
        status:
          type: string
          example: OPEN
    UserRef:
      type: object
      properties:
        userId:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
    UserAddRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizationId
            - users
          properties:
            organizationId:
              type: string
            users:
              type: array
              items:
                $ref: '#/components/schemas/UserRef'
    OrganizationAddRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizations
          properties:
            organizations:
              type: array
              items:
                type: object
                properties:
                  organizationId:
                    type: string
                  name:
                    type: string
    DocumentAddRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizationId
            - documents
          properties:
            organizationId:
              type: string
            documents:
              type: array
              items:
                type: object
                properties:
                  documentId:
                    type: string
                  documentName:
                    type: string
                  folderId:
                    type: string
    NotificationAddRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizationId
            - notifications
          properties:
            organizationId:
              type: string
            notifications:
              type: array
              items:
                type: object
                properties:
                  documentId:
                    type: string
                  toUserId:
                    type: string
                  message:
                    type: string
    NotificationConfigGetRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizationId
            - userId
          properties:
            organizationId:
              type: string
            userId:
              type: string
            documentIds:
              type: array
              items:
                type: string
              description: Up to 30 document IDs for document-level config.
            getOrganizationConfig:
              type: boolean
              description: Set true to fetch organization-level config instead of user-level.
    WebhookEndpointRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - organizationId
            - url
          properties:
            organizationId:
              type: string
            url:
              type: string
              format: uri
              description: The endpoint URL you control.
            eventTypes:
              type: array
              items:
                type: string
              description: >-
                Collaboration event types to subscribe to (for example comment
                newlyAdded and statusChanged actions).
    Result:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
        data:
          type: array
          items:
            type: object
    Error:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string