Skip to content

DXL extension API endpoints

Important

The DXL Extension API is experimental and is provided for users to try and evaluate. It is not yet supported for production use.

The DXL Extension API is disabled by default. To enable it, see Enable CalDav, CardDav, and DXL extension APIs.

For any feedback, questions, or issues, you may post them in the OpenNTF Discord channel link image.

The following tables show the DXL extension API endpoints, including their HTTP method, path, required ACL, and purpose.

Tip

All endpoints use the standard HCL Domino REST API authentication model, which requires a JWT bearer token. The interactive Swagger UI is available at http://<host>:8880/openapi/swagger-ui/?url=/api/dxl/schema/openapi.dxlext.json.

Database properties

GET /database

Returns the database properties, including the title, replica ID, file path, design template name, and launch settings (Notes client and web browser) in JSON format.

/api/dxl/database

Reader

Sample request:

GET /api/dxl/database?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
"replicaId": "AABBCCDD00112233",
"title": "My Application",
"filePath": "apps/myapp.nsf",
"designTemplate": "",
"launchSettings": {
    "notes": {
       "whenOpened": "openframeset",
       "framesetName": "MainFrameset"
    }
  }
}

Note

The launchSettings object is extracted by exporting the database icon note as DXL. If the database has no explicit launch settings, launchSettings will be an empty object. If the DXL parse fails, a parseError field is included but basic fields, such as title and replicaId, are always returned.

PUT /database

Updates the database title and launch settings. Only the fields included in the request are modified, while omitted fields remain unchanged.

/api/dxl/database

Manager

Sample request:

PUT /api/dxl/database?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>
Content-Type: application/json

{
    "title": "My Application v2",
    "notes": {
        "whenOpened": "openframeset",
        "framesetName": "MainFrameset"
    }
}

Notes client whenOpened values

Value Effect
openaboutdocument Show About document
openframeset Open a specific frameset
restorelastview Restore the last-used view
openfirstdocument Open the first document
openpage Open a named page
openxpage Open an XPage
opencompapp Open a composite application

Web whenOpened values:

  • page
  • view
  • url
  • doclink

Sample response:

{
"status": "ok",
"log": "<DXLImportLog/>"
}

Design summary

GET /designsummary

Returns every design elements in the database, grouped by type. Each element includes its name, aliases, UNID, and note ID. No DXL is returned, keeping the response lightweight. Design element types with no entries are omitted.

/api/dxl/designsummary

Reader

Sample request:

GET /api/dxl/designsummary?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "database": "My Application",
  "replicaId": "85257ABC00123DEF",
  "totalCount": 42,
  "types": {
    "form": {
      "count": 3,
      "elements": [
        { "name": "MainForm", "aliases": ["MF"], "unid": "AABBCCDD...", "noteId": 256 },
        { "name": "SubForm",  "unid": "11223344...", "noteId": 260 },
        { "name": "Feedback", "aliases": ["FB", "FeedbackForm"], "unid": "55667788...", "noteId": 264 }
      ]
    },
    "view": {
      "count": 2,
      "elements": [
        { "name": "AllDocuments", "aliases": ["All"], "unid": "DDEE0011...", "noteId": 512 },
        { "name": "ByAuthor", "unid": "FFAA2233...", "noteId": 516 }
      ]
    }
  }
}

Note

Elements without aliases omit the aliases field entirely. The database and replicaId fields make the response self-describing, which is useful when working with multiple databases.


Design elements

GET /{type}

Lists every design element of the requested type with name, UNID, and note ID.

/api/dxl/{type}

Reader

Sample request:

GET /api/dxl/form?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "type": "form",
  "count": 3,
  "elements": [
    { "name": "MainForm", "unid": "AABBCCDD...", "noteId": 256 },
    { "name": "SubForm",  "unid": "11223344...", "noteId": 260 }
  ]
}

GET /{type}/{name}

Exports a single design element as DXL wrapped in a JSON response.

/api/dxl/{type}/{name}

Reader

Sample request:

GET /api/dxl/form/MainForm?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "type": "form",
  "name": "MainForm",
  "unid": "AABBCCDD00112233AABBCCDD00112233",
  "noteId": 256,
  "dxl": "<form name='MainForm' ...>...</form>"
}

Note

The dxl field contains the raw element DXL without an XML declaration or DOCTYPE.

