CLI Support in API Studio

APIM CLI provides the Command Line Interface (CLI) support for API Management. In API Studio you can build, deploy, and test the deployed assets by using APIM CLI. These following sections describe operations that you can do such as build, deploy, and test by using the CLI with some examples.

Installing APIM CLI

Make sure that you have Node.js installed.

Run the following command in the command line to install APIM CLI.

npm install -g @apistudio/apim-cli

Commands in APIM CLI

• apic build
  • Building a single project
  • Building multiple projects
  • Building all projects in the local directory
  • Building an API
  • Building a project without --output
  • Building specific assets (Partial Build)
  • Building with asset type filter
• apic deploy
  • Deploying a single project
  • Deploying multiple projects
  • Deploying all projects
  • Deploying an API
• apic test
  • Testing a single project
  • Testing multiple projects
  • Testing all projects
  • Testing an API
  • Testing a project by overwriting the environment configuration
  • Testing a project using endpoints
  • Saving test results in different formats
• apic tryout
  • Trying out an API with direct endpoint
  • Trying out an API with API name
  • Trying out an API with path parameter
  • Trying out an API with custom headers and body
• apic lint
  • Linting a single project
  • Linting multiple projects
  • Linting all projects
  • Linting an API
  • Linting with dependencies
• apic validate
  • Validating a single project
  • Validating multiple projects
  • Validating all projects
• apic create
• apic update
• apic delete
• apic list
• apic schema
  • apic schema list
  • apic schema get
• apic help

apic build

This operation builds and archives the specified project assets. APIs can have external dependencies referenced, hence when you build a project it includes all these references provided in the local folder.

Syntax

apic build [options][projects]

Specifies the projects in the local folder you want to build. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available options for the apic build command and their descriptions.

Options Description

| Command | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | -l, --localDir | Path of the local folder of the specified studio projects. This argument is mandatory. | | -a, --all | Use --all to include all projects in the given local directory. If you do not want to build all projects in the given local directory, then specify the project name that is required. | | -n, --names | Specify the API kind in the format namespace:apiname:version. You can provide multiple asset names as comma-separated entries. Studio supports only API assets. | | -f, --filter-assets | Build specific assets within a project using asset references in the format namespace:name:version. You can provide multiple asset references as comma-separated entries. See Partial Build documentation for details. | | -t, --asset-type | Filter assets by type: ai or api. Only top-level assets matching the specified type will be included in the build. AI assets include API (with domain=ai-platform), Product (with AI APIs), MCPServer, and LLMProvider. API assets include API (without domain or domain=api), Product (with API APIs), and GlobalPolicy. Common assets (Quota, PolicySequence, etc.) are always included when top-level assets exist. | | -o, --output build_output_path | Provide the name and path where the output zip file should be stored. If you do not specify the path, the built project is stored in the directory from where you run the command. | | -d, --debug | Enables the debug mode. | | -h, --help | Displays help for the build command. |

1. Building a single project

Syntax

apic build Projectname --localDir local_dir_path --output build_output_path

Example

apic build Project1 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

Builds a project project_build.zip from a single project file, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

2. Building multiple projects

Syntax

apic build Project1 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

apic build Projectname1,Projectname2  --localDir local_dir_path --output build_output_path

Example

apic build Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

Builds a project project_build.zip from two project files, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

3. Building all projects in the local directory

Syntax

apic build --all --localDir local_dir_path --output build_output_path

Example

apic build --all --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

Builds a project project_build.zip by bundling all the projects located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

4. Building an API

Syntax

apic build Projectname1 --names namespace:name:version  --localDir local_dir_path --output build_output_path

Example

apic build Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

Builds an API project_build.zip from a single API file specified by its name dev:TestPayments:1.0 located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

5. Building a project without --output

Syntax

apic build Projectname --localDir local_dir_path

Example

apic build Project1 --localDir /Users/user1/Desktop/apistudio_localdir

Builds a project project_build.zip from the project file, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir. When you do not provide the --output option, APIM CLI builds it with a fixed standard package name, for example, studio-projectname-build.zip and archives it in the same location from where the command is run.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

6. Building specific assets (Partial Build)

The partial build feature allows you to build only specific assets within a project, along with their dependencies. This is useful for faster builds during development or when you need to deploy only a subset of your project's assets.

Syntax

apic build Projectname --localDir local_dir_path --filter-assets "namespace:name:version,..." --output build_output_path

Example: Building a single asset

apic build Project1 --localDir /Users/user1/Desktop/apistudio_localdir --filter-assets "dev:PaymentAPI:1.0" --output ./builds/payment-api.zip

Builds only the PaymentAPI asset (version 1.0 in the dev namespace) from Project1, along with all its dependencies (policies, routes, endpoints, etc.), and saves it to ./builds/payment-api.zip.

Example: Building multiple assets

apic build Project1 --localDir /Users/user1/Desktop/apistudio_localdir --filter-assets "dev:PaymentAPI:1.0,dev:UserAPI:2.0" --output ./builds/multi-api.zip

