Designer API 🟡 BETA

UI designer for visual bot dialog creation — load, edit, validate, and export .gbdialog files through a visual interface.

Base URL

/api/ui/designer

Authentication

All endpoints require a valid session token via Authorization: Bearer <token> header.

Endpoints

List Files

GET /api/ui/designer/files

Lists all dialog files available in the designer.

Response:

{
  "files": [
    {
      "name": "start.bas",
      "path": "start.bas",
      "size": 512,
      "modified_at": "2025-06-04T10:00:00Z",
      "bot": "default"
    },
    {
      "name": "check_inventory.bas",
      "path": "tools/check_inventory.bas",
      "size": 1024,
      "modified_at": "2025-06-03T14:00:00Z",
      "bot": "default"
    },
    {
      "name": "tables.bas",
      "path": "tables.bas",
      "size": 256,
      "modified_at": "2025-06-01T08:00:00Z",
      "bot": "default"
    }
  ],
  "directories": [
    "tools/",
    "handlers/",
    "schedulers/"
  ]
}

Load File

GET /api/ui/designer/load

Loads a file’s content for editing.

Response:

{
  "bot": "default",
  "path": "start.bas",
  "content": "ADD SUGGESTION \"Check inventory\"\nADD SUGGESTION \"Create report\"\nTALK \"Hello! How can I help?\"",
  "modified_at": "2025-06-04T10:00:00Z",
  "size": 128,
  "line_count": 3,
  "syntax_valid": true
}

Save File

POST /api/ui/designer/save

Saves content to a file in the bot’s dialog directory.

Request Body:

{
  "bot": "default",
  "path": "tools/check_inventory.bas",
  "content": "items = GET FROM inventory WHERE quantity < 10\nIF COUNT(items) = 0 THEN\n    TALK \"All items well stocked!\"\nELSE\n    response = \"Low stock items:\\n\"\n    FOR EACH item IN items\n        response = response + \"- \" + item.name + \": \" + item.quantity + \"\\n\"\n    NEXT\n    TALK response\nEND IF",
  "validate": true
}

Response:

{
  "success": true,
  "bot": "default",
  "path": "tools/check_inventory.bas",
  "size": 312,
  "line_count": 10,
  "syntax_valid": true,
  "saved_at": "2025-06-04T11:00:00Z"
}

Validate File

POST /api/ui/designer/validate

Validates BASIC script syntax without saving.

Request Body:

{
  "bot": "default",
  "content": "TALK \"Hello\"\nINVALID_KEYWORD \"test\"",
  "filename": "test.bas"
}

Response (errors):

{
  "valid": false,
  "errors": [
    {
      "line": 2,
      "column": 1,
      "message": "Unknown keyword: INVALID_KEYWORD",
      "severity": "error"
    }
  ],
  "warnings": []
}

Response (success):

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "line": 5,
      "column": 1,
      "message": "Unused variable 'temp'",
      "severity": "warning"
    }
  ]
}

Export File

GET /api/ui/designer/export

Exports a compiled .ast file for a BASIC script.

Response:

Returns the file as a download:

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="check_inventory.ast"

The response body contains the compiled bytecode. For json format, returns:

{
  "source": "check_inventory.bas",
  "format": "ast",
  "compiled_at": "2025-06-04T11:00:00Z",
  "size_bytes": 1024,
  "checksum": "sha256:abc123..."
}

Dialog Management

GET /api/ui/designer/dialogs

Lists all available dialog templates.

Response:

{
  "dialogs": [
    {
      "id": "dlg_001",
      "name": "Welcome Dialog",
      "category": "onboarding",
      "description": "Initial greeting with suggestion buttons",
      "bot": "default",
      "file_count": 1,
      "created_at": "2025-06-01T08:00:00Z"
    },
    {
      "id": "dlg_002",
      "name": "Inventory Checker",
      "category": "tools",
      "description": "Checks inventory levels and reports low stock",
      "bot": "default",
      "file_count": 2,
      "created_at": "2025-06-02T10:00:00Z"
    }
  ]
}

POST /api/ui/designer/dialogs

Creates a new dialog from a template.

Request Body:

{
  "name": "Customer Lookup",
  "bot": "default",
  "category": "tools",
  "description": "Search customers by name or email",
  "files": [
    {
      "path": "tools/customer_lookup.bas",
      "content": "HEAR \"Enter customer name or email\" AS query\nresults = FIND query IN customers\nIF COUNT(results) = 0 THEN\n    TALK \"No customers found.\"\nELSE\n    FOR EACH c IN results\n        TALK c.name + \" - \" + c.email\n    NEXT\nEND IF"
    }
  ]
}

Response:

{
  "id": "dlg_003",
  "name": "Customer Lookup",
  "bot": "default",
  "category": "tools",
  "file_count": 1,
  "created_at": "2025-06-04T12:00:00Z"
}

GET /api/ui/designer/dialogs/:id

Retrieves a dialog with all its files.

Response:

{
  "id": "dlg_002",
  "name": "Inventory Checker",
  "category": "tools",
  "description": "Checks inventory levels and reports low stock",
  "bot": "default",
  "files": [
    {
      "path": "tools/check_inventory.bas",
      "size": 312,
      "line_count": 10,
      "syntax_valid": true,
      "modified_at": "2025-06-03T14:00:00Z"
    },
    {
      "path": "tools/restock.bas",
      "size": 256,
      "line_count": 8,
      "syntax_valid": true,
      "modified_at": "2025-06-03T14:30:00Z"
    }
  ],
  "created_at": "2025-06-02T10:00:00Z"
}

Designer File Types

Response Codes

See Also

• File Operations — raw file management
• Compilation — BASIC compilation pipeline
• Tool Definition — how tools are registered
• Storage API — Drive (MinIO) integration