PUT /{type}/{name}

Imports a single design element from raw DXL. The element is created if it does not exist, or it is replaced if it already does. The DXL body must be the element fragment, and not a full <database> document. The imported element is automatically signed after import.

When the calling user is authenticated via a method compatible with ID Vault, such as SAML or OAuth, the note is signed with their own identity to preserve an audit trail of who deployed the element. When the user's ID cannot be retrieved, the note is signed with the server ID instead. Either way, agents and script libraries are immediately runnable.

/api/dxl/{type}/{name}

Designer

Sample request:

PUT /api/dxl/form/MainForm?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>
Content-Type: text/xml

<form name='MainForm' xmlns='http://www.lotus.com/dxl'>
...
</form>

Note

Do not include an <?xml ...?> declaration or DOCTYPE at the top of the body. The importer wraps your fragment in a <database> element before parsing, which makes an XML declaration illegal and causes a fatal parse error. For more information, see DXL format.

Sample response:

{
  "status": "ok",
  "importedCount": 1,
  "log": "<DXLImportLog>...</DXLImportLog>"
}

DELETE /{type}/{name}

Permanently removes the named element from the database.

/api/dxl/{type}/{name}

Designer

Sample request:

DELETE /api/dxl/form/MainForm?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "deleted": true,
  "type": "form",
  "name": "MainForm",
  "unid": "AABBCCDD00112233AABBCCDD00112233"
}

Note

Returns a 404 Not Found response if the specified design element does not exist.

Supported {type} values

Type DbDesign method DocumentClass
form getForm() / getForms() FORM
subform getSubform() / getSubforms() FORM
view getView() / getViews() VIEW
folder getFolder() / getFolders() VIEW
frameset getFrameset() / getFramesets() FORM
page getPage() / getPages() FORM
agent getAgent() / getAgents() FILTER
scriptlibrary getScriptLibrary() / getScriptLibraries() FILTER
sharedfield getSharedField() / getSharedFields() FIELD
sharedcolumn getSharedColumn() / getSharedColumns() FORM
outline getOutline() / getOutlines() FORM
navigator getNavigator() / getNavigators() FORM
imageresource getImageResource() / getImageResources() FORM
fileresource getFileResource() / getFileResources() FORM

Framesets

Framesets have two additional endpoints that work with a structured JSON representation of the frameset layout instead of raw DXL, making them easier to create and parse programmatically.

GET /frameset/{name}/layout

Returns the frameset as a structured JSON tree.

/api/dxl/frameset/{name}/layout

Reader

Sample request:

GET /api/dxl/frameset/MainFrameset/layout?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "name": "MainFrameset",
  "orientation": "rows",
  "sizes": ["50px", "1", "30px"],
  "content": [
    {
      "type": "frame",
      "name": "Header",
      "target": { "kind": "page", "name": "HeaderPage" }
    },
    {
      "type": "frame",
      "name": "Content",
      "target": { "kind": "view", "name": "AllDocuments" },
      "scrolling": "auto"
    },
    {
      "type": "frame",
      "name": "Footer",
      "target": { "kind": "url", "url": "/footer.html" }
    }
  ]
}

Note

  • The value of orientation is rows if frames are stacked vertically, or columns if frames are side by side.
  • sizes has one entry per frame. A plain number like "1" means "take remaining space."
  • Returns a 404 Not Found response if the frameset does not exist.

PUT /frameset/{name}/layout

Converts the JSON layout to DXL and imports it, or creates the frameset from the JSON spec if it does not exist.

/api/dxl/frameset/{name}/layout

Designer

Sample request:

PUT /api/dxl/frameset/MainFrameset/layout?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>
Content-Type: application/json

{
  "orientation": "columns",
  "sizes": ["239px", "1"],
  "content": [
    {
      "type": "frame",
      "name": "Nav",
      "target": { "kind": "view", "name": "NavView" }
    },
    {
      "type": "frame",
      "name": "Main",
      "target": { "kind": "view", "name": "AllDocs" },
      "scrolling": "auto",
      "targetFrame": "Main"
    }
  ]
}

Note

  • The frame target kinds are page, view, form, frameset, and url.
  • For nested framesets, include a content item of "type": "frameset" with its own orientation, sizes, and content array.

Sample response:

{
  "status": "ok",
  "importedCount": 1,
  "log": "<DXLImportLog/>"
}