Builds both PaymentAPI and UserAPI assets with their dependencies from Project1.

Key Features:

• Automatic Dependency Resolution: All required dependencies (policies, routes, endpoints, etc.) are automatically included
• Faster Build Times: Build only what you need, significantly reducing build time for large projects
• Selective Deployment: Deploy specific features without affecting other parts of your project
• Asset Reference Format: Use namespace:name:version format to specify assets

For detailed information, including dependency resolution, troubleshooting, and advanced use cases, see the Partial Build Documentation.

Outcome

As the build progresses, it lists the assets added (including resolved dependencies). On successful completion you will see the message Build completed successfully!. In addition it displays the location where the build is placed.

In case of any errors, a build failure message with the reason for failure is displayed so you can take the corrective action.

7. Building with asset type filter

The asset type filter allows you to build only AI or API assets from a project. This is useful when you have a mixed project containing both AI and API assets and want to build them separately.

Syntax

apic build Projectname --localDir local_dir_path --asset-type <ai|api> --output build_output_path

Example: Building only AI assets

apic build AIProject --localDir /Users/user1/Desktop/apistudio_localdir --asset-type ai --output ./builds/ai-assets.zip

Builds only AI assets (APIs with domain=ai-platform, Products with AI APIs, MCPServer, LLMProvider) from AIProject, along with their dependencies and common assets (Quota, PolicySequence, etc.).

Example: Building only API assets

apic build MixedProject --localDir /Users/user1/Desktop/apistudio_localdir --asset-type api --output ./builds/api-assets.zip

Builds only API assets (APIs without domain or domain=api, Products with API APIs, GlobalPolicy) from MixedProject, along with their dependencies and common assets.

Key Features:

• AI Asset Types: API (with metadata.domain='ai-platform'), Product (referencing AI APIs), MCPServer, LLMProvider
• API Asset Types: API (without domain or domain='api'), Product (referencing API APIs), GlobalPolicy
• Common Assets Included: Assets like Quota, PolicySequence, Invoke, MCPTools are always included when top-level assets exist
• Validation: Build fails with a clear error message if no top-level assets match the specified type

Important Notes:

• The filter applies only to top-level assets. Dependencies and common assets are automatically included.
• If no top-level assets match the filter, the build will fail with an error message.
• MCPTools assets and their spec files are included as dependencies when MCPServer is present.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully! with a summary showing the asset type filter applied. In addition it displays the location where the build is placed.

In case no assets match the filter, an error message like "No top-level assets found matching asset type filter 'api'" is displayed.

Deploy

This operation deploys the build API Gateway.

Syntax

apic deploy [options][projects]

projects. Specifies the projects in the local folder you want to deploy. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available options for the apic deploy command and their descriptions.

Options Description | Commands | Description | |-----------------------------|--------------| | -l, --localDir | Path of the local folder of the specified studio projects. This is a mandatory argument. | | -a, --all | Use --all to include all projects in the given local directory. If you do not want to build all projects in the given local directory, then specify the project name that is required. | | -n, --names | Specify the API kind in the format namespace:apiname:version. You can provide multiple asset names as comma-separated entries as input. Studio supports only API assets. | | -a, --archive archive | Specify the archive to be deployed. | | -t, --target target | Specify the endpoint of the API Gateway instance to which the asset has to be deployed. This is a mandatory argument. | | -u, --username username | Provide the username of the API Gateway instance to which the asset is deployed. This user must have Manage APIs functional privilege. This is a mandatory argument. | | -pwd, --password password | Provide the password of the API Gateway instance to which the asset is deployed. If you do not provide the password, CLI prompts for the password, where you can provide the masked password. | | -ow, --overwrite | Specify if you want to overwrite the existing assets on the API Gateway instance where the specified asset is being deployed. | | -d, --debug | Enables the debug mode. | | -h, --help | Displays help for the build command. |

1. Deploying a single project

Syntax

apic deploy Projectname --localDir local_dir_path  --target "http://host:port"
--username username --password password --overwrite

Example

apic deploy Project1 --localDir /Users/user1/Desktop/apistudio_localdir --target "http://host:port" --username "******" --password "******" --overwrite

Deploys a single project file, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

As the deployment progresses, it lists the asset being added followed by deployment status of the asset. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the project is displayed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

2. Deploying multiple projects

Syntax

apic deploy Projectname1,Projectname2
--localDir local_dir_path
--target "http://host:port"
--username username --password password --overwrite

Example

apic deploy Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir
--target "http://host:port"
--username "******" --password "******" --overwrite

Deploys two projects from two project files, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

As the deployment progresses, it lists the assets being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the projects is displayed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

3. Deploying all projects

Syntax

apic deploy --all --localDir local_dir_path
--target "http://host:port"
--username username --password password --overwrite

Example

apic deploy --all --localDir /Users/user1/Desktop/apistudio_localdir
--target "http://host:port"
--username "******" --password "******" --overwrite

Deploys all projects located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

