Dynamic API Operations

Overview

kdx run exposes resource-specific API operations discovered from the platform OpenAPI specification. Use it when you need an operation that is not covered by a stable top-level command.

kdx run <resource-type> [operation] [flags]

Examples of good kdx run use cases:

Inspect operations available for activities, activity-plans, document-families, or projects.
Call a document-family export, external-data, label, touch, or status endpoint.
Run administrative project operations exposed by the current platform.
Prototype an integration before turning it into application code.

How Discovery Works

List available operations for a resource:

kdx run document-families
kdx run activities
kdx run projects

The operation list comes from the connected environment. If an operation is missing after a platform upgrade, refresh the discovery cache:

kdx api-resources --refresh

Executing An Operation

Path and query parameters are passed as dynamic flags. Request bodies are passed as JSON with --body.

kdx run <resource-type> <operation> --id <id> --body '{"key":"value"}'

Parameter handling:

Parameter type	How to pass it
Path parameter	`--id <value>`, `--ref <value>`, or the parameter name shown by `kdx run <resource>`
Query parameter	`--format json`, `--includeIds true`, `--filter "slug:'invoice'"`
Request body	`--body '{"statusId":"..."}'`
Output format	`-o json`, `-o yaml`, `-o table`

Common Operations

Document Families

# List available document-family operations
kdx run document-families

# Get document-family details
kdx run document-families get-document-families --id <document-family-id>

# Get extracted data
kdx run document-families data --id <document-family-id> --format json

# List external data keys
kdx run document-families external-data-keys --id <document-family-id>

# Get one external data value
kdx run document-families external-data-get --id <document-family-id> --key transformed_objects

# Get processing steps for operational review
kdx run document-families steps --id <document-family-id>

# Touch a document family to emit a platform event
kdx run document-families touch --id <document-family-id>

For routine data export, prefer the stable wrapper:

kdx document-family data <document-family-id> -o extracted.json

Activities

# Discover Activity operations exposed by this environment
kdx run activities

# Get an Activity run; current Activity APIs include materialized step data
kdx run activities get-activities --id <activity-id> -o json

Use activities when you need to inspect the business process run itself. Use activity-plans when you need to inspect the reusable workflow definition.

Projects

# Discover project-specific operations
kdx run projects

# Get project resources or project-specific forms when exposed by the API
kdx run projects get-apiprojects-resources --id <project-id>
kdx run projects get-apiprojects-dataforms --id <project-id>

For creating a project from a template, prefer:

kdx project create --template <org/template> --org <org-slug> --name <project-name>

Data Definitions

Use the current data-definitions resource name for new work:

kdx run data-definitions
kdx get data-definitions
kdx describe data-definition invoice-data

Some servers still expose compatibility aliases for older names. New documentation and new metadata should use data-definition and data-definitions.

Service Bridges

kdx run service-bridges
kdx get service-bridges

For Activity workflow calls, prefer defining a BRIDGE_CALL step in an Activity Plan. Use kdx run for inspection, troubleshooting, and one-off administrative calls exposed by the API.

Output And Scripting

# Get Activity status for scripting
kdx run activities get-activities --id "$ACTIVITY_ID" -o json | jq '.status'

# Export external data for another tool
kdx run document-families external-data-get \
  --id "$DOCUMENT_FAMILY_ID" \
  --key transformed_objects \
  -o json > transformed-objects.json

When To Use `run`

Use kdx run when:

You need an API operation that is not modeled as a top-level CLI command.
You want to inspect what the current server supports.
You are building an automation and want to verify the API call shape.

Use a stable command when it exists:

Need	Prefer
List or inspect resources	`kdx get`, `kdx describe`
Create or update YAML resources	`kdx apply -f`
Validate YAML	`kdx validate -f`
Export document-family data	`kdx document-family data`
Download KDDB content	`kdx document-family content download`
Version metadata	`kdx sync`

Troubleshooting

Operation Not Found

List the operations exposed by the current environment:

kdx run <resource-type>

Then refresh discovery if needed:

kdx api-resources --refresh

Missing Required Parameter

The operation list shows required path and body parameters. Add the corresponding dynamic flag:

kdx run document-families get-document-families --id <document-family-id>

Invalid JSON Body

Validate the body with jq before passing it:

echo '{"statusId":"..."}' | jq .
kdx run document-families status --id <document-family-id> --body '{"statusId":"..."}'

Resource Name Drift

Use current resource names in new commands and docs:

Current name	Notes
`data-definitions`	Current name for business data models
`activity-plans`	Reusable workflow definitions
`activities`	Running workflow instances
`task-templates`	Human work templates used by Activity `CREATE_TASK` steps

Getting Started

Core Operations

Sync & GitOps

Operational Commands

Document Commands

Overview

How Discovery Works

Executing An Operation

Common Operations

Document Families

Activities

Projects

Data Definitions

Service Bridges

Output And Scripting

When To Use `run`

Troubleshooting

Operation Not Found

Missing Required Parameter

Invalid JSON Body

Resource Name Drift

​Overview

​How Discovery Works

​Executing An Operation

​Common Operations

​Document Families

​Activities

​Projects

​Data Definitions

​Service Bridges

​Output And Scripting

​When To Use run

​Troubleshooting

​Operation Not Found

​Missing Required Parameter

​Invalid JSON Body

​Resource Name Drift

Overview

How Discovery Works

Executing An Operation

Common Operations

Document Families

Activities

Projects

Data Definitions

Service Bridges

Output And Scripting

When To Use `run`

Troubleshooting

Operation Not Found

Missing Required Parameter

Invalid JSON Body

Resource Name Drift