Outlines

Outlines have two additional endpoints that work with a structured JSON representation of the entry hierarchy instead of raw DXL. This makes it straightforward to add, reorder, or rename outline entries without having to modify the DXL directly. This is particularly useful in hybrid-mode workflows where an outline is copied from a reference database and its view targets need to be updated.

GET /outline/{name}/entries

Returns the outline's entry hierarchy as a label/target/children tree. Supports both flat level-based and nested DXL formats, including the imageref properties.

/api/dxl/outline/{name}/entries

Reader

Sample request:

GET /api/dxl/outline/MainOutline/entries?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "name": "MainOutline",
  "entries": [
    {
      "label": "All Documents",
      "frame": "NotesView",
      "target": { "kind": "view", "name": "All Documents" }
    },
    {
      "label": "Administration",
      "children": [
        {
          "label": "Pending",
          "frame": "NotesView",
          "target": { "kind": "view", "name": "Pending Approval" }
        }
      ]
    }
  ]
}

Note

Returns a 404 Not Found response if the outline does not exist.

PUT /outline/{name}/entries

Converts the JSON entry tree to flat DXL with level attributes for hierarchy and imports it. Supports nested children arrays and optional imageref per entry. Creates the outline if it does not exist, or replaces it entirely if it does.

/api/dxl/outline/{name}/entries

Designer

Sample request:

PUT /api/dxl/outline/MainOutline/entries?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>
Content-Type: application/json

{
  "entries": [
    {
      "label": "All Documents",
      "frame": "NotesView",
      "target": { "kind": "view", "name": "All Documents" }
    },
    {
      "label": "Administration",
      "children": [
        {
          "label": "Pending",
          "frame": "NotesView",
          "target": { "kind": "view", "name": "Pending Approval" }
        }
      ]
    }
  ]
}

Entry fields

Field Type Description
label string (required) Display text for the entry
frame string Target frame that opens when a link from this entry is clicked
alias string Alternate name
expanded boolean Whether the entry is expanded by default
target object Where the entry navigates to (see below)
children array Nested entries — supports any depth

Target object

Field Description
kind One of view, form, page, frameset, navigator, url
name Design element name (all kinds except url)
url URL string (kind url only)

Sample response:

{
  "status": "ok",
  "importedCount": 1,
  "log": "<DXLImportLog/>"
}

DXL export

GET /export

Exports design elements from the database as a DXL <database> document fully or filtered by type.

/api/dxl/export

Reader

Sample request:

Full export: includes database properties, ACL, and all design elements

GET /api/dxl/export?nsfPath=apps/myapp.nsf&full=true
Authorization: Bearer <token>

Filtered export by type: exports only the listed element types

GET /api/dxl/export?nsfPath=apps/myapp.nsf&types=form,view
Authorization: Bearer <token>

Filtered export with database properties: adds include=properties

GET /api/dxl/export?nsfPath=apps/myapp.nsf&types=form&include=properties

Sample response:

For full export that includes database properties, ACL, and all design elements

{
  "mode": "full",
  "dxl": "<database xmlns='http://www.lotus.com/dxl'>...</database>"
}

For filtered export by type that exports only the listed element types

{
  "mode": "filtered",
  "types": ["form", "view"],
  "elementCount": 12,
  "dxl": "<database xmlns='http://www.lotus.com/dxl'>...</database>"
}

For filtered export with database properties that add include=properties

{
  "mode": "filtered",
  "types": ["form"],
  "elementCount": 4,
  "dxl": "<database ...>...</database>",
  "propertiesDxl": "<database ...>...</database>"
}

Note

The propertiesDxl field is a separate DXL document containing only database-level properties (useful for replicating launch settings without copying design elements).


DXL validate

POST /validate

Performs a two-pass validation: first verifies that the XML is well-formed, then runs the importer in dry-run mode without writing any changes. Use this endpoint before starting an asynchronous import operation.

/api/dxl/validate

Reader

Sample request:

POST /api/dxl/validate?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>
Content-Type: application/json

{
  "dxl": "<database xmlns='http://www.lotus.com/dxl'><form name='Test'>...</form></database>"
}

Note

The DXL must be wrapped in a <database> element. A leading UTF-8 BOM is accepted and stripped automatically.

Sample response:

Valid response