As the deployment progresses, it lists the assets being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the project is displayed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

4. Deploying an API

Syntax

apic deploy Projectname1 --names namespace:name:version
--localDir local_dir_path --target "http://host:port"
--username username --password password --overwrite

Example

apic deploy Project1 --names dev:TestPayments:1.0
--localDir '/Users/user1/Desktop/apistudio_localdir'  --target 'http://host:port'
--username "******" --password "******" --overwrite

Deploys an API specified by its name dev:TestPayments:1.0, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

As the deployment progresses, it lists the asset being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoint of the API is displayed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

5. Deploying an archive

Syntax

apic deploy --archive --localDir local_dir_path
--target "http://host:port"
--username username --password password --overwrite

Example

apic deploy --archive /Users/user1/Desktop/apistudio_localdir/build.zip
--target "http://host:port" --username "******" --password "****"
--overwrite

Deploys an archive, build.zip, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

As the deployment progresses, it lists the assets being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the project is displayed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

Test

This operation tests the projects deployed to API Gateway.

Syntax

apic test [options][projects]

projects. Specifies the projects in the local folder that have to be tested. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available arguments for the apic test command and their descriptions.

Argument Description | Command | Description | |--------------------------------|--------------| | -l, --localDir localDirpath | Path of the local folder of the specified studio projects. This is a mandatory argument. | | -a, --all | Use --all to include all projects in the given local directory. If you do not want to build all projects in the given local directory, then specify the project name that is required. | | -t, --target target | Specify the endpoint of the API Gateway instance to which the asset has to be deployed. | | -n, --names | Specify the API kind in the format namespace:apiname:version. You can provide multiple asset names as comma-separated entries as input. Studio supports only API assets. | | -u, --username username | Provide the username of the API Gateway instance to which the asset is deployed. This user must have Manage APIs functional privilege. This is a mandatory argument. | | -pwd, --password password | Provide the password of the API Gateway instance to which the asset is deployed. If you do not provide the password, CLI prompts for the password, where you can provide the masked password. | | -de, --deploy | Deploys the projects or the specified asset to API Gateway during testing. | | -e, --env key=value | Adds or overwrites the environment configuration values in the environment asset file. For example, key1=value1,key2=value2. | | -en, --endpoints | Tests the specified API, as defined by the --names parameter, against the --endpoint value where it is already deployed. | | -f, --format <format> | Specifies the output format for test results. Supported formats: json, csv. If not specified, results are displayed in console only. | | -out, --output <path> | Specifies the file path where test results should be saved. If not specified with format, results are displayed in console only. | | -d, --debug | Enables the debug mode. | | -h, --help | Displays help for the build command. |

1. Testing a single project

Syntax

apic test Projectname --localDir local_dir_path

Example

apic test Project1 --localDir /Users/user1/Desktop/apistudio_localdir

Tests the project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

2. Testing multiple projects

Syntax

apic test Projectname1,Projectname2  --localDir local_dir_path

Example

apic test Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir

Tests the projects, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

As the tests start, it displays the assets added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

3. Testing all projects

Syntax

apic test --all --localDir local_dir_path

Example

apic test --all --localDir /Users/user1/Desktop/apistudio_localdir

Tests all the projects located in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

4. Testing an API

Syntax

apic test Projectname --names namespace:name:version --localDir local_dir_path

Example

apic test Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir

Tests an API specified by its name dev:TestPayments:1.0, located in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

As the tests start, it displays the asset added and a list of gateway endpoint of the API. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

5. Testing a project by overwriting the environment configuration

Syntax

apic test Projectname --localDir local_dir_path --env key=value

Example

apic test Project1 --localDir  /Users/user1/Desktop/apistudio_localdir --env Content-Type=application/json,petId=1

Tests a project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir using the environment configuration values provided in the environment asset file.

Outcome

As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

6. Testing a project using endpoints

Syntax

apic test Projectname --names namespace:name:version --localDir local_dir_path --endpoints endpoint

Example

apic test Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir
--endpoints http://host:port/gateway/ProductAPI10/1.0

Tests a project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir using the API endpoint http://host:port/gateway/ProductAPI10/1.0.

Outcome

As the tests start, the display shows the added assets. When all tests run successfully, the message Test executed successully... appears. Additionally, it shows the number of tests passed, the number failed, and the overall test status. You can view details for each test, including the resource, assertion, status, and, for any failed test, an error message explaining the reason for failure.

7. Deploying and testing a project

Syntax

apic test Projectname --localDir local_dir_path --target "http://host:port" --username username --password password --deploy

Example

apic test Project1 --localDir  C:/Users/user1/Desktop/apistudio_localdir  --target "http://host:port"
--username "******" --password "******" --deploy

Deploys the project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. On successful deployment it tests the deployed project.

Outcome

As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

8. Saving test results in different formats

You can save test results in JSON or CSV format for further analysis or reporting.

Syntax

apic test Projectname --localDir local_dir_path --format <format> --output <output_path>

Example: Saving test results in JSON format

