Applications

​

Overview

​

What Are Applications?

• API Operations: Individual endpoints the AI can call
• MCP Tools: AI-friendly tools generated from API operations
• Security Configuration: Authentication and credential management
• Metadata: Context and descriptions for better AI understanding

​

Application Lifecycle

​

Discovery

​

Installation

​

Configuration

​

Usage

​

Installing Applications

​

Method 1: From OpenAPI URL

1. Navigate to Applications page
2. Click + Install Application button
3. Select From URL tab
4. Enter the OpenAPI specification URL
   Copy

   https://api.example.com/openapi.json
   

5. Click Install

• JSON (.json)
• YAML (.yaml, .yml)
• OpenAPI 2.0 (Swagger)
• OpenAPI 3.0
• OpenAPI 3.1

​

Method 2: Upload File

1. Navigate to Applications page
2. Click + Install Application button
3. Select From File tab
4. Click to select or drag and drop your file
5. Click Install

• Valid OpenAPI specification
• Maximum size: 10MB
• Formats: JSON or YAML

​

Installation Process

1. Validates the specification
   • Checks OpenAPI format
   • Verifies required fields
   • Identifies errors
2. Creates agentic metadata
   • Generates tool descriptions
   • Extracts parameter information
   • Creates operation summaries
3. Initializes configuration
   • Sets up security placeholders
   • Creates default settings
   • Prepares for first use

​

Configuring Applications

​

General Settings

• API Name: Unique identifier (read-only)
• API Title: Display name for the application
• Description: What the application does
• Version: API version (from specification)
• Domain URL: Base URL for API calls

• Private: Only you can use it
• Organization: Available to your team
• Toggle visibility as needed

​

Security Configuration

​

Authentication Types

Security Scheme: API Key
Location: Header / Query Parameter / Cookie
Parameter Name: X-API-Key (example)

Configuration:
- Enter your API key
- Specify where it should be sent
- Save credentials

Security Scheme: HTTP Bearer
Format: JWT (typical)

Configuration:
- Enter your bearer token
- Token is sent in Authorization header
- Refresh tokens if needed

Security Scheme: OAuth2
Flow: Authorization Code / Client Credentials

Configuration:
- Client ID
- Client Secret
- Authorization URL
- Token URL
- Scopes (permissions needed)

Security Scheme: HTTP Basic
Encoding: Base64 (username:password)

Configuration:
- Username
- Password
- Automatically encoded

Security Scheme: Custom headers

Configuration:
- Add any custom headers required
- Support for multiple headers
- Dynamic value substitution

​

Security Setup Steps

1. Identify Authentication Method
   • Check application documentation
   • Look at the Security tab
   • Note required credentials
2. Obtain Credentials
   • Generate API keys from provider
   • Complete OAuth flow if needed
   • Get service account credentials
3. Configure in Apigene
   • Enter credentials in Security tab
   • Test connection if available
   • Save configuration
4. Verify Setup
   • Use application in Copilot
   • Check for authentication errors
   • Update if credentials expire

​

API Operations

• Method (GET, POST, PUT, DELETE, etc.)
• Path (e.g., /api/v1/users)
• Summary description
• Tags for organization

• Full description
• Parameters (path, query, body)
• Request examples
• Response schemas
• Status codes

• Search by operation name
• Filter by HTTP method
• Filter by tags
• Sort by various criteria

​

MCP Tools Configuration

• Tool name (e.g., github_create_issue)
• Description for AI understanding
• Required parameters
• Optional parameters
• Success criteria

• Edit tool descriptions
• Modify parameter hints
• Add usage examples
• Set default values

• Automatically created during installation
• One tool per API operation
• Can be regenerated if needed
• Updates reflect in Copilot immediately

​

Common Parameters

• Organization ID (consistent across all calls)
• API version preference
• Response format preferences
• Default pagination limits

• Parameter name
• Default value
• Apply to all operations or specific ones
• Override in individual calls if needed

• Reduce repetitive input
• Ensure consistency
• Simplify Copilot interactions
• Minimize errors