{
  "valid": true,
  "errors": [],
  "warnings": []
}

Invalid response

{
  "valid": false,
  "errors": ["Root element is not <database>"],
  "warnings": []
}

DXL import (Async)

Large DXL imports run asynchronously. Start the import by sending a POST /import request, then poll GET /import/{jobId} until the job completes.

POST /import

Starts an async DXL import job.

Note

Before the import begins, the DXL is automatically preprocessed. Any leading UTF-8 byte order mark (BOM) and whitespace before the first < character are removed, allowing imports to succeed even with files exported from, for example, PowerShell.

/api/dxl/import

Designer

Sample request:

POST /api/dxl/import?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>
Content-Type: application/json

{
  "dxl": "<database xmlns='http://www.lotus.com/dxl'>...</database>",
  "options": {
    "designOption": "replaceElseCreate",
    "documentsOption": "ignore",
    "replaceDbProperties": false
  }
}

Options

Field Default Description
designOption replaceElseCreate How to handle existing design elements
documentsOption ignore How to handle documents in the DXL
replaceDbProperties false Whether to update database-level properties

Option values:

  • replaceElseCreate
  • replaceElseIgnore
  • ignoreElseCreate
  • create
  • ignore

Sample response:

{
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "running",
  "nsfPath": "apps/myapp.nsf"
}

GET /import/{jobId}

Returns the current status of an async DXL import job.

/api/dxl/import/{jobId}

Reader

Sample request:

GET /api/dxl/import/f47ac10b-58cc-4372-a567-0e02b2c3d479?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

Status: running

{
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "running"
}

Status: complete

{
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "complete",
  "importedCount": 14,
  "log": "<DXLImportLog>...</DXLImportLog>"
}

Status: error

{
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "error",
  "error": "DXL is blank"
}

Note

Returns a 404 Not Found response if the job ID is unknown or has expired.


ACL management

GET /acl

Returns all ACL entries and the list of roles defined in the database.

/api/dxl/acl

Manager

Sample request:

GET /api/dxl/acl?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "entries": [
    {
      "name": "-Default-",
      "level": "NOACCESS",
      "type": "UNSPECIFIED",
      "roles": [],
      "flags": []
    },
    {
      "name": "CN=Alice Example/O=MyOrg",
      "level": "EDITOR",
      "type": "PERSON",
      "roles": ["[Approver]"],
      "flags": ["NODELETE_DOCUMENT"]
    }
  ],
  "roles": ["[Approver]", "[Admin]"]
}

Note

The roles array lists every role defined in the ACL, whether assigned or not.

PUT /acl/entry/{aclEntryName}

Creates the named ACL entry if it does not exist, or replaces it with the supplied level, roles, type, and flags.

/api/dxl/acl/entry/{aclEntryName}

Manager

Sample request:

PUT /api/dxl/acl/entry/CN%3DAlice%20Example%2FO%3DMyOrg?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>
Content-Type: application/json

{
  "level": "EDITOR",
  "type": "PERSON",
  "roles": ["[Approver]"],
  "flags": ["NODELETE_DOCUMENT"]
}

Note

  • URL-encode the entry name (slashes, equals signs, spaces).
  • level is required while all other fields are optional and default to empty.
  • Roles must already be defined in the ACL. If a role does not exist, the request fails with a 400 Bad Request error.

Sample response:

The response is the saved entry as JSON.

DELETE /acl/entry/{aclEntryName}

Removes the named entry from the ACL.

Note

The entries -Default- and LocalDomainServers are protected and cannot be removed.

/api/dxl/acl/entry/{aclEntryName}

Manager

Sample request:

DELETE /api/dxl/acl/entry/CN%3DAlice%20Example%2FO%3DMyOrg?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "deleted": true,
  "name": "CN=Alice Example/O=MyOrg"
}

Help documents

Every NSF contains two special notes intended for user-facing documentation:

Document NoteID Purpose
About 0xFFFF0002 Shown when the database opens if configured to display in the launch settings
Using 0xFFFF0100 Available from Help → Using This Database in the Notes client

Use the following endpoints to read, replace, or delete either document programmatically.

Note

The docType path parameter accepts the values about and using. The values are case-insensitive.

GET /helpdoc/{docType}

Returns the database's About or Using help document as DXL.

/api/dxl/helpdoc/{docType}