apic test Project1 --localDir /Users/user1/Desktop/apistudio_localdir --format json --output ./test-results.json

Example: Saving test results in CSV format

apic test Project1 --localDir /Users/user1/Desktop/apistudio_localdir --format csv --output ./test-results.csv

Example: Using short flags

apic test Project1 -l /Users/user1/Desktop/apistudio_localdir -f csv -out ./results.csv

Tests the project, Project1, and saves the results in the specified format and location. If you specify only the format without output path, a default filename is used (e.g., test-results.json or test-results.csv).

Outcome

The test results are saved in the specified format at the given location. The JSON format provides detailed structured data, while the CSV format offers a tabular view with columns: Test Name, Resource Name, Assertions, Status, and Message. This makes it easy to import results into spreadsheet applications or other analysis tools.

apic load-sample

This operation loads sample projects from the bundled samples or JFrog Artifactory into your local directory. Sample projects help you get started quickly with pre-configured API projects for different gateway types.

Syntax

apic load-sample [options]

The following table lists all available options for the apic load-sample command and their descriptions.

Options Description

| Command | Description | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | -l, --localDir | Path of the local directory where sample projects will be loaded. This argument is mandatory. | | -g, --gatewayType <gatewayType> | Filters samples by gateway type. Valid values: datapower-nano-gateway, datapower-gateway, datapower-api-gateway, wm-api-gateway. Optional. | | -p, --project <project> | Loads only the sample project with the specified name. Optional. | | -b, --branch <branch> | Branch to download samples from when fetching from JFrog Artifactory. Default: main. Optional. Has no effect when bundled samples are available. | | -h, --help | Displays help for the load-sample command. |

1. Loading all sample projects

Syntax

apic load-sample --localDir local_dir_path

Example

apic load-sample --localDir /Users/user1/Desktop/my-samples

Loads all available sample projects into the local directory /Users/user1/Desktop/my-samples. The command automatically loads samples for all supported gateway types including DataPower Gateway, DataPower API Gateway, DataPower Nano Gateway, and webMethods API Gateway.

Outcome

As the loading progresses, it displays the sample projects being copied. On successful completion you will see the message indicating the number of sample projects loaded and their location. The samples are ready to use and can be built, deployed, or tested using other APIM CLI commands.

2. Loading sample projects for a specific gateway type

Syntax

apic load-sample --localDir local_dir_path --gatewayType gateway_type

Example

apic load-sample --localDir /Users/user1/Desktop/my-samples --gatewayType wm-api-gateway

Loads only the sample projects for the wm-api-gateway gateway type into the specified local directory. Valid gateway type values are datapower-nano-gateway, datapower-gateway, datapower-api-gateway, and wm-api-gateway.

Outcome

Only the sample projects matching the specified gateway type are copied to the local directory. The success message shows the number of projects loaded.

3. Loading a specific sample project by name

Syntax

apic load-sample --localDir local_dir_path --project project_name

Example

apic load-sample --localDir /Users/user1/Desktop/my-samples --project DPv6_Product_Calculator_Soap

Loads only the sample project named DPv6_Product_Calculator_Soap into the specified local directory.

Outcome

Only the named project is copied to the local directory. If no project with that name exists, an error is displayed indicating no matching sample projects were found.

4. Loading a specific sample project for a specific gateway type

Syntax

apic load-sample --localDir local_dir_path --gatewayType gateway_type --project project_name

Example

apic load-sample --localDir /Users/user1/Desktop/my-samples --gatewayType datapower-api-gateway --project DPv6_Product_Calculator_Soap

Loads only the project DPv6_Product_Calculator_Soap under the datapower-api-gateway gateway type. Both filters are applied together, so the project must match both the name and the gateway type.

Outcome

The matching project is copied to the local directory. If the combination of name and gateway type produces no match, an error is displayed indicating no matching sample projects were found.

5. Loading samples from a specific branch

Syntax

apic load-sample --localDir local_dir_path --branch branch_name

Example

apic load-sample --localDir /Users/user1/Desktop/my-samples --branch release-12.1

Tryout

The apic tryout command allows you to quickly test API endpoints without deploying or running full test suites. It's similar to using curl but integrated with APIM for endpoint discovery.

Key Features:

• Test APIs using direct endpoint URLs
• Discover and test APIs using APIM (org/catalog/space)
• Support for all HTTP methods (GET, POST, PUT, DELETE, etc.)
• Custom headers and request body support
• Verbose mode to see full request/response details
• Save responses to files

Syntax:

# Using direct endpoint
apic tryout --endpoint <url> [options]

# Using API name with APIM
apic tryout --apiName <namespace:name:version> --org <org> --catalog <catalog> --server <apim-url> --token <token> [options]

Options:

