OpenAPI

​

Introduction

• Standardized API Documentation: Define API structure using JSON or YAML format with consistent schema
• Operation Definitions: Each API endpoint has an operationId, description, parameters, and response schemas
• Authentication Schemes: Built-in support for various authentication methods including API Key, OAuth 2.0, and Basic Auth
• Request/Response Validation: Schema definitions ensure data consistency and validation
• Tool Generation: Enables automated tool creation from API documentation
• Multi-Language Support: Works across programming languages and platforms

• JSON (recommended for consistency and broad compatibility)
• YAML (also fully supported for human readability)
• URL (pointing to publicly accessible OpenAPI specifications)
• Raw text (containing complete specification content)

​

Toolkit’s Account Setup and Configuration

​

API Access Requirements

1. OpenAPI Specification File: The complete API documentation in OpenAPI format (JSON or YAML)
2. API Access: Valid credentials or API keys if the API requires authentication
3. Base URL: The API’s base URL

1. From API Provider: Most API providers publish their OpenAPI specifications in their developer documentation. Look for links labeled “API Specification,” “OpenAPI Schema,” or “Swagger Documentation.”
2. Generate from Code: If you have access to the API implementation, many frameworks can automatically generate OpenAPI specifications (e.g., FastAPI for Python, Swashbuckle for .NET, SpringDoc for Java).
3. Manual Creation: Use Swagger Editor to create or edit OpenAPI specifications manually.
4. Convert YAML to JSON: If you have a YAML specification and prefer JSON, use Swagger Editor or online conversion tools.

​

Authentication Credentials

• API Key or Token value
• Authentication type (Bearer, Basic, or Custom Header)
• Custom header name (if using Custom authentication type)

• Client ID
• Client Secret
• Token URL (OAuth token endpoint)
• Authorization URL (optional, for authorization code flows)
• Scope (optional, space-separated permissions)

• No authentication credentials required

​

System Integration with ELITEA

​

Step 1: Create OpenAPI Configuration Credentials

1. Navigate to Credentials Menu: Open the sidebar and select Credentials.
2. Create New Credential: Click the + Create button.
3. Select OpenAPI Configuration: Choose OpenAPI Configuration as the credential type.
4. Configure Credential Details:
   • Display Name: Enter a descriptive name (e.g., “GitHub API - Production”, “Petstore API Key”)
5. Configure Authentication Method: Choose one of the following based on your API requirements:
   • API Key Authentication: For Bearer tokens, Basic auth, or Custom headers
   • OAuth 2.0 Authentication: For OAuth flows
   • Anonymous: For public APIs without authentication requirements
6. Fill Authentication Fields: Depending on your selected authentication method (see Authentication Methods Reference below for detailed field descriptions)
7. Save Credential: Click Save to create the credential

​

Authentication Methods Reference

• Select the Anonymous option when creating your OpenAPI Configuration credential
• Leave all authentication fields empty
• No authentication headers will be added to requests
• Note: Uncommon for production APIs; most APIs require some form of authentication

1. Api Key (Required)
   • Your API key or token value
   • Can reference ELITEA Secrets for enhanced security
2. Auth Type (Required)

​

Step 2: Create OpenAPI Toolkit

1. Navigate to Toolkits Menu: Open the sidebar and select Toolkits.
2. Create New Toolkit: Click the + Create button.
3. Select OpenAPI: Choose OpenAPI from the list of available toolkit types.
4. Configure Toolkit Details:
   • Toolkit Name: Enter a descriptive name for your toolkit (e.g., “GitHub API - Public Repos”, “Petstore API”)
   • Description: Optional multiline text field for adding context about your toolkit and its purpose.
5. Configure Credentials:
   • OpenAPI credentials configuration: Select your previously created OpenAPI Configuration credential from the dropdown (created in Step 1). For public APIs without authentication, select an Anonymous credential.
