The bridge API provides scripts running inside the QuickJS sandbox with controlled access to Kodexa platform capabilities. Every bridge method is gated by a permission that must be declared in the form’s bridge.permissions array. If a script calls a method whose permission is not granted, the call throws a Permission denied error.
The bridge is organized into five namespaces: kodexa.data for reading and writing data objects and attributes, kodexa.navigation for controlling the workspace view, kodexa.form for managing form-level state, kodexa.http for making API requests, and kodexa.log for diagnostic output.
This page is a complete reference. For a guided introduction to scripting and the bridge, see the Scripting guide.
Permission Table Every bridge method requires a specific permission. Declare the permissions your form needs in the bridge configuration:
{ "bridge" : { "permissions" : [ "data:read" , "data:write" , "navigation" , "formState" , "http:get" , "http:post" ] } }
Permission Methods data:readkodexa.data.getDataObjects, getDataObject, getAttributes, getAttribute, getTagMetadata, getTaxonomiesdata:writekodexa.data.setAttribute, addDataObject, deleteDataObjectnavigationkodexa.navigation.focusAttribute, scrollToNode, switchViewformStatekodexa.form.get, set, getNodeRefhttp:getkodexa.http.gethttp:postkodexa.http.post
kodexa.log methods (debug, warn, error) do not require any permission and are always available.
kodexa.data Methods for reading and writing data objects, attributes, and taxonomy metadata. These operate against the current workspace store.
getDataObjects Returns an array of data objects, optionally filtered by path or parent ID.
kodexa . data . getDataObjects ( filter ?: { path? : string ; parentId ?: string }): DataObject []
Parameter Type Required Description filterobjectNo Optional filter object filter.pathstringNo Filter by data object path (e.g., "invoice", "lineItem") filter.parentIdstringNo Filter by parent data object UUID
Permission : data:read{ "type" : "script" , "target" : "kodexa.log.debug('Invoices:', kodexa.data.getDataObjects({ path: 'invoice' }).length)" }
getDataObject Returns a single data object by UUID, or null if not found.
kodexa . data . getDataObject ( uuid : string ): DataObject | null
Parameter Type Required Description uuidstringYes The UUID of the data object
Permission : data:readgetAttributes Returns all attributes for a given data object.
kodexa . data . getAttributes ( dataObjectUuid : string ): DataAttribute []
Parameter Type Required Description dataObjectUuidstringYes The UUID of the data object
Permission : data:readgetAttribute Returns the value of a specific attribute on a data object, or undefined if not found.
kodexa . data . getAttribute ( dataObjectUuid : string , path : string ): any
Parameter Type Required Description dataObjectUuidstringYes The UUID of the data object pathstringYes The attribute path (e.g., "invoice/totalAmount")
Permission : data:read{ "type" : "script" , "target" : "kodexa.log.debug('Total:', kodexa.data.getAttribute(ctx.$item.uuid, 'invoice/totalAmount'))" }
setAttribute Sets the value of a specific attribute on a data object.
kodexa . data . setAttribute ( dataObjectUuid : string , path : string , value : any ): void
Parameter Type Required Description dataObjectUuidstringYes The UUID of the data object pathstringYes The attribute path valueanyYes The new value to set
Permission : data:write{ "type" : "script" , "target" : "kodexa.data.setAttribute(ctx.$item.uuid, 'invoice/status', 'approved')" }
addDataObject Creates a new data object as a child of the specified parent.
kodexa . data . addDataObject ( parentUuid : string , path : string ): DataObject
Parameter Type Required Description parentUuidstringYes The UUID of the parent data object pathstringYes The path (type) of the new data object (e.g., "lineItem")
Permission : data:writedeleteDataObject Deletes a data object by UUID.
kodexa . data . deleteDataObject ( uuid : string ): void
Parameter Type Required Description uuidstringYes The UUID of the data object to delete
Permission : data:writeReturns tag metadata for a given taxonomy path, or null if not found.
kodexa . data . getTagMetadata ( path : string ): TagMetadata | null
Parameter Type Required Description pathstringYes The taxonomy path (e.g., "invoice/totalAmount")
Permission : data:readgetTaxonomies Returns all taxonomies available in the current project.
kodexa . data . getTaxonomies (): Taxonomy []
Permission : data:readkodexa.navigation Methods for controlling the workspace view and navigating to specific elements.
focusAttribute Scrolls to and highlights a specific attribute in the document view.
kodexa . navigation . focusAttribute ( dataObjectUuid : string , attributePath : string ): void
Parameter Type Required Description dataObjectUuidstringYes The UUID of the data object attributePathstringYes The attribute path to focus
Permission : navigation{ "type" : "script" , "target" : "kodexa.navigation.focusAttribute(ctx.$item.uuid, 'invoice/invoiceNumber')" }
Scrolls the form view to a specific node identified by its ref name.
kodexa . navigation . scrollToNode ( ref : string ): void
Parameter Type Required Description refstringYes The ref value of the target UINode
Permission : navigationswitchView Switches the workspace to a different named view.
kodexa . navigation . switchView ( viewName : string ): void
Parameter Type Required Description viewNamestringYes The name of the view to switch to
Permission : navigationMethods for reading and writing form-level state that persists across script evaluations within the same session.
get Retrieves a value from the form state store.
kodexa . form . get ( key : string ): any
Parameter Type Required Description keystringYes The state key
Permission : formStateset Stores a value in the form state store.
kodexa . form . set ( key : string , value : any ): void
Parameter Type Required Description keystringYes The state key valueanyYes The value to store
Permission : formState{ "type" : "script" , "target" : "kodexa.form.set('selectedTab', 'details')" }
getNodeRef Returns a reference to a rendered UINode by its ref name, allowing programmatic prop updates.
kodexa . form . getNodeRef ( ref : string ): { setProps ( props : Record < string , any >) : void }
Parameter Type Required Description refstringYes The ref value of the target UINode
Permission : formState{ "type" : "script" , "target" : "kodexa.form.getNodeRef('statusLabel').setProps({ label: 'Updated!' })" }
kodexa.http Methods for making HTTP requests to the Kodexa API or external endpoints. The base URL defaults to "/api" but can be overridden in the bridge configuration.
get Performs an HTTP GET request and returns the parsed JSON response.
kodexa . http . get ( path : string ): Promise < any >
Parameter Type Required Description pathstringYes The URL path, appended to apiBaseUrl
Permission : http:get{ "type" : "script" , "target" : "kodexa.http.get('/document-stores/' + ctx.storeId).then(r => kodexa.log.debug(r))" }
post Performs an HTTP POST request with a JSON body and returns the parsed JSON response.
kodexa . http . post ( path : string , body : any ): Promise < any >
Parameter Type Required Description pathstringYes The URL path, appended to apiBaseUrl bodyanyYes The request body, serialized as JSON
Permission : http:postkodexa.log Diagnostic logging methods that output to the browser developer console. These methods do not require any permission.
debug Logs a debug message.
kodexa . log . debug ( ... args : any []): void
Output format: [DataFormV2] ...args
warn Logs a warning message.
kodexa . log . warn ( ... args : any []): void
error Logs an error message.
kodexa . log . error ( ... args : any []): void
Example { "events" : { "change" : { "type" : "script" , "target" : "kodexa.log.debug('Attribute changed:', ctx.$item?.uuid, 'new value:', ctx.newValue)" } } }
Common Patterns Read-Only Data Display For forms that only display data, grant minimal permissions:
{ "bridge" : { "permissions" : [ "data:read" ] } }
For forms that allow editing and support click-to-navigate:
{ "bridge" : { "permissions" : [ "data:read" , "data:write" , "navigation" , "formState" ] } }
For forms that call external APIs:
{ "bridge" : { "permissions" : [ "data:read" , "http:get" , "http:post" ], "apiBaseUrl" : "/api" } }
Next Steps
Data Binding How bindings and the data context work
Event Handling Event types and handler configuration