| Option | Description | |--------|-------------| | -ep, --endpoint <endpoint> | Direct endpoint URL to try out. For example, https://api.example.com/v1/users | | -api, --apiName <apiName> | API identifier in format namespace:name:version. For example, dev:paymentAPI:1.0 | | -p, --path <path> | API path to append to the gateway endpoint. For example, /air-temperature or /users/123 | | -X, --method <method> | HTTP method for the request (GET, POST, PUT, DELETE, etc.). Default: GET | | -H, --headers <headers> | HTTP headers in format key1:value1,key2:value2 | | -d, --body <body> | Request body for POST/PUT requests. Can be JSON string or @filepath | | -v, --verbose | Show verbose output including request and response headers | | -save, --save <file> | Save the response to a file | | -o, --org <org> | Organization ID (required with --apiName) | | -c, --catalog <catalog> | Catalog ID (required with --apiName) | | -space, --space <space> | Space ID (optional with --apiName) | | -s, --server <server> | APIM server URL (required with --apiName) | | -token, --token <token> | Authentication token (required with --apiName) | | -debug, --debug | Enable debug mode |

1. Trying out an API with direct endpoint

Test an API using a direct endpoint URL.

Syntax:

apic tryout --endpoint <url> --method <method> [--verbose]

Example:

apic tryout --endpoint "https://api.github.com/zen" --method GET --verbose

Outcome:

--------------------------
> GET https://api.github.com/zen
--------------------------
< HTTP 200 OK
< content-type: text/plain;charset=utf-8
< content-length: 46
...
Keep it logically awesome.
--------------------------
Response time: 601ms
✓ Request completed successfully

2. Trying out an API with API name

Test an API by looking up its endpoint from APIM using the API name.

Syntax:

apic tryout --apiName <namespace:name:version> \
  --org <orgId> \
  --catalog <catalogId> \
  --server <apimUrl> \
  --token <token> \
  --method <method>

Example:

apic tryout --apiName "myorg:paymentAPI:1.0" \
  --org "5d2e8f9a" \
  --catalog "sandbox" \
  --server "https://apim.example.com" \
  --token "eyJhbGc..." \
  --method GET \
  --verbose

Outcome:

The command will:

1. Look up the API gateway endpoint from APIM
2. Make the HTTP request to the discovered endpoint
3. Display the response

3. Trying out an API with path parameter

Test an API by appending a path to the base endpoint.

Syntax:

apic tryout --endpoint <base-url> --path <resource-path> --method <method>

Example:

apic tryout --endpoint "https://api.example.com" \
  --path "/users/123" \
  --method GET \
  --verbose

Outcome:

The command will make a request to https://api.example.com/users/123 and display the response.

4. Trying out an API with custom headers and body

Test an API with custom headers and request body.

Syntax:

apic tryout --endpoint <url> \
  --method POST \
  --headers "Content-Type:application/json,Authorization:Bearer token" \
  --body '{"key":"value"}' \
  --verbose

Example with inline JSON:

apic tryout --endpoint "https://api.example.com/users" \
  --method POST \
  --headers "Content-Type:application/json" \
  --body '{"name":"John Doe","email":"[email protected]"}' \
  --verbose

Example with file:

apic tryout --endpoint "https://api.example.com/users" \
  --method POST \
  --headers "Content-Type:application/json" \
  --body "@request.json" \
  --save "response.json"

Outcome:

The command will:

1. Send a POST request with the specified headers and body
2. Display the full request and response (with --verbose)
3. Save the response to a file (with --save)

Important Notes:

• When using --endpoint, APIM parameters (--org, --catalog, --server, --token) are not required
• When using --apiName, all APIM parameters (--org, --catalog, --server, --token) are required
• The command validates parameter combinations and provides helpful error messages
• Use --verbose to see full request/response headers for debugging

Downloads and loads sample projects from the release-12.1 branch of JFrog Artifactory instead of the default main branch. This option is only used when no bundled samples are available locally. If bundled samples are present, they are always used regardless of the --branch value.

Outcome

Sample projects from the specified branch are downloaded, extracted, and copied to the local directory. The success message includes the source branch for reference.

Lint

This operation analyzes project assets for errors, warnings, and best practice violations. It helps ensure code quality and adherence to API design standards before building or deploying your projects.

Syntax

apic lint [options][projects]

projects. Specifies the projects in the local folder that need to be linted. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available arguments for the apic lint command and their descriptions.

Argument Description | Command | Description | |--------------------------------|--------------| | -l, --localDir localDirpath | Path of the local folder of the specified studio projects. This is a mandatory argument. | | -a, --all | Use --all to lint all projects in the given local directory. If you do not want to lint all projects, specify the project names that are required. | | -n, --names <names> | Specify the API kind in the format namespace:apiname:version. You can provide multiple asset names as comma-separated entries as input. Studio supports only API assets. | | -dependencies, --dependencies <dependencies> | Include dependent projects in linting. Set to true to include dependencies. Default: false. | | -f, --format <format> | Specifies the output format for lint results. Supported formats: table, json. Default: table. | | -d, --debug | Enables the debug mode. | | -h, --help | Displays help for the lint command. |

1. Linting a single project

Syntax

apic lint Projectname --localDir local_dir_path

Example

apic lint Project1 --localDir /Users/user1/Desktop/apistudio_localdir