Reader

Sample request:

GET /api/dxl/helpdoc/about?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "type": "about",
  "unid": "86E3F50B2B8A4D...",
  "noteId": "0xFFFF0002",
  "dxl": "<document xmlns='http://www.lotus.com/dxl' ...>...</document>"
}

Note

The dxl field contains the full DXL representation of the help document, including its rich-text body.

PUT /helpdoc/{docType}

Creates or replaces the database's About or Using help document.

/api/dxl/helpdoc/{docType}

Designer

Sample request:

PUT /api/dxl/helpdoc/about?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>
Content-Type: text/xml

<helpaboutdocument xmlns='http://www.lotus.com/dxl'>
  <body>
    <richtext>
      <pardef id='1'/>
      <par def='1'>Welcome to My Application.</par>
    </richtext>
  </body>
</helpaboutdocument>

Note

The DXL element name must match the document type:

  • <helpaboutdocument> for About
  • <helpusingdocument> for Using.

The easiest approach is to GET the existing document, modify the rich text content, and PUT it back.

Sample response:

{
  "type": "about",
  "status": "ok",
  "importedCount": 1,
  "log": "<DXLImportLog .../>"
}

Note

The imported note is automatically signed with the calling user's identity when it is available via ID Vault, or with the server ID.

DELETE /helpdoc/{docType}

Removes the database's About or Using help document permanently.

/api/dxl/helpdoc/{docType}

Designer

Sample request:

DELETE /api/dxl/helpdoc/about?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "deleted": true,
  "type": "about",
  "unid": "86E3F50B2B8A4D...",
  "noteId": "0xFFFF0002"
}

Note

Returns a 404 Not Found response if the help document does not exist in the database.


Database icon note

Every NSF includes a special icon note (DocumentClass.ICON, NoteID 0xFFFF0010) that controls the database's workspace icon in the Notes client. This icon note is separate from the $DBIcon image resource, which stores the higher-resolution database icon used by Domino Designer and supported web clients.

To ensure the database icon displays consistently across supported clients, both the icon note and the $DBIcon image resource must be present.

GET /dbicon

Returns the database icon note as DXL.

/api/dxl/dbicon

Reader

Sample request:

GET /api/dxl/dbicon?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "type": "dbicon",
  "unid": "3228AB6D79FC1C61...",
  "noteId": "0xFFFF0010",
  "dxl": "<iconnote xmlns='http://www.lotus.com/dxl' ...>...</iconnote>"
}

Note

The dxl field contains the full icon note DXL, which includes the icon bitmap and the database launch settings.

PUT /dbicon

Creates or replaces the database icon note.

/api/dxl/dbicon

Designer

Sample request:

PUT /api/dxl/dbicon?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>
Content-Type: text/xml

<iconnote xmlns='http://www.lotus.com/dxl'>
  <png>iVBORw0KGgoAAAANSUhEUg...</png>
</iconnote>

Tip

The recommended approach is to GET the icon note from a working database and PUT it into the target database.

Launch settings preservation

The icon note also stores the database launch settings (<launchsettings>), such as whether the database opens to a frameset or page. When the icon is replaced, the server automatically snapshots the current launch settings before the import and restores them after the import. This ensures that replacing the icon does not accidentally reset the database's launch configuration.

Sample response:

{
  "type": "dbicon",
  "status": "ok",
  "importedCount": 1,
  "propsRestored": true,
  "log": "<DXLImportLog .../>"
}

Note

  • The propsRestored field indicates whether the database launch settings were preserved and restored during the icon replacement operation. If its value is true, the launch settings existed and were successfully restored. If its value is false, no launch settings were available to restore, or the settings could not be restored because the snapshot failed.
  • The imported note is automatically signed with the calling user's identity when it is available via ID Vault, or with the server ID.

DELETE /dbicon

Removes the database icon note permanently.

/api/dxl/dbicon

Designer

Sample request:

DELETE /api/dxl/dbicon?nsfPath=apps/myapp.nsf
Authorization: Bearer <token>

Sample response:

{
  "deleted": true,
  "type": "dbicon",
  "unid": "3228AB6D79FC1C61...",
  "noteId": "0xFFFF0010"
}

Note

Returns a 404 Not Found response if the icon note does not exist in the database. After deletion, the database reverts to the default Domino icon on the Notes workspace.