openapi: 3.2.0
info:
  description: SafeBase API documentation.
  version: 1.4.1
  title: SafeBase API documentation Documents API
  contact:
    email: support@safebase.io
servers:
- url: https://app.safebase.io/api/ext/v1/rest
security:
- apiKey: []
tags:
- name: Documents
paths:
  /document/{id}:
    get:
      tags:
      - Documents
      summary: Get a document by ID or external ID
      description: Fetch a single document by its ID or external ID, using a query parameter to indicate which
      operationId: getDocument
      parameters:
      - name: id
        in: path
        required: true
        schema:
          description: A unique document ID
          type: string
          format: uuid
      - in: query
        name: type
        required: false
        schema:
          description: 'Enum indicating whether to use the document ID or external ID to reference a document. \

            When querying for documents by external ID you can only retrieve documents that have been \

            created with this endpoint. When querying by document ID you can retrieve documents from \

            any source.

            '
          type: string
          enum:
          - document
          - external
          default: document
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    $ref: '#/paths/~1documents~1upload/put/responses/200/content/application~1json/schema/properties/result'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      security:
      - apiKey:
        - documents:view
    delete:
      tags:
      - Documents
      summary: Delete a document by ID
      description: Delete a single document by its ID
      operationId: deleteDocument
      parameters:
      - $ref: '#/paths/~1document~1%7Bid%7D/get/parameters/0'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      security:
      - apiKey:
        - documents:edit
    patch:
      tags:
      - Documents
      summary: Update document by ID
      description: Patch update a document by ID
      operationId: patchDocument
      parameters:
      - $ref: '#/paths/~1document~1%7Bid%7D/get/parameters/0'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                aiOptOut:
                  type: boolean
                expiresAt:
                  type: string
                  nullable: true
                  format: date-time
                name:
                  type: string
                tagIds:
                  type: array
                  items:
                    type: string
                productIds:
                  type: array
                  items:
                    type: string
                type:
                  type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      security:
      - apiKey:
        - documents:edit
  /documents:
    get:
      tags:
      - Documents
      summary: Get all documents
      description: Get all documents, with optional filtering
      operationId: getDocuments
      parameters:
      - in: query
        name: page
        schema:
          type: integer
      - in: query
        name: limit
        schema:
          type: integer
      - in: query
        name: orderBy
        schema:
          type: string
          enum:
          - createdAt:asc
          - createdAt:desc
          - updatedAt:asc
          - updatedAt:desc
          - name:asc
          - name:desc
          - expiresAt:asc
          - expiresAt:desc
      - in: query
        name: query
        schema:
          type: string
      - in: query
        name: mimeTypes
        schema:
          type: string
      - in: query
        name: productIds
        schema:
          type: string
      - in: query
        name: tags
        schema:
          type: string
      - in: query
        name: usedForAi
        schema:
          type: boolean
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    type: object
                    properties:
                      count:
                        type: integer
                      documents:
                        type: array
                        items:
                          $ref: '#/paths/~1documents~1upload/put/responses/200/content/application~1json/schema/properties/result'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      security:
      - apiKey:
        - documents:view
  /documents/upload:
    post:
      tags:
      - Documents
      summary: Request file upload
      description: 'Request a presigned url to upload a file. This file can then be used to create a new

        Document in Safebase or to replace a file for an existing Document.


        Once granted a presigned url, you should POST your file to that url, and then call

        PUT /documents/upload in order to create the Document.

        '
      operationId: postDocumentUpload
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - fileName
              - mimeType
              - md5b64
              - fileSize
              properties:
                fileName:
                  description: Name of a file, including the file extension
                  type: string
                mimeType:
                  description: The mime type of the file you want to upload
                  type: string
                  enum:
                  - text/csv
                  - text/html
                  - application/json
                  - application/msword
                  - application/pdf
                  - application/vnd.ms-excel
                  - application/vnd.ms-excel.sheet.macroenabled.12
                  - application/vnd.ms-excel.sheet.binary.macroenabled.12
                  - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
                  - application/vnd.openxmlformats-officedocument.wordprocessingml.document
                  - image/apng
                  - image/avif
                  - image/gif
                  - image/jpeg
                  - image/png
                  - image/svg+xml
                  - image/tiff
                  - image/webp
                  - text/plain
                  - application/zip
                  - application/x-zip-compressed
                md5b64:
                  description: A base64-encoded MD5 hash of the file
                  type: string
                fileSize:
                  description: The file size in bytes
                  type: integer
                  minimum: 0
                  maximum: 78643200
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    type: object
                    required:
                    - fileId
                    - signedUrl
                    - headers
                    properties:
                      fileId:
                        description: A unique fileId used to reference the uploaded file
                        type: string
                        format: uuid
                      signedUrl:
                        description: A presigned url that can be used to POST a file to
                        type: string
                        format: url
                      headers:
                        description: 'An object of string keys to string values that should be included

                          as headers in the request to upload the file to the signedUrl

                          '
                        type: object
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      security:
      - apiKey:
        - documents:edit
    put:
      tags:
      - Documents
      summary: Create document
      description: 'Creates a new Document or replaces a file backing an existing Document.

        '
      operationId: putDocumentUpload
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - fileId
              - mimeType
              properties:
                aiOptOut:
                  type: boolean
                expiresAt:
                  nullable: true
                  type: string
                  format: date-time
                name:
                  type: string
                tagIds:
                  type: array
                  items:
                    type: uuid
                  example: []
                productIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  example: []
                type:
                  description: Call GET /document-types to retrieve the current list of allowed document types
                  type: string
                fileId:
                  description: The id value returned from POST /documents/upload
                  type: string
                  format: uuid
                externalId:
                  description: A field to store your own unique identifier in
                  type: string
                replacementDocumentId:
                  type: string
                  format: uuid
                  description: "The id of an existing Document whose file you want to replace. \nWhen this field is not provided a new Document will be created.\n"
                mimeType:
                  description: The mime type of the file you want to upload
                  type: string
                  enum:
                  - text/csv
                  - text/html
                  - application/json
                  - application/msword
                  - application/pdf
                  - application/vnd.ms-excel
                  - application/vnd.ms-excel.sheet.macroenabled.12
                  - application/vnd.ms-excel.sheet.binary.macroenabled.12
                  - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
                  - application/vnd.openxmlformats-officedocument.wordprocessingml.document
                  - image/apng
                  - image/avif
                  - image/gif
                  - image/jpeg
                  - image/png
                  - image/svg+xml
                  - image/tiff
                  - image/webp
                  - text/plain
                  - application/zip
                  - application/x-zip-compressed
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    type: object
                    required:
                    - aiOptOut
                    - checksum
                    - createdAt
                    - expiresAt
                    - externalId
                    - id
                    - mimeType
                    - name
                    - sha256Hash
                    - size
                    - source
                    - type
                    - updatedAt
                    - tags
                    - uploadStatus
                    properties:
                      aiOptOut:
                        type: boolean
                      checksum:
                        type: string
                      createdAt:
                        type: string
                      expiresAt:
                        type: string
                        nullable: true
                      externalId:
                        type: string
                        nullable: true
                      id:
                        type: string
                      mimeType:
                        type: string
                      name:
                        type: string
                      sha256Hash:
                        type: string
                        nullable: true
                      size:
                        type: integer
                      source:
                        type: string
                      type:
                        type: string
                        nullable: true
                      updatedAt:
                        type: string
                      uploadStatus:
                        type: string
                      tags:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            tagName:
                              type: string
                      products:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      security:
      - apiKey:
        - documents:edit
  /document-types:
    get:
      tags:
      - Documents
      summary: Get document types
      description: Get all document types
      operationId: getDocumentTypes
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              example: privacy_policy
                            name:
                              type: string
                              example: Privacy Policy
                      count:
                        type: number
                        description: Number of Document Types in the list
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      security:
      - apiKey:
        - documents:view
components:
  schemas:
    ApiResponseInvalidApiKeyOrMissingScope:
      type: object
      properties:
        statusCode:
          type: integer
          example: 403
        error:
          type: string
          example: forbidden
        message:
          type: string
          example: 'Invalid API key / Missing required scope(s): (missing scopes here)'
    ApiResponseInvalidRequest:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        error:
          type: string
          example: bad_request
        message:
          type: string
          example: Invalid request.
    ApiResponseNotFound:
      type: object
      properties:
        statusCode:
          type: integer
          example: 404
        error:
          type: string
          example: not_found
        message:
          type: string
          example: Not found
  responses:
    '400':
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseInvalidRequest'
    '405':
      description: Method not allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseNotFound'
    '404':
      description: Not found or no access
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseNotFound'
    '403':
      description: Invalid api key / missing scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseInvalidApiKeyOrMissingScope'
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-sb-api-key
      in: header