Lints the project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir. The command analyzes all assets in the project for errors and warnings.

Outcome

The lint results are displayed in a formatted table showing any errors, warnings, or informational messages found in the project assets. Each issue includes the file name, line number, severity level, and a description of the problem. If no issues are found, you will see a success message indicating the project passed all lint checks.

2. Linting multiple projects

Syntax

apic lint Projectname1,Projectname2 --localDir local_dir_path

Example

apic lint Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir

Lints multiple projects, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir. Each project is analyzed independently.

Outcome

The lint results for all specified projects are displayed. Issues are grouped by project, making it easy to identify which project needs attention. The output shows the total number of errors and warnings across all projects, helping you prioritize fixes.

3. Linting all projects

Syntax

apic lint --all --localDir local_dir_path

Example

apic lint --all --localDir /Users/user1/Desktop/apistudio_localdir

Lints all projects located in the local directory /Users/user1/Desktop/apistudio_localdir. This is useful for ensuring code quality across your entire workspace.

Outcome

All projects in the directory are analyzed and results are displayed in a comprehensive report. This provides a complete overview of code quality across all your API projects, making it easy to maintain consistent standards.

4. Linting an API

Syntax

apic lint Projectname --names namespace:name:version --localDir local_dir_path

Example

apic lint Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir

Lints a specific API, dev:TestPayments:1.0, within the project Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

The lint results focus on the specified API asset, showing any issues specific to that API. This targeted approach is useful when you want to verify a specific API without analyzing the entire project.

5. Linting with dependencies

Syntax

apic lint Projectname --localDir local_dir_path --dependencies true --format json

Example

apic lint Project1 --localDir /Users/user1/Desktop/apistudio_localdir --dependencies true --format json

Lints the project Project1 along with all its dependent projects, and outputs the results in JSON format for further processing or integration with CI/CD pipelines.

Outcome

The lint analysis includes not only the specified project but also all projects it depends on. This ensures that the entire dependency chain is validated. The JSON format output can be easily parsed by automated tools, making it ideal for continuous integration workflows. The structured output includes detailed information about each issue, including severity, location, and suggested fixes.

Validate

This operation validates project build artifacts against gateway-specific specifications. It automatically detects the gateway type (DataPower, Nano, or webMethods) based on the policy kinds used in your project and validates the build using the appropriate SDK validators.

Syntax

apic validate [options][projects]

projects. Specifies the projects in the local folder that need to be validated. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available arguments for the apic validate command and their descriptions.

Argument Description | Command | Description | |--------------------------------|--------------| | -l, --localDir localDirpath | Path of the local folder of the specified studio projects. This is a mandatory argument. | | -a, --all | Use --all to validate all projects in the given local directory. If you do not want to validate all projects, specify the project names that are required. | | -d, --debug | Enables the debug mode. | | -h, --help | Displays help for the validate command. |

1. Validating a single project

Syntax

apic validate Projectname --localDir local_dir_path

Example

apic validate Project1 --localDir /Users/user1/Desktop/apistudio_localdir

Validates the project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir. The command automatically detects the gateway type and validates the build artifacts accordingly.

Outcome

The validation results are displayed in a formatted table showing the project name, detected gateway type (DataPower, Nano, or webMethods), validation status (PASSED or FAILED), and any error messages if validation fails. On successful validation, you will see the message "All X project(s) validated successfully!". If validation fails, detailed error messages help you identify and fix the issues.

2. Validating multiple projects

Syntax

apic validate Projectname1,Projectname2 --localDir local_dir_path

Example

apic validate Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir

Validates multiple projects, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir. Each project is validated independently with its detected gateway type.

Outcome

The validation results are displayed in a formatted table with separate rows for each project. Each row shows the project name, gateway type, status, and any errors. The summary at the top displays the total number of projects validated, successful validations, and failed validations. This makes it easy to identify which projects need attention.

3. Validating all projects

Syntax

apic validate --all --localDir local_dir_path

Example

apic validate --all --localDir /Users/user1/Desktop/apistudio_localdir

Validates all projects located in the local directory /Users/user1/Desktop/apistudio_localdir. This is useful for batch validation of multiple projects in your workspace.

Outcome

All projects in the directory are validated and results are displayed in a comprehensive table. Each project shows its detected gateway type and validation status. The command provides a complete overview of the health of all your API projects, making it easy to ensure all projects meet gateway specifications before deployment.

Export

This operation exports the specified projects from API Manager to a ZIP archive in the local directory. It connects to an API Manager instance, retrieves the project files, and packages them into a ZIP file that can be stored locally or imported into another environment.

Syntax

apic export [options][projects]

projects. Specifies the projects in API Manager that need to be exported. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available arguments for the apic export command and their descriptions.

