# API Tools
## Introduction
API Tools are a set of interfaces and helper utilities designed specifically for intelligent agents to call external services, retrieve data, or perform various tasks. They enable agents to automate operations and enhance their capabilities and flexibility.
* **Invoke external APIs**: Allow agents to access third-party or internal APIs for data querying, writing, and more.
* **Unified interface management**: Standardize and manage all API requests centrally for easier maintenance and scalability.
* **Parameter validation and formatting**: Automatically verify parameters and support necessary format conversions.
* **Asynchronous calls and error handling**: Improve call efficiency and handle exceptions gracefully.
## Creation
First, select the **Tool** panel. Here, you can choose either **Create From Blank** or **Create From Template**. In this example, we’ll go with the first option — **Create From Blank**.
After clicking **Create**, you will be redirected to the **Tool Creation Panel**, where you need to configure the following information:
* **Avatar**\
The icon or image representing your tool. This helps visually identify the tool in the interface.
* **Name**\
The internal name of the tool. **Tool name can only contain letters, numbers, and underscores** (e.g., `my_custom_tool`). This name is used programmatically and must follow naming rules.
* **Display Name**\
The name shown to users, such as when the tool is used by an agent. **There are no restrictions on characters**, so you can use spaces, symbols, or non-English characters if needed (e.g., `My Custom Tool`).
* **Description**\
A brief explanation of what the tool does. This helps others (and yourself) understand the purpose of the tool at a glance.
* **Create Tool Type**\
Choose the type of tool to create.
When creating an API Tool, you need to additionally configure some properties:
### API Schema
You can provide the OpenAPI specification in either JSON or YAML text format.\
Here is a sample JSON for a library API:
```json
{
"openapi": "3.0.3",
"info": {
"title": "Library API",
"version": "1.0.0",
"description": "Manage books and authors in a library system"
},
"servers": [
{
"url": "https://api.library.example.com/v1",
"description": "Production server"
}
],
"paths": {
"/books": {
"get": {
"summary": "List all books",
"operationId": "listBooks",
"responses": {
"200": {
"description": "A list of books",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": { "$ref": "#/components/schemas/Book" }
}
}
}
}
}
},
"post": {
"summary": "Add a new book",
"operationId": "createBook",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/BookInput" }
}
}
},
"responses": {
"201": { "description": "Book created successfully" },
"400": { "description": "Invalid input" }
}
}
},
"/books/{bookId}": {
"parameters": [
{
"name": "bookId",
"in": "path",
"required": true,
"schema": { "type": "integer", "format": "int64" }
}
],
"get": {
"summary": "Get a book by ID",
"operationId": "getBook",
"responses": {
"200": {
"description": "Book details",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Book" }
}
}
},
"404": { "description": "Book not found" }
}
},
"delete": {
"summary": "Delete a book",
"operationId": "deleteBook",
"responses": {
"204": { "description": "Book deleted" },
"404": { "description": "Book not found" }
}
}
}
},
"components": {
"schemas": {
"Book": {
"type": "object",
"required": ["id", "title", "author"],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 101
},
"title": {
"type": "string",
"example": "The Great Gatsby"
},
"author": {
"type": "string",
"example": "F. Scott Fitzgerald"
},
"publishedDate": {
"type": "string",
"format": "date",
"example": "1925-04-10"
}
}
},
"BookInput": {
"type": "object",
"required": ["title", "author"],
"properties": {
"title": { "type": "string" },
"author": { "type": "string" },
"publishedDate": {
"type": "string",
"format": "date"
}
}
}
}
}
}
```
***
### Authorization Type
You can select either **None** or **API-Key**.\
If you choose **API-Key**, you need to configure the following two properties to specify the header name and the corresponding API key value:
* **Header**\
The name of the header where the API key should be sent (e.g., `Authorization` or `x-api-key`).
* **API Key**\
The actual API key value used for authentication.
After successfully configuring the properties and creating the tool, you will be redirected to the **API Tool** panel. Here, you can review the imported **API Endpoints** and modify the OpenAPI schema at any time — simply edit the text above, and your changes will be saved automatically.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.workfx.ai/workfx-companion-agent-knowledge/workforce-factory/tools/api-tools.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.