openapi: 3.0.3
info:
  title: ToolJet External API
  description: >
    The ToolJet External API provides REST endpoints for managing users,
    workspaces, applications (export/import), groups, and user role assignments
    across a ToolJet instance. It is enabled via environment variables and
    secured with a static access token using Basic authentication.
  version: 1.0.0
  contact:
    name: ToolJet
    url: https://tooljet.com/
  license:
    name: AGPL-3.0
    url: https://github.com/ToolJet/ToolJet/blob/main/LICENSE

servers:
  - url: https://{instance}/api/ext
    description: ToolJet instance
    variables:
      instance:
        default: your-tooljet-instance.com
        description: Hostname of the ToolJet deployment

security:
  - BasicAuth: []

tags:
  - name: Users
    description: User management endpoints
  - name: Workspaces
    description: Workspace management endpoints
  - name: Applications
    description: Application export, import, and Git sync endpoints
  - name: Groups
    description: Group and permission management endpoints

paths:
  /users:
    get:
      summary: List all users
      operationId: getAllUsers
      tags:
        - Users
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      summary: Create a user
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserDto"
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /user/{id}:
    get:
      summary: Get a user by ID
      operationId: getUser
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          description: User details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      summary: Update a user
      operationId: updateUser
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserDto"
      responses:
        "200":
          description: User updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /user/{id}/workspaces:
    put:
      summary: Replace user workspaces
      operationId: replaceUserWorkspaces
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/WorkspaceDto"
      responses:
        "200":
          description: Workspaces replaced
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /user/{id}/workspace/{workspaceId}:
    patch:
      summary: Update user workspace membership
      operationId: updateUserWorkspace
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/UserId"
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateGivenWorkspaceDto"
      responses:
        "200":
          description: Workspace membership updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /workspaces:
    get:
      summary: List all workspaces
      operationId: getAllWorkspaces
      tags:
        - Workspaces
      responses:
        "200":
          description: List of workspaces
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /update-user-role/workspace/{workspaceId}:
    put:
      summary: Update user role in a workspace
      operationId: updateUserRole
      tags:
        - Workspaces
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EditUserRoleDto"
      responses:
        "200":
          description: User role updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /workspace/{workspaceId}/user/{userId}:
    get:
      summary: Get user metadata in workspace
      operationId: getUserMetadata
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User UUID
      responses:
        "200":
          description: User metadata
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      summary: Update user metadata in workspace
      operationId: updateUserMetadata
      tags:
        - Users
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserMetadataDto"
      responses:
        "200":
          description: User metadata updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /workspace/{workspaceId}:
    get:
      summary: List apps in workspace
      operationId: getWorkspaceApps
      tags:
        - Applications
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: List of apps with versions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppsResponseDto"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /import/{workspaceId}:
    post:
      summary: Import an application into a workspace
      operationId: importApp
      tags:
        - Applications
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppImportRequestDto"
      responses:
        "201":
          description: Application imported
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /export/{appId}/{workspaceId}:
    get:
      summary: Export an application
      operationId: exportApp
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: Application UUID
        - $ref: "#/components/parameters/WorkspaceId"
        - name: exportTjdb
          in: query
          schema:
            type: boolean
          description: Include ToolJet database export
        - name: appVersion
          in: query
          schema:
            type: string
          description: Specific version to export
        - name: exportAllVersions
          in: query
          schema:
            type: boolean
          description: Export all versions
      responses:
        "200":
          description: Application export data
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /pull-git:
    post:
      summary: Pull app from Git
      operationId: pullGit
      tags:
        - Applications
      parameters:
        - name: createMode
          in: query
          schema:
            type: boolean
          description: Create a new app if not found
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppGitPullDto"
      responses:
        "200":
          description: Git pull result
        "401":
          $ref: "#/components/responses/Unauthorized"

  /pull-changes/{appId}:
    post:
      summary: Pull Git changes for an app
      operationId: pullChanges
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: Application UUID
        - name: createMode
          in: query
          schema:
            type: boolean
          description: Create a new app if not found
      responses:
        "200":
          description: Pull changes result
        "401":
          $ref: "#/components/responses/Unauthorized"

  /push-git/{appId}/{versionId}:
    post:
      summary: Push app version to Git
      operationId: pushGit
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: Application UUID
        - name: versionId
          in: path
          required: true
          schema:
            type: string
          description: Version UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppGitPushDto"
      responses:
        "200":
          description: Push result
        "401":
          $ref: "#/components/responses/Unauthorized"

  /auto-deploy/{appIdOrSlug}:
    post:
      summary: Auto-deploy an app version
      operationId: autoDeploy
      tags:
        - Applications
      parameters:
        - name: appIdOrSlug
          in: path
          required: true
          schema:
            type: string
          description: Application UUID or slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AutoDeployBodyDto"
      responses:
        "200":
          description: Deployment initiated
        "401":
          $ref: "#/components/responses/Unauthorized"

  /save-version/{appIdOrSlug}:
    post:
      summary: Save a named version of an app
      operationId: saveVersion
      tags:
        - Applications
      parameters:
        - name: appIdOrSlug
          in: path
          required: true
          schema:
            type: string
          description: Application UUID or slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SaveVersionBodyDto"
      responses:
        "200":
          description: Version saved
        "401":
          $ref: "#/components/responses/Unauthorized"

  /workspace/{workspaceId}/groups:
    get:
      summary: List groups in workspace
      operationId: listGroups
      tags:
        - Groups
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: search
          in: query
          schema:
            type: string
          description: Filter groups by name
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 20
          description: Results per page
      responses:
        "200":
          description: List of groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      $ref: "#/components/schemas/Group"
                  total:
                    type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      summary: Create a group in workspace
      operationId: createGroup
      tags:
        - Groups
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGroupExternalDto"
      responses:
        "201":
          description: Group created
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /workspace/{workspaceId}/groups/{groupId}:
    get:
      summary: Get a group by ID
      operationId: getGroup
      tags:
        - Groups
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/GroupId"
      responses:
        "200":
          description: Group details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      summary: Update a group
      operationId: updateGroup
      tags:
        - Groups
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/GroupId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateGroupExternalDto"
      responses:
        "204":
          description: Group updated
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      summary: Delete a group
      operationId: deleteGroup
      tags:
        - Groups
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/GroupId"
      responses:
        "204":
          description: Group deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >
        Static access token configured via the TOOLJET_SERVICE_TOKEN environment
        variable. Pass the token as the username with an empty password, encoded
        as Base64 in the Authorization header.

  parameters:
    UserId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: User UUID
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Workspace UUID
    GroupId:
      name: groupId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Group UUID

  responses:
    Unauthorized:
      description: Authentication required or invalid token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    BadRequest:
      description: Invalid request body or parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  schemas:
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string

    Status:
      type: string
      enum:
        - active
        - archived
        - invited

    UserRole:
      type: string
      enum:
        - admin
        - developer
        - viewer
        - end-user

    GroupDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string

    WorkspaceDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        role:
          $ref: "#/components/schemas/UserRole"
        status:
          $ref: "#/components/schemas/Status"
        groups:
          type: array
          items:
            $ref: "#/components/schemas/GroupDto"

    UpdateGivenWorkspaceDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          $ref: "#/components/schemas/Status"
        groups:
          type: array
          items:
            $ref: "#/components/schemas/GroupDto"

    CreateUserDto:
      type: object
      required:
        - name
        - email
        - workspaces
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        password:
          type: string
        status:
          $ref: "#/components/schemas/Status"
        defaultOrganizationId:
          type: string
        workspaces:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceDto"

    UpdateUserDto:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        password:
          type: string
        status:
          $ref: "#/components/schemas/Status"
        defaultOrganizationId:
          type: string

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        status:
          $ref: "#/components/schemas/Status"
        defaultOrganizationId:
          type: string
        workspaces:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceDto"

    Workspace:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string

    EditUserRoleDto:
      type: object
      required:
        - role
      properties:
        role:
          $ref: "#/components/schemas/UserRole"
        userId:
          type: string
          format: uuid

    UpdateUserMetadataDto:
      type: object
      required:
        - userDetails
      properties:
        userDetails:
          type: array
          items:
            type: object
            required:
              - key
              - value
            properties:
              key:
                type: string
              value:
                type: string

    VersionDto:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        createdAt:
          type: string
          format: date-time

    AppWithVersionsDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        createdAt:
          type: string
          format: date-time
        organizationId:
          type: string
          format: uuid
        versions:
          type: array
          items:
            $ref: "#/components/schemas/VersionDto"
        versionCount:
          type: integer

    WorkspaceAppsResponseDto:
      type: object
      properties:
        apps:
          type: array
          items:
            $ref: "#/components/schemas/AppWithVersionsDto"
        total:
          type: integer

    AppImportRequestDto:
      type: object
      required:
        - tooljet_version
      properties:
        tooljet_version:
          type: string
        app:
          type: array
          items:
            type: object
            properties:
              definition:
                type: object
                additionalProperties: true
        appName:
          type: string
        tooljet_database:
          type: array
          items:
            type: object
            required:
              - id
              - table_name
              - schema
            properties:
              id:
                type: string
                format: uuid
              table_name:
                type: string
              schema:
                type: object
                additionalProperties: true

    AppGitPullDto:
      type: object
      required:
        - appId
        - organizationId
      properties:
        appId:
          type: string
        organizationId:
          type: string

    AppGitPushDto:
      type: object
      required:
        - commitMessage
      properties:
        commitMessage:
          type: string

    AutoDeployBodyDto:
      type: object
      properties:
        versionId:
          type: string
          format: uuid
        versionName:
          type: string

    SaveVersionBodyDto:
      type: object
      properties:
        name:
          type: string
          maxLength: 25

    WorkspacePermissionsDto:
      type: object
      properties:
        appCreate:
          type: boolean
        appDelete:
          type: boolean
        folderCreate:
          type: boolean
        folderDelete:
          type: boolean
        orgConstantCRUD:
          type: boolean
        workflowCreate:
          type: boolean
        workflowDelete:
          type: boolean
        dataSourceCreate:
          type: boolean
        dataSourceDelete:
          type: boolean
        appPromote:
          type: boolean
        appRelease:
          type: boolean

    GranularPermissionDto:
      type: object
      required:
        - type
        - applyToAll
        - resources
        - permissions
      properties:
        type:
          type: string
          enum:
            - app
            - data_source
            - folder
            - workflow
        applyToAll:
          type: boolean
        resources:
          type: array
          items:
            type: string
        permissions:
          type: object
          additionalProperties: true

    CreateGroupExternalDto:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 50
          description: Group name (alphanumeric, spaces, hyphens, underscores only)
        permissions:
          $ref: "#/components/schemas/WorkspacePermissionsDto"
        granularPermissions:
          type: array
          items:
            $ref: "#/components/schemas/GranularPermissionDto"

    UpdateGroupExternalDto:
      type: object
      properties:
        name:
          type: string
          maxLength: 50
          description: Group name (alphanumeric, spaces, hyphens, underscores only)
        permissions:
          $ref: "#/components/schemas/WorkspacePermissionsDto"
        granularPermissions:
          type: array
          items:
            $ref: "#/components/schemas/GranularPermissionDto"

    Group:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        permissions:
          $ref: "#/components/schemas/WorkspacePermissionsDto"
        granularPermissions:
          type: array
          items:
            $ref: "#/components/schemas/GranularPermissionDto"