Argument Description | Command | Description | |----------------------------------------|--------------| | -l, --localDir <localDir> | Path of the local folder where the exported ZIP file will be saved. This is a mandatory argument. | | -s, --server <server> | URL of the API Manager instance from which the projects are exported. This is a mandatory argument. | | -o, --org <org> | The organisation in API Manager from which the projects are exported. This is a mandatory argument. | | -token, --token <token> | Authentication token for API Manager. This is a mandatory argument. | | -a, --all | Use --all to export all projects from API Manager. If you do not want to export all projects, specify the project names that are required. | | --dependencies <dependencies> | Include dependent projects (transitive dependencies) in the export. Accepts true or false. Default: false. | | -d, --debug | Enables the debug mode. | | -h, --help | Displays help for the export command. |

1. Exporting a single project

Syntax

apic export Projectname --localDir local_dir_path --server apim_url --org org_name --token auth_token

Example

apic export Project1 --localDir /Users/user1/Desktop/apistudio_localdir --server https://apim.example.com --org my-org --token eyJhbGci...

Exports the project, Project1, from API Manager and saves it as a ZIP archive in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

A ZIP file named studio-Project1-export.zip is created in the specified local directory. The archive contains all of the project's asset files. A success message is displayed confirming the export and showing the full path of the created ZIP file.

2. Exporting multiple projects

Syntax

apic export Projectname1,Projectname2 --localDir local_dir_path --server apim_url --org org_name --token auth_token

Example

apic export Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir --server https://apim.example.com --org my-org --token eyJhbGci...

Exports multiple projects, Project1 and Project2, from API Manager and packages them together into a single ZIP archive in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

A ZIP file named studio-projects-export.zip is created in the specified local directory. The archive contains the asset files for all specified projects. A success message confirms the export and displays the path of the created ZIP file.

3. Exporting all projects

Syntax

apic export --all --localDir local_dir_path --server apim_url --org org_name --token auth_token

Example

apic export --all --localDir /Users/user1/Desktop/apistudio_localdir --server https://apim.example.com --org my-org --token eyJhbGci...

Exports all projects from the specified API Manager organisation and saves them into a single ZIP archive in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

A ZIP file named studio-all-export.zip is created in the specified local directory. The archive contains all projects found in the organisation. This is useful for creating a full backup of your API Manager workspace before migrations or major changes.

4. Exporting a project with dependencies

Syntax

apic export Projectname --localDir local_dir_path --server apim_url --org org_name --token auth_token --dependencies true

Example

apic export Project1 --localDir /Users/user1/Desktop/apistudio_localdir --server https://apim.example.com --org my-org --token eyJhbGci... --dependencies true

Exports the project Project1 along with all of its dependent projects (transitive dependencies) from API Manager.

Outcome

A ZIP file is created in the specified local directory containing Project1 and all projects it depends on. The archive also includes a manifest file listing the exported projects and their dependencies. This ensures that all assets required to run the project in another environment are included in the export.

Import

This operation imports the specified projects from a local directory into API Manager. It reads project folders from the local filesystem, creates the corresponding projects in API Manager, and uploads all project files. Projects that already exist in API Manager are automatically skipped to avoid overwriting existing data.

Syntax

apic import [options][projects]

projects. Specifies the project folders in the local directory that need to be imported. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available arguments for the apic import command and their descriptions.

Argument Description | Command | Description | |----------------------------------------|--------------| | -l, --localDir <localDir> | Path of the local folder containing the project folders to import. This is a mandatory argument. | | -s, --server <server> | URL of the API Manager instance into which the projects are imported. This is a mandatory argument. | | -o, --org <org> | The organisation in API Manager into which the projects are imported. This is a mandatory argument. | | -token, --token <token> | Authentication token for API Manager. This is a mandatory argument. | | -a, --all | Use --all to import all project folders found in the local directory. If you do not want to import all projects, specify the project names that are required. | | -d, --debug | Enables the debug mode. | | -h, --help | Displays help for the import command. |

1. Importing a single project

Syntax

apic import Projectname --localDir local_dir_path --server apim_url --org org_name --token auth_token

Example

apic import Project1 --localDir /Users/user1/Desktop/apistudio_localdir --server https://apim.example.com --org my-org --token eyJhbGci...

Imports the project folder Project1 from the local directory /Users/user1/Desktop/apistudio_localdir into API Manager.

Outcome

The project is created in API Manager and all files from the project folder are uploaded. A success message is displayed once the import is complete. If the project already exists in API Manager, it is skipped and a warning is shown.

2. Importing multiple projects

Syntax

apic import Projectname1,Projectname2 --localDir local_dir_path --server apim_url --org org_name --token auth_token

Example

apic import Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir --server https://apim.example.com --org my-org --token eyJhbGci...

Imports multiple project folders, Project1 and Project2, from the local directory /Users/user1/Desktop/apistudio_localdir into API Manager.

Outcome

Each project is created in API Manager and its files are uploaded independently. Projects that already exist in API Manager are automatically skipped with a warning. A final success message is displayed once all projects have been processed.

3. Importing all projects

Syntax

apic import --all --localDir local_dir_path --server apim_url --org org_name --token auth_token

Example