​

Managing Applications

​

Application List

• Application icon (auto-generated from domain)
• Application name and title
• Description
• Security status (configured ✓ / not configured ⚠️)
• Installation date

• Click to view/edit details
• Delete application
• Refresh metadata
• Export configuration

​

Searching Applications

• Search by name
• Search by description
• Filter results in real-time

​

Updating Applications

1. Go to application details
2. Click Update Specification
3. Provide new URL or file
4. Review changes
5. Save updates

• New operations added
• Removed operations deprecated
• Modified parameters reflected
• Security schemes updated
• MCP tools regenerated

​

Deleting Applications

1. Navigate to Applications page
2. Find the application
3. Click the delete icon
4. Confirm deletion

• All configuration is removed
• MCP tools become unavailable
• Copilot conversations can no longer use it
• Agents using this application will show errors
• Historical data is retained

​

Application Status Indicators

​

Security Status

• Authentication is set up
• Application is ready to use
• API calls will succeed

• Missing credentials
• Application cannot make API calls
• Configuration required

• Credentials may be expired
• Security scheme changed
• Reconfiguration recommended

​

Connection Status

• Successfully making API calls
• Credentials are valid
• Service is reachable

• Authentication errors
• Network issues
• Service unavailable

• Not yet used in conversations
• Status unknown
• Test needed

​

Best Practices

​

Installation

• Use official OpenAPI specs when available
• Verify specification completeness
• Check for recent updates

• Use clear, recognizable names
• Include version if relevant
• Follow team naming conventions

​

Configuration

• Use service accounts when possible
• Rotate credentials regularly
• Don’t share credentials publicly
• Use environment-specific keys (dev/prod)

• Make a simple API call in Copilot
• Verify authentication works
• Check returned data format
• Confirm permissions are sufficient

​

Maintenance

• Check Dashboard for application usage
• Identify unused applications
• Review API call success rates
• Monitor for errors

• Update specifications when APIs change
• Review security configurations quarterly
• Remove deprecated applications
• Document configuration changes

• Set common parameters to reduce overhead
• Configure only necessary operations
• Use appropriate authentication methods
• Monitor rate limits

​

Advanced Features

​

Custom Operation Metadata

Operation: createUser
Enhanced Description: |
  Creates a new user account in the system.
  
  Requirements:
  - Email must be unique
  - Password must be at least 8 characters
  - Username can only contain alphanumeric characters
  
  Returns the created user object with auto-generated ID.
  
  Example usage:
  "Create a new user with email [email protected]"

​

Parameter Templates

Template: CreateIssue
Parameters:
  project_id: "PROJ"
  priority: "medium"
  issue_type: "task"
  
Usage: 
  "Create an issue in PROJ with these defaults"

​

Response Transformation

• Full Response: Show complete JSON
• Summary: Show key fields only
• Custom Format: Define what to extract
• Error Handling: Custom error messages

​

Webhook Integration

• Configure webhook endpoints
• Receive real-time updates
• Trigger automated workflows
• Enable event-driven actions

​

Troubleshooting

​

Installation Fails

• Verify OpenAPI format
• Use validation tools
• Check for syntax errors
• Ensure all required fields present

• Check URL accessibility
• Verify no authentication required for spec
• Try downloading and uploading as file
• Check firewall settings

​

Authentication Issues

• Verify credentials are correct
• Check if tokens have expired
• Confirm account has API access
• Review authentication method

• Check account permissions
• Verify required scopes granted
• Contact service administrator
• Review API access policies

​

API Calls Failing

• Check internet connection
• Verify API service is online
• Review firewall rules
• Check for rate limiting

• Review required vs optional parameters
• Check parameter data types
• Verify parameter formats
• Review API documentation

• Check API status page
• Review error messages
• Verify data format expectations
• Check for breaking changes in API

​

Next Steps

• Use applications in Copilot to execute API operations
• Create agents with specific application access
• Monitor usage in the dashboard
• View API call logs for debugging