Baserow Workspaces API

openapi: 3.0.3
info:
  title: Baserow API spec Admin Workspaces API
  version: 2.2.2
  description: 'For more information about our REST API, please visit [this page](https://baserow.io/docs/apis%2Frest-api).


    For more information about our deprecation policy, please visit [this page](https://baserow.io/docs/apis%2Fdeprecations).'
  contact:
    url: https://baserow.io/contact
  license:
    name: MIT
    url: https://github.com/baserow/baserow/blob/develop/LICENSE
tags:
- name: Workspaces
paths:
  /api/workspaces/:
    get:
      operationId: list_workspaces
      description: Lists all the workspaces of the authorized user. A workspace can contain multiple applications like a database. Multiple users can have access to a workspace. For example each company could have their own workspace containing databases related to that company. The order of the workspaces are custom for each user. The order is configurable via the **order_workspaces** endpoint.
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkspaceUserWorkspace'
          description: ''
    post:
      operationId: create_workspace
      description: Creates a new workspace where only the authorized user has access to. No initial data like database applications are added, they have to be created via other endpoints.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      tags:
      - Workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Workspace'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Workspace'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Workspace'
        required: true
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceUserWorkspace'
          description: ''
  /api/workspaces/{workspace_id}/:
    patch:
      operationId: update_workspace
      description: Updates the existing workspace related to the provided `workspace_id` parameter if the authorized user belongs to the workspace. It is not yet possible to add additional users to a workspace.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: header
        name: ClientUndoRedoActionGroupId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular action group.Then calling the undo/redo endpoint with the same ClientSessionId header, all the actions belonging to the same action group can be undone/redone together in a single API call.
      - in: path
        name: workspace_id
        schema:
          type: integer
        description: Updates the workspace related to the provided value.
        required: true
      tags:
      - Workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedWorkspace'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedWorkspace'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedWorkspace'
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                    - ERROR_REQUEST_BODY_VALIDATION
                    - ERROR_USER_INVALID_GROUP_PERMISSIONS
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_GROUP_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
    delete:
      operationId: delete_workspace
      description: Deletes an existing workspace if the authorized user belongs to the workspace. All the applications, databases, tables etc that were in the workspace are going to be deleted also.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: header
        name: ClientUndoRedoActionGroupId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular action group.Then calling the undo/redo endpoint with the same ClientSessionId header, all the actions belonging to the same action group can be undone/redone together in a single API call.
      - in: path
        name: workspace_id
        schema:
          type: integer
        description: Deletes the workspace related to the provided value.
        required: true
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '204':
          description: No response body
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                    - ERROR_REQUEST_BODY_VALIDATION
                    - ERROR_USER_INVALID_GROUP_PERMISSIONS
                    - ERROR_CANNOT_DELETE_ALREADY_DELETED_ITEM
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_GROUP_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/workspaces/{workspace_id}/export/:
    get:
      operationId: list_workspace_exports
      description: Lists exports that were created for given workspace.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: path
        name: workspace_id
        schema:
          type: integer
        description: The id of the workspace that is being exported.
        required: true
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListExportWorkspaceApplications'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_GROUP_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/workspaces/{workspace_id}/export/async/:
    post:
      operationId: export_workspace_applications_async
      description: Export workspace or set of applications application if the authorized user is in the application's workspace. All the related children are also going to be exported. For example in case of a database application all the underlying tables, fields, views and rows are going to be exported.Roles are not part of the export.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: path
        name: workspace_id
        schema:
          type: integer
        description: The id of the workspace that must be exported.
        required: true
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportApplicationsJobTypeResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                    - ERROR_APPLICATION_NOT_IN_GROUP
                    - ERROR_MAX_JOB_COUNT_EXCEEDED
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_GROUP_DOES_NOT_EXIST
                    - ERROR_APPLICATION_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/workspaces/{workspace_id}/import/{resource_id}/:
    delete:
      operationId: import_export_resource
      description: Delete a resource. This endpoint mark as ready for deletion the specified resource. This operation is not undoable. The user must be the owner of the resource to perform this action.
      parameters:
      - in: path
        name: resource_id
        schema:
          type: string
          pattern: ^[0-9]+$
        required: true
      - in: path
        name: workspace_id
        schema:
          type: string
          pattern: ^[0-9]+$
        required: true
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '204':
          description: No response body
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - RESOURCE_DOES_NOT_EXIST
                    - ERROR_GROUP_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/workspaces/{workspace_id}/import/async/:
    post:
      operationId: import_workspace_applications_async
      description: Import a set of applications included in a given resource if the authorized user is in the specified workspace. This endpoint requires a valid resource_id of the uploaded file.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: path
        name: workspace_id
        schema:
          type: integer
        description: The id of the workspace where the application will be imported.
        required: true
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportApplicationsJobTypeResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                    - ERROR_MAX_JOB_COUNT_EXCEEDED
                    - ERROR_RESOURCE_DOES_NOT_EXIST
                    - ERROR_RESOURCE_IS_INVALID
                    - ERROR_APPLICATION_IDS_NOT_FOUND
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_GROUP_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/workspaces/{workspace_id}/import/upload-file/:
    post:
      operationId: import_resource_upload_file
      description: Uploads an exported workspace or a set of applications if the authorized user is in the workspace. The uploaded file must be a valid ZIP file containing the applications' data for future import.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: path
        name: workspace_id
        schema:
          type: integer
        description: The id of the workspace for which file is uploaded.
        required: true
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResource'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                    - ERROR_INVALID_FILE
                    - ERROR_FILE_SIZE_TOO_LARGE
                    - ERROR_RESOURCE_IS_INVALID
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_GROUP_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/workspaces/{workspace_id}/leave/:
    post:
      operationId: leave_workspace
      description: Makes the authenticated user leave the workspace related to the provided `workspace_id` if the user is in that workspace. If the user is the last admin in the workspace, they will not be able to leave it. There must always be one admin in the workspace, otherwise it will be left without control. If that is the case, they must either delete the workspace or give another member admin permissions first.
      parameters:
      - in: path
        name: workspace_id
        schema:
          type: integer
        description: Leaves the workspace related to the value.
        required: true
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '204':
          description: No response body
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                    - ERROR_GROUP_USER_IS_LAST_ADMIN
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_GROUP_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/workspaces/{workspace_id}/permissions/:
    get:
      operationId: workspace_permissions
      description: "Returns a the permission data necessary to determine the permissions of a specific user over a specific workspace. \nSee `core.handler.CoreHandler.get_permissions()` for more details."
      parameters:
      - in: path
        name: workspace_id
        schema:
          type: integer
        description: The workspace id we want the permission object for.
        required: true
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PermissionObject'
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                    - ERROR_GROUP_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/workspaces/{workspace_id}/settings/generative-ai/:
    get:
      operationId: get_workspace_generative_ai_models_settings
      description: Returns the generative AI models settings for the given workspace.
      parameters:
      - in: path
        name: workspace_id
        schema:
          type: string
          pattern: ^[0-9]+$
        required: true
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerativeAISettings'
          description: ''
    patch:
      operationId: update_workspace_generative_ai_models_settings
      description: Updates the generative AI models settings for the given workspace.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: path
        name: workspace_id
        schema:
          type: integer
        description: Updates the workspace settings for the generative AI models available.
        required: true
      tags:
      - Workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedGenerativeAISettings'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedGenerativeAISettings'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedGenerativeAISettings'
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_NOT_IN_GROUP
                    - ERROR_REQUEST_BODY_VALIDATION
                    - ERROR_USER_INVALID_GROUP_PERMISSIONS
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_GROUP_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/workspaces/create-initial-workspace/:
    post:
      operationId: create_initial_workspace
      description: Creates an initial workspace. This is typically called after the user signs up and skips the onboarding in the frontend. It contains some example data.
      tags:
      - Workspaces
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceUserWorkspace'
          description: ''
  /api/workspaces/order/:
    post:
      operationId: order_workspaces
      description: Changes the order of the provided workspace ids to the matching position that the id has in the list. If the authorized user does not belong to the workspace it will be ignored. The order will be custom for each user.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: header
        name: ClientUndoRedoActionGroupId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular action group.Then calling the undo/redo endpoint with the same ClientSessionId header, all the actions belonging to the same action group can be undone/redone together in a single API call.
      tags:
      - Workspaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderWorkspaces'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OrderWorkspaces'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OrderWorkspaces'
        required: true
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '204':
          description: No response body
  /api/workspaces/users/{workspace_user_id}/:
    patch:
      operationId: update_workspace_user
      description: Updates the existing workspace user related to the provided `workspace_user_id` param if the authorized user has admin rights to

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/baserow/refs/heads/main/openapi/baserow-workspaces-api-openapi.yml