Managing API and Query Collections

Contents

• Overview
• Creating a Collection
  • Creating API Collection
    • Configuring Connection Bindings
    • Adding Operations
    • Dynamic Path Parameters
  • creating Query Collection
    • Adding Query Operations
• Operation Validity Indicator
• Agentic Tool (JSON)
• More Options
• Cloning a Collection

Overview:

A Collection defines a logical grouping of API operations that interact with an external system. It organizes endpoints such as create, retrieve, update, or comment actions under a single connection, enabling structured and reusable API execution within workflows.

Creating a API Collection

To create a Collection:

1. Navigate to AI Orchestration → Registry.

2. Select Add Asset.

3. Choose API Collection as the Sub-asset type.

4. Provide a Name and Description.

5. Save the Collection.

NOTE: By default, the Asset Type is set to Collection, and the Sub Types available are API Collection and Query Collection.

Connection Binding specifies which data source and API credentials the collection will use, ensuring the collection is linked to the correct source configuration.

Configuring Connection Bindings

Once the Collection asset is created, the Overview tab displays the Asset-Specific Details, where Connection Bindings can be configured by linking one or more previously configured REST API connections.
 

• If multiple connections are added, the first created connection is automatically marked as Default.

• The default connection is used during execution unless explicitly changed.

NOTE: If the default Connection is deleted, the system automatically assigns the next available Connection as default.

• Once published, the Collection is ready to define operations and can be integrated into Workflows for execution.

Adding Operations

An operation is defined by specifying a name, description, 

After creating an Operation, users must specify the HTTP method (GET, POST, PUT, PATCH and DELETE), provide the endpoint URL, and configure query parameters or request body as required. 

The base URL is automatically fetched from the configured source details,

Dynamic Path Parameters

Dynamic path parameters are placeholders used within an API endpoint URL that are replaced with actual values at runtime. They allow API operations to be reusable without hardcoding specific values.

Why Use Dynamic Path Parameters?

• Avoid hardcoding resource identifiers (e.g., IDs, keys)

• Enable reuse of the same API operation for different inputs

• Support dynamic execution in testing and workflows

How to Define

Use double curly braces {{ }} in the endpoint URL.

Example:

/rest/api/3/project/{{projectIdOrKey}}

How It Works

At runtime, the user provides values for the defined dynamic path parameters.

• During workflow execution, users can pass values to the parameters

• During Try It Out, users can manually enter parameter values for testing

Example:

• Parameter: projectIdOrKey = DV-123

Creating a Query Collection

Overview

A Query Collection defines a logical grouping of database queries that interact with structured data sources such as JDBC-based systems. It enables users to organize, manage, and execute reusable SQL queries within workflows.

Unlike API Collections, which interact with external services using HTTP requests, Query Collections execute SQL queries directly on connected data sources.

Creating a Query Collection

To create a Query Collection:

1. Navigate to AI Orchestration → Registry

2. Select Add Asset

3. Select Query Collection as the Sub-asset type

4. Provide a Name and Description

5. Select a Connection Binding

Key Points:

• Multiple connections can be added

• The first connection is set as the default

• The default connection is used during execution unless changed

Note: If the default connection is deleted, the system automatically assigns another available connection as the default.

Adding Query Operations

An operation in a Query Collection represents a SQL query execution.

To add an operation:

1. Navigate to the Operations tab

2. Click Add Operation

3. Provide:

   • Operation Name

   • Description

4. Enter the SQL Query

• Queries can include:

  • SELECT, INSERT, UPDATE, DELETE

• The query is executed directly on the selected data source

Operation Validity Indicator

Visual indicators show the configuration status of each operation. If the endpoint URL or required details are missing, the operation is marked as unusable. Once all mandatory fields are completed, it becomes valid.

Try It Out (Testing)

Operations can be executed  using the option Try It Out. by provide values for defined variables, execute the request, and review the response in JSON format.

Agentic Tool (JSON)

The Agentic Tool (JSON) view provides a read-only JSON representation of the configured API operation. This definition copied and used when setting up the operation as a Tool within AI Agents.

More Options (⋮)

The ellipsis (three-dot) menu provides additional actions for managing the API operation.

• Clone – Creates a duplicate of the current API operation, allowing you to modify it without affecting the original configuration.
• Delete – Permanently removes the API operation from the system.

Cloning a Collection

API Collections and Query Collections can be cloned by selecting Clone from the three-dot (⋮) menu. The cloned collection is created as a separate asset, allowing its details, connection bindings, and operations to be modified independently of the original collection.