6. Configure Base URL (Optional):
   • Base Url: Enter an absolute base URL (starting with http:// or https://) if your OpenAPI specification uses relative server URLs (e.g., /api/v3) or has no servers entry. Example: https://petstore3.swagger.io. Leave empty if your specification already contains absolute server URLs.
7. Configure OpenAPI Specification:
   • Schema: Provide your OpenAPI specification using one of these methods:
     • Copy & Paste: Copy the complete JSON or YAML content and paste directly into the field
     • Drag & Drop: Drag your specification file (.json, .yaml, .yml) directly into the Schema field
     • File Upload: Click the “choose file” link and select your specification file
   • The editor supports both JSON and YAML syntax highlighting
   • Click the fullscreen icon (⛶) for an expanded editing view when working with large specifications
8. Review Available API Endpoints (Tools): After providing a valid specification, the “Api Endpoints” accordion displays all available operations. Each operation with operationId becomes an available tool. You can expand rows to view details, sort by columns, and navigate using pagination for large specifications.
9. Save Toolkit: Click Save to create the toolkit

​

Understanding Generated Tools

• Tool names come directly from the operationId field in your OpenAPI specification
• Example: If your spec has operationId: "getPetById", the tool will be named getPetById
• Important: If an operation lacks an operationId, it will be skipped (not available as a tool)

1. View Available Tools: Navigate to your saved toolkit to see the TOOLS section displaying all generated operations
2. Select a Tool: Click on any tool from the TOOLS list to open it
3. Test in TEST SETTINGS Panel: Use the TEST SETTINGS panel on the right side to:
   • Configure required parameters (path, query, headers)
   • Provide request body data for POST/PUT/PATCH operations
   • Execute the tool and view the API response
   • Verify authentication and endpoint connectivity
   • Debug parameter configurations before using in agents

​

Step 3: Use OpenAPI Toolkit in Agents

​

In Agents:

1. Navigate to Agents: Open the sidebar and select Agents.
2. Create or Edit Agent: Click + Create for a new agent or select an existing agent to edit.
3. Add OpenAPI Toolkit:
   • In the “TOOLKITS” section of the agent configuration, click the “+Toolkit” icon
   • Select your OpenAPI toolkit from the dropdown menu
   • The toolkit will be added to your agent with all configured API endpoints available as tools

​

In Pipelines:

1. Navigate to Pipelines: Open the sidebar and select Pipelines.
2. Create or Edit Pipeline: Either create a new pipeline or select an existing pipeline to edit.
3. Add OpenAPI Toolkit:
   • In the “TOOLKITS” section of the pipeline configuration, click the “+Toolkit” icon
   • Select your OpenAPI toolkit from the dropdown menu
   • The toolkit will be added to your pipeline with all configured API endpoints available

​

In Chat:

1. Navigate to Chat: Open the sidebar and select Chat.
2. Start New Conversation: Click +Create or open an existing conversation.
3. Add Toolkit to Conversation:
   • In the chat Participants section, look for the Toolkits element
   • Click to add a toolkit and select your OpenAPI toolkit from the available options
   • The toolkit will be added to your conversation with all API endpoints available as tools
4. Use Toolkit in Chat: You can now directly interact with your API by asking questions or requesting actions that will trigger the OpenAPI toolkit tools.

​

Instructions and Prompts for Using the OpenAPI Toolkit

​

Instruction Creation for OpenAI Agents

• Direct and Action-Oriented: Employ strong action verbs and clear commands to initiate actions. For example, “Use the ‘getPetById’ tool…”, “Create a task named…”, “Retrieve user data for…”.
• Parameter-Centric: Clearly enumerate each parameter required by the tool. For each parameter, specify:
  • Its name (exactly as defined in the OpenAPI specification)
  • Its expected data type (string, integer, object, array, etc.)
  • How the Agent should obtain the value – whether from user input, derived from previous steps in the conversation, retrieved from an external source, or a predefined static value
• Contextually Rich: Provide sufficient context so the Agent understands the overarching objective and the specific scenario in which each API tool should be applied within the broader workflow. Explain the desired outcome or goal for each tool invocation.
• Step-by-Step Structure: Organize instructions into a numbered or bulleted list of steps for complex workflows. This helps the Agent follow a logical sequence of actions.
• Add Conversation Starters: Include example conversation starters that users can use to trigger this functionality. For example, “Conversation Starters: ‘Show me pet with ID 42’, ‘Create a new pet named Fluffy’, ‘List all available pets’”

1. State the Goal: Begin by clearly stating the objective you want to achieve with this step. For example, “Goal: To retrieve details of a specific pet by its ID.”
2. Specify the Tool: Clearly indicate the specific API tool (operationId) to be used for this step. For example, “Tool: Use the ‘getPetById’ tool.”
3. Define Parameters: Provide a detailed list of all parameters required by the selected tool. For each parameter:
   • Parameter Name: <Parameter Name as defined in OpenAPI specification>
   • Value or Source: <Specify the value or how to obtain the value. Examples: "user input", "from previous step", "hardcoded value '123'", "value of variable X">
4. Describe Expected Outcome (Optional but Recommended): Briefly describe the expected result or outcome after the tool is successfully executed. For example, “Outcome: The Agent will display the full details of the specified pet.”
5. Add Conversation Starters: Include example conversation starters that users can use to trigger this functionality. For example, “Conversation Starters: ‘Show me pet 42’, ‘Get details for pet ID 123‘“

​

Example Agent Instruction

You have access to the Petstore API with the following tools:
- getPetById: Retrieve a pet by ID (requires petId parameter)
- addPet: Add a new pet (requires body_json with pet details)
- updatePet: Update existing pet (requires petId and body_json)
- deletePet: Delete a pet (requires petId parameter)

## When the user asks about a specific pet:
1. Use getPetById tool with the provided pet ID (must be an integer)
2. Present the pet information clearly including name, status, category, and photo URLs

Example interaction:
User: "Show me details for pet 42"
Tool call: getPetById(petId=42)
Response: Display pet name, status, and other details

## When the user wants to add a pet:
1. Collect required information (name, category, status, photo URLs)
2. Use addPet tool with properly formatted body_json:
   {
     "name": "string",
     "category": {"id": 0, "name": "string"},
     "status": "available",
     "photoUrls": ["string"]
   }
3. Confirm successful creation with the pet ID

## When the user wants to update a pet:
1. Get the pet ID and fields to update
2. Use updatePet tool with petId and body_json containing updated fields
3. Confirm the changes were applied

## When the user wants to delete a pet:
1. Confirm the pet ID to delete
2. Use deletePet tool with the petId parameter
3. Confirm successful deletion

## Parameter Guidelines:
- Path Parameters: Include as named arguments (e.g., petId=123)
- Query Parameters: Include as named arguments (e.g., status="available")
- Request Bodies: Pass as body_json string containing valid JSON
- Headers: Authentication headers are automatically applied

## Conversation Starters:
- "Show me pet 42"
- "Add a new pet named Fluffy"
- "Update pet 123 status to sold"
- "Delete pet 456"

​

Chat Usage Example

User: "Show me the details of pet 42."

ELITEA Response: [ELITEA uses getPetById tool with petId=42]

🐾 **Pet Details** (ID: 42):

- **Name**: Fluffy
- **Category**: Dogs
- **Status**: Available
- **Photo URLs**: 
  - https://example.com/photos/fluffy1.jpg
  - https://example.com/photos/fluffy2.jpg

This pet is currently available for adoption.

​

Use Cases

Agent Instructions:
"You have access to the Sales CRM API. Use the following tools:
- getSalesData: Retrieve sales records (parameters: startDate, endDate, region)
- getCustomerDetails: Get customer information (parameter: customerId)
- getProductAnalytics: Analyze product performance (parameters: productId, period)

When analyzing sales:
1. Fetch data for the requested period
2. Calculate key metrics (total revenue, top customers, regional performance)
3. Present insights in a clear, structured format"

Agent Instructions:
"You manage tasks in the Project Management API:
- createTask: Create new tasks (required: title, description; optional: dueDate, assignee, priority)
- updateTask: Modify existing tasks (required: taskId; optional: any field to update)
- deleteTask: Remove tasks (required: taskId)
- listTasks: Get all tasks (optional: projectId, status filter)

Task Management Guidelines:
- Always confirm task details before creation
- Include relevant project context
- Set realistic due dates
- Assign to appropriate team members"

Agent Instructions:
"You orchestrate order fulfillment using multiple APIs:

Order API:
- getNewOrders: Fetch pending orders
- updateOrderStatus: Mark order progress

Inventory API:
- checkStock: Verify product availability
- reduceInventory: Deduct ordered quantities

Email API:
- sendOrderConfirmation: Email customer confirmation
- sendShippingNotification: Email tracking information

Workflow:
1. Check for new orders every hour
2. Verify inventory availability
3. Update inventory levels
4. Send customer confirmation
5. Update order status to 'processing'"

Agent Instructions:
"You coordinate development workflow across tools:

GitHub API:
- getPullRequests: Fetch open PRs
- mergePullRequest: Merge approved PRs

Jira API:
- getIssueDetails: Fetch issue information
- updateIssueStatus: Move issues through workflow

Slack API:
- postMessage: Send notifications to channels

Workflow:
1. Monitor GitHub for approved pull requests
2. Check associated Jira issues
3. Merge PR if requirements met
4. Update Jira issue to 'Done'
5. Notify team in Slack"

​

Common Integration Patterns

​

Troubleshooting and Support

​

Troubleshooting

​

FAQ

​

Support Contact