> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic API Operations

> Use kdx run to discover and execute resource-specific Kodexa API operations beyond standard get, describe, apply, and delete commands.

## 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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
kdx api-resources --refresh
```

## Executing An Operation

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

```bash theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
kdx document-family data <document-family-id> -o extracted.json
```

### Activities

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
kdx project create --template <org/template> --org <org-slug> --name <project-name>
```

### Data Definitions

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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
kdx run <resource-type>
```

Then refresh discovery if needed:

```bash theme={null}
kdx api-resources --refresh
```

### Missing Required Parameter

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

```bash theme={null}
kdx run document-families get-document-families --id <document-family-id>
```

### Invalid JSON Body

Validate the body with `jq` before passing it:

```bash theme={null}
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 |