This content is dedicated to our next version. It is work in progress: its content will evolve until the new version is released.

Before that time, it cannot be considered as official.

REST API for Bonita UI Builder

The REST API lets you automatize some UI Builder actions with HTTP requests.

These REST APIs aim to solve the following cloud deployment use cases:

  • Deploy initial applications

  • Update applications: add, update, and remove applications

  • Re-deploy applications: ensuring resilience (for example in case of a Kubernetes pod crash)

  • Export all applications for storing files in a Bonita Studio project

These APIs are allowed to the Bonita technical user only.
See the Bonita login API to log in. The X-Bonita-API-Token and JSESSIONID cookies are required for these APIs (in the Headers).

Overview

The Applications Management API provides endpoints to manage applications in the UIB workspace. These endpoints allow you to list, import, export, and delete applications.

Base URL: /uib/api/v1/applications

Common Requirements:

  • All endpoints require authentication via session cookies

  • CSRF protection via x-requested-by: Appsmith header is required

  • Operations are scoped to the default workspace

Table of Contents

  1. List Applications

  2. Delete All Applications

  3. Import Single Application

  4. Import Multiple Applications

  5. Export All Applications

List Applications

Retrieve a list of all applications in the default workspace.

Request

HTTP Method

GET

URL

/uib/api/v1/applications/

Headers

Header Required Description

x-requested-by

Yes

Must be set to Appsmith

Cookie

Yes

Must include valid session cookies: X-Bonita-API-Token and JSESSIONID

Query Parameters

Parameter Type Required Description

full

boolean

No

If true, returns complete application objects. If false or omitted, returns only id and name fields. Default: false

Response

Content Type

application/json

Response Status Codes

Status Code Status Description

200

OK

Applications retrieved successfully. Returns a list of application objects.

204

NO_CONTENT

No applications found in the workspace. Returns an empty list.

500

INTERNAL_SERVER_ERROR

An error occurred while retrieving applications.

Response Body Structure

{
  "responseMeta": {
    "status": 200,
    "success": true
  },
  "data": [
    {
      "id": "app-id-1",
      "name": "My Application"
    },
    {
      "id": "app-id-2",
      "name": "Another Application"
    }
  ],
  "errorDisplay": null
}

Response Body (full=true)

When full=true is specified, each application object contains all fields including metadata, configuration, pages, etc.

Examples

Example 1: List applications (minimal)

curl -X GET 'http://localhost/uib/api/v1/applications/' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456'

Response:

{
  "responseMeta": {
    "status": 200,
    "success": true
  },
  "data": [
    {"id": "64a1b2c3d4e5f6", "name": "Dashboard"},
    {"id": "74b2c3d4e5f6a7", "name": "Admin Panel"}
  ],
  "errorDisplay": null
}

Example 2: List applications (full details)

curl -X GET 'http://localhost/uib/api/v1/applications/?full=true' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456'

Returns complete application objects with all fields.

Example 3: Empty workspace

curl -X GET 'http://localhost/uib/api/v1/applications/' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456'

Response:

{
  "responseMeta": {
    "status": 204,
    "success": true
  },
  "data": [],
  "errorDisplay": "No applications found"
}

Behavior Details

  • Retrieves applications from the default workspace only

  • Returns applications in the order they are stored

  • The full parameter allows to control the size of the response payload

  • Errors are logged but return a 500 status with error details

Delete All Applications

Delete all applications from the default workspace (workspace cleanup).

Request

HTTP Method

DELETE

URL

/uib/api/v1/applications/all

Headers

Header Required Description

x-requested-by

Yes

Must be set to Appsmith

Cookie

Yes

Must include valid session cookies: X-Bonita-API-Token and JSESSIONID

Query Parameters

| Parameter | Type | Required | Default | Description | |------------------------|---------|----------|---------|-----------------------------------------------------------| | cleanGitApplication | boolean | No | true | If true, deletes Git-connected applications. If false, skips Git-connected applications and only deletes non-Git applications. |

Request Body

None