apic import --all --localDir /Users/user1/Desktop/apistudio_localdir --server https://apim.example.com --org my-org --token eyJhbGci...

Imports all project folders found in the local directory /Users/user1/Desktop/apistudio_localdir into API Manager. This is useful for bulk import of projects, for example when migrating an entire workspace to a new API Manager instance.

Outcome

Every sub-folder in the specified local directory is treated as a project and imported into API Manager. Projects that already exist in API Manager are skipped. A success message is displayed at the end confirming that all eligible projects have been imported.

apic create

Creates a new project in the specified local directory.

Syntax:

apic create <project-name> [options]

Arguments:

• <project-name> - Name of the project to create (required)

Options:

| Option | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | -l, --localDir <localDir> | Path of the local directory of the specified project asset. For example, C:\local_dir. If not specified, current folder will be used as the root directory. | | --desc <desc> | Project description | | -t, --tags <tags> | Tags for the project. Comma separated values |

Examples:

1. Creating a project in the current folder:

apic create MyProject

2. Creating a project in a specific folder:

apic create MyProject --localDir /Users/user1/Desktop/apistudio_localdir

3. Creating a project with description and tags:

apic create MyProject --localDir /Users/user1/Desktop/apistudio_localdir --desc "Payment processing API" --tags "payment,api,v1"

apic update

Updates an existing project's metadata and optionally renames the project folder.

Syntax:

apic update <project-name> [options]

Arguments:

• <project-name> - Name of the project to update (required)

Options:

| Option | Description | | --------------------------- | ------------------------------------------------------------------------------------- | | -l, --localDir <localDir> | Path of the local directory of the specified project asset. For example, C:\local_dir | | --desc <desc> | Project description | | -t, --tags <tags> | Tags for the project. Comma separated values | | --name <name> | New project name (renames the project) |

Examples:

1. Updating project description and tags:

apic update MyProject --localDir /Users/user1/Desktop/apistudio_localdir --desc "Updated description" --tags "payment,api,v2"

2. Renaming a project:

apic update MyProject --localDir /Users/user1/Desktop/apistudio_localdir --name MyRenamedProject

apic delete

Deletes an existing project from metadata and optionally removes the project folder.

Syntax:

apic delete <project-name> [options]

Arguments:

• <project-name> - Name of the project to delete (required)

Options:

| Option | Description | | --------------------------- | ------------------------------------------------------------------------------------- | | -l, --localDir <localDir> | Path of the local directory of the specified project asset. For example, C:\local_dir | | --keepDir | Keep the project folder in the local directory (only removes from metadata) |

Examples:

1. Deleting only project metadata (keeping the folder):

apic delete MyProject --localDir /Users/user1/Desktop/apistudio_localdir --keepDir

2. Deleting project metadata and folder:

apic delete MyProject --localDir /Users/user1/Desktop/apistudio_localdir

apic list

Lists projects from the local directory metadata.

Syntax:

apic list [options]

Options:

| Option | Description | | --------------------------- | ------------------------------------------------------------------------------------- | | -l, --localDir <localDir> | Path of the local directory of the specified project asset. For example, C:\local_dir | | --json | Display projects in JSON format | | -t, --tags <tags> | Filter projects by tags. Comma separated values |

Examples:

1. Listing all projects:

apic list --localDir /Users/user1/Desktop/apistudio_localdir

2. Listing projects in JSON format:

apic list --localDir /Users/user1/Desktop/apistudio_localdir --json

3. Listing projects filtered by tags:

apic list --localDir /Users/user1/Desktop/apistudio_localdir --tags "payment,api"

apic schema

Manages API Studio asset schemas for LLM-based asset generation. Provides access to JSON Schema definitions for all available asset kinds across different gateway types.

apic schema list

Lists all available asset kinds with their default versions.

Syntax:

apic schema list [options]

Options:

| Option | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | -g, --gateway <gateway> | Gateway type: common (base assets only), wmgw (WebMethods Gateway), or lwgw (Lightweight/Nano Gateway). Default: lwgw | | -h, --help | Displays help for the command |

Examples:

1. Listing assets for Lightweight/Nano Gateway (default):

apic schema list

2. Listing assets for WebMethods Gateway:

apic schema list --gateway wmgw

3. Listing common/base assets only:

apic schema list --gateway common

Output: Displays a categorized list of all available asset kinds with their default versions, grouped by type (Core Assets, Policies & Sequences, Other Assets).

apic schema get

Retrieves and displays the JSON Schema for a specific asset kind.

Syntax:

apic schema get <kind> [options]

Arguments:

• <kind> - Asset kind name (e.g., API, Route, StagedPolicySequence) (required)

Options:

| Option | Description | | ------------------------- | ---------------------------------------------------------- | | -g, --gateway <gateway> | Gateway type: common, wmgw, or lwgw. Default: lwgw | | --asset-version <version> | Specific schema version. Uses default if not specified | | -f, --format <format> | Output format: json or yaml. Default: json | | -h, --help | Displays help for the command |

Examples:

1. Gett