Response

Content Type

application/json

Response Status Codes

Status Code Status Description

200

OK

All applications were successfully deleted.

204

NO_CONTENT

No applications found to delete.

207

MULTI_STATUS

Some applications were deleted, but others failed. Check the response body for details.

500

INTERNAL_SERVER_ERROR

All deletion attempts failed.

Response Body Structure

{
  "responseMeta": {
    "status": 200,
    "success": true
  },
  "data": [
    {
      "id": "app-id-1",
      "name": "Application Name",
      "deleted": true,
      "errorMessage": null
    },
    {
      "id": "app-id-2",
      "name": "Failed App",
      "deleted": false,
      "errorMessage": "Permission denied"
    }
  ],
  "errorDisplay": null
}

Examples

Example 1: Delete all applications successfully

curl -X DELETE 'http://localhost/uib/api/v1/applications/all?cleanGitApplication=false' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456'

Response:

{
  "responseMeta": {
    "status": 200,
    "success": true
  },
  "data": [
    {"id": "64a1b2c3d4e5f6", "name": "Dashboard", "deleted": true, "errorMessage": null},
    {"id": "74b2c3d4e5f6a7", "name": "Admin Panel", "deleted": true, "errorMessage": null}
  ],
  "errorDisplay": "Applications deleted successfully"
}

Example 2: No applications to delete

curl -X DELETE 'http://localhost/uib/api/v1/applications/all' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456'

Response:

{
  "responseMeta": {
    "status": 204,
    "success": true
  },
  "data": null,
  "errorDisplay": "No applications to delete"
}

Example 3: Partial deletion (Multi-Status)

curl -X DELETE 'http://localhost/uib/api/v1/applications/all' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456'

Response:

{
  "responseMeta": {
    "status": 207,
    "success": true
  },
  "data": [
    {"id": "64a1b2c3d4e5f6", "name": "Dashboard", "deleted": true, "errorMessage": null},
    {"id": "74b2c3d4e5f6a7", "name": "Admin Panel", "deleted": false, "errorMessage": "Database constraint violation"}
  ],
  "errorDisplay": "Some applications could not be deleted"
}

Important Notes

  • Atomic Operations: Each application deletion is independent. If one fails, others continue.

  • File Cleanup: The endpoint also deletes the JSON descriptor file stored on the file system.

  • No Rollback: There is no automatic rollback. Successful deletions are permanent even if others fail.

  • Logging: All deletion attempts are logged with detailed information.

  • Error Handling: Individual application deletion errors are captured and returned in the response.

File System Impact

For each application deleted, the corresponding JSON file is removed from:

{bonitaProperties.applicationFolderPath}/\{applicationName}.json

If the file doesn’t exist, a warning is logged but deletion continues.

Import Single Application

Import a single application from a JSON descriptor file.

Request

HTTP Method

POST

URL

/uib/api/v1/applications/import

Headers

Header Required Description

x-requested-by

Yes

Must be set to Appsmith

Cookie

Yes

Must include valid session cookies: X-Bonita-API-Token and JSESSIONID

Content-Type

Yes

Must be multipart/form-data

Request Body

Field Type Required Description

file

File

Yes

The JSON application descriptor file to import. Must have .json extension.

Response

Content Type

application/json

Response Status Codes

Status Code Status Description

200

OK

Application imported and published successfully.

400

BAD_REQUEST

Invalid file (not a file part, not a .json file, invalid JSON format, or no application imported).

500

INTERNAL_SERVER_ERROR

An error occurred during import or publishing.

Response Body Structure

{
  "responseMeta": {
    "status": 200,
    "success": true
  },
  "data": {
    "name": "Imported Application Name",
    "status": "IMPORTED"
  },
  "errorDisplay": null
}

Examples

Example 1: Import application successfully

curl -X POST 'http://localhost/uib/api/v1/applications/import' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456' \
  -F 'file=@MyApplication.json'

Response:

{
  "responseMeta": {
    "status": 200,
    "success": true
  },
  "data": {
    "name": "MyApplication",
    "status": "IMPORTED"
  },
  "errorDisplay": null
}

Example 2: Invalid file type

curl -X POST 'http://localhost/uib/api/v1/applications/import' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456' \
  -F 'file=@application.xml'

Response:

{
  "responseMeta": {
    "status": 400,
    "success": false
  },
  "data": null,
  "errorDisplay": "File is not a .json application descriptor"
}

Important Notes

  • Automatic Publishing: The application is automatically published after import

  • File Persistence: A copy of the JSON descriptor is saved to the file system at:

{bonitaProperties.applicationFolderPath}/\{applicationName}.json

  • Memory Usage: The entire JSON file is loaded into memory during processing

  • Name Conflicts: If an application with the same slug exists, the import fails

  • Validation: The JSON must be a valid Appsmith application descriptor

Import Multiple Applications

Import multiple applications from a ZIP archive containing JSON descriptor files.

Request

HTTP Method

POST

URL

/uib/api/v1/applications/import-bulk

Headers

Header Required Description

x-requested-by

Yes

Must be set to Appsmith

Cookie

Yes

Must include valid session cookies: X-Bonita-API-Token and JSESSIONID

Content-Type

Yes

Must be multipart/form-data

Request Body

Field Type Required Description

file

File

Yes

The ZIP archive containing JSON application descriptors. Must have .zip extension.

Response

Content Type

application/json

Response Status Codes

Status Code Status Description

200

OK

All applications imported successfully.

206

PARTIAL_CONTENT

Some applications were imported, but not all. Check response for details.

400

BAD_REQUEST

Invalid file (not a file part, not a .zip file, or no valid applications found in the archive).

500

INTERNAL_SERVER_ERROR

An error occurred during import processing.

Response Body Structure

{
  "responseMeta": {
    "status": 200,
    "success": true
  },
  "data": [
    {
      "name": "Application1",
      "status": "IMPORTED"
    },
    {
      "name": "Application2",
      "status": "IMPORTED"
    }
  ],
  "errorDisplay": null
}

Partial Import Response (206)

{
  "responseMeta": {
    "status": 206,
    "success": true
  },
  "data": [
    {
      "name": "Application1",
      "status": "IMPORTED"
    }
  ],
  "errorDisplay": "Not all applications were imported from the zip archive"
}

Examples

Example 1: Import all applications from ZIP

curl -X POST 'http://localhost/uib/api/v1/applications/import-bulk' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456' \
  -F 'file=@applications-backup.zip'

Response:

{
  "responseMeta": {
    "status": 200,
    "success": true
  },
  "data": [
    {"name": "Dashboard", "status": "IMPORTED"},
    {"name": "Admin Panel", "status": "IMPORTED"},
    {"name": "User Portal", "status": "IMPORTED"}
  ],
  "errorDisplay": null
}

Example 2: Partial import (some applications failed)

curl -X POST 'http://localhost/uib/api/v1/applications/import-bulk' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456' \
  -F 'file=@applications.zip'

Response:

{
  "responseMeta": {
    "status": 206,
    "success": true
  },
  "data": [
    {"name": "Dashboard", "status": "IMPORTED"},
    {"name": "Admin Panel", "status": "IMPORTED"}
  ],
  "errorDisplay": "Not all applications were imported from the zip archive"
}

Example 3: Invalid ZIP file

curl -X POST 'http://localhost/uib/api/v1/applications/import-bulk' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456' \
  -F 'file=@document.pdf'

Response:

{
  "responseMeta": {
    "status": 400,
    "success": false
  },
  "data": null,
  "errorDisplay": "File is not a .zip archive"
}

ZIP Archive Structure

The ZIP file should contain one or more JSON files:

applications.zip
├── Application1.json
├── Application2.json
├── Application3.json
└── subfolder/
    └── Application4.json    (also supported)

Notes: * Only files with .json extension are processed * Subdirectories are supported (JSON files can be nested) * Non-JSON files and directories are ignored * File names are preserved for logging purposes

Important Notes

  • Sequential Processing: Applications are imported one at a time in the order they appear in the ZIP

  • Partial Success: If some applications fail, successfully imported ones remain (no rollback)

  • Error Handling: Individual import errors are logged but don’t stop the process

  • Memory Usage: The entire ZIP is loaded into memory, then each JSON is processed

  • File Persistence: Each imported application’s JSON is saved to:

{bonitaProperties.applicationFolderPath}/\{applicationName}.json

Export All Applications

Export all applications from the default workspace as a ZIP archive.

This endpoint is accessible as follows:

  • Only technical users can access it when ui-builder is started with the BONITA_DEV_MODE=true environment variable.

  • All user roles can access it when ui-builder is started with the BONITA_DEV_MODE=false environment variable.

Request

HTTP Method

GET

URL

/uib/api/v1/applications/export/all

Headers

Header Required Description

x-requested-by

Yes

Must be set to Appsmith

Cookie

Yes

Must include valid session cookies: X-Bonita-API-Token and JSESSIONID

Query Parameters

| Parameter | Type | Required | Default | Description | |---------------------|---------|----------|---------|-----------------------------------------------------------| | exportAsZipFormat | boolean | No | true | If true, returns ZIP file. If false, exports to filesystem (requires BONITA_APPLICATION_EXPORT_PATH configuration). |

Request Body

None

Response

Content Type

application/octet-stream

Response Headers

Header Description

Content-Disposition

Set to attachment; filename=applications-YYYYMMDD-HHmmss.zip where the timestamp represents when the export was generated

Content-Type

Set to application/octet-stream

Response Status Codes

Status Code Status Description

200

OK

Applications exported successfully. Response body contains a ZIP file with all application JSON descriptors.

204

NO_CONTENT

No applications found in the workspace. No file is returned.

500

INTERNAL_SERVER_ERROR

An error occurred during the export process. The response body is empty.

Response Body (200 OK)

When successful, the response is a ZIP archive containing one or more JSON files.

ZIP Archive Structure
applications-20250109-143022.zip
├── ApplicationName1.json
├── ApplicationName2.json
├── ApplicationName3.json
└── ...

Each JSON file contains the complete application descriptor in Appsmith’s ArtifactExchangeJson format.

JSON File Naming

Each file inside the ZIP is named using the pattern: {ApplicationName}.json

Examples

Example 1: Export all applications

curl -X GET 'http://localhost/uib/api/v1/applications/export/all' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456' \
  --output applications.zip

Response:

HTTP/1.1 200 OK
Content-Disposition: attachment; filename=applications-20250109-143022.zip
Content-Type: application/octet-stream

[Binary ZIP file content]

Example 2: Export from empty workspace

curl -X GET 'http://localhost/uib/api/v1/applications/export/all' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456' \
  -v

Response:

HTTP/1.1 204 No Content

No file is created or returned.

Example 3: Using wget with timestamped filename

wget --header="x-requested-by: Appsmith" \
     --header="Cookie: X-Bonita-API-Token=abc123; JSESSIONID=def456" \
     -O "backup-$(date +%Y%m%d).zip" \
     http://localhost/uib/api/v1/applications/export/all

Example 4: Verify exported contents

# List files in the ZIP
unzip -l applications.zip

# Extract to inspect
unzip applications.zip -d exported-apps/

# View an application's JSON
cat exported-apps/MyApplication.json | jq .

Important Notes

  • Partial Success: If some applications fail to export, the endpoint still returns 200 OK with successfully exported applications

  • Empty Workspace: Returns 204 NO_CONTENT if no applications exist

  • Streaming: The file is streamed to minimize memory usage

  • Temporary Files: A temporary ZIP is created and automatically cleaned up

  • Filename Timestamp: Format is YYYYMMDD-HHmmss for unique filenames

Performance Considerations

  • Large Workspaces: Exports may take time for many applications

  • Memory Usage: Optimized with streaming to minimize memory consumption

  • Concurrent Requests: Supported, but may impact server performance

Common Workflows

Complete Backup and Restore

# 1. List applications (optional verification)
curl -X GET 'http://localhost/uib/api/v1/applications/' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=xxx; JSESSIONID=xxx'

# 2. Export all applications (backup)
curl -X GET 'http://localhost/uib/api/v1/applications/export/all' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=xxx; JSESSIONID=xxx' \
  --output backup-$(date +%Y%m%d).zip

# 3. Delete all applications (cleanup)
curl -X DELETE 'http://localhost/uib/api/v1/applications/all' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=xxx; JSESSIONID=xxx'

# 4. Restore applications (import)
curl -X POST 'http://localhost/uib/api/v1/applications/import-bulk' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=xxx; JSESSIONID=xxx' \
  -F 'file=@backup-20250109.zip'

# 5. Verify restoration
curl -X GET 'http://localhost/uib/api/v1/applications/' \
  --header 'x-requested-by: Appsmith' \
  --header 'Cookie: X-Bonita-API-Token=xxx; JSESSIONID=xxx'

Error Handling

Common Error Codes

Status Code Possible Cause Resolution

400 Bad Request

Invalid file format, missing file, or invalid JSON

Verify file format (.json or .zip) and ensure valid JSON content

401 Unauthorized

Missing or invalid authentication cookies

Ensure X-Bonita-API-Token and JSESSIONID are valid and not expired

403 Forbidden

Missing x-requested-by header or insufficient permissions

Add the required header with value Appsmith and verify user permissions

404 Not Found

Invalid endpoint URL

Check the endpoint URL matches the API documentation

500 Internal Server Error

Server-side error (database, file system, or service failure)

Check server logs for detailed error messages. Verify system resources.

204 No Content

No data available (valid response, not an error)

For list/export: workspace is empty. For delete: nothing to delete.

206 Partial Content

Bulk import partially succeeded

Check response data to see which applications imported successfully

207 Multi-Status

Some deletions succeeded, others failed

Check response data to see which applications were deleted

Error Response Format

All error responses follow this structure:

{
  "responseMeta": {
    "status": 400,
    "success": false
  },
  "data": null,
  "errorDisplay": "Descriptive error message"
}

Security Considerations

Authentication and Authorization

  • Session-Based: All endpoints require valid session cookies

  • CSRF protection requires header x-requested-by: Appsmith to be present

  • Workspace Scoped: Operations are limited to the default workspace

  • Permission Checks: Users must have appropriate permissions on the workspace

Data Security

  • Sensitive Data: Exported JSON files may contain:

    • API keys and tokens

    • Database credentials

    • Connection strings

    • Business logic

  • Secure Storage: Store exported ZIP files securely

  • Access Control: Limit access to import/export endpoints

  • Audit Logging: All operations are logged for audit purposes

Best Practices

  1. Encrypt exports when storing or transferring

  2. Rotate credentials after exporting applications

  3. Review imported applications for security issues

  4. Limit access to these endpoints to administrators only

  5. Monitor logs for unauthorized access attempts

  6. Use HTTPS in production environments

Performance and Limitations

Performance Considerations

Operation Performance Impact Recommendations

List Applications

Low (database query)

Use full=false for faster responses when only names/IDs are needed

Delete All

Medium (depends on number of apps)

May take time for workspaces with many applications

Import Single

Medium (JSON parsing + publishing)

Suitable for individual application imports

Import Bulk

High (sequential processing)

For large ZIP files, expect longer processing times

Export All

Medium-High (depends on app count)

Streaming minimizes memory usage

Limitations

  • Workspace Scope: Only operates on the default workspace

  • File Formats: Only JSON descriptors and ZIP archives are supported

  • No Progress Tracking: Long-running operations don’t provide progress updates

  • Sequential Processing: Bulk imports process applications one at a time

  • Partial Failures: Some operations continue on errors (partial success possible)

  • Memory Constraints: Large files may impact server memory

  • Concurrent Operations: Multiple simultaneous requests may affect performance