> ## Documentation Index > Fetch the complete documentation index at: https://docs.sigmamind.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Tool > Creates a new API tool under the specified integration. Define the HTTP endpoint, method, and parameter schema the agent will use when invoking the tool. Returns the created tool including its toolId, which is required for subsequent get, update, delete, and execute calls. ## OpenAPI ````yaml post /v1/integrations/{integrationId}/tools openapi: 3.0.1 info: title: SigmaMind APIs description: OpenAPI documentation SigmaMind Agent Builder APIs version: '1.0' servers: - url: https://api.sigmamind.ai description: SigmaMind AI Agent Builder APIs security: - apiKeyAuth: [] tags: - name: Chats description: >- Endpoints for creating and managing text-based chat sessions with an agent. A session is started by specifying an agent and an opening message. Returns a chatId used in all subsequent get, update, completion, and end-session calls. - name: Calls description: >- Endpoints for creating and managing outbound phone calls. A call is initiated by specifying an agent, caller number, and destination number — dynamic variables can be included to personalise the agent's behaviour. Returns a callId used in all subsequent get and delete operations. - name: Phone Numbers description: >- Endpoints for managing phone numbers used in outbound and inbound calls. Supports purchasing a new number through SigmaMind or importing an existing number via SIP trunking (BYO). Each number can be assigned separate inbound and outbound agents. - name: Campaigns description: >- Endpoints for creating and managing outbound call campaigns. A campaign dials a CSV-uploaded contact list using a selected agent and caller number, with support for immediate or scheduled launch. Returns a campaignId used in all subsequent get, update, and delete operations. - name: Agents description: >- Endpoints for creating and managing single prompt agents. An agent is configured with a system prompt, voice settings, and optional tools. Returns an agentId used in all subsequent update, call, and simulation operations. - name: Integrations description: >- Endpoints for creating and managing third-party integrations (e.g. Shopify, Cal.com). An integration links your account to an external service and acts as the parent resource for auth credentials and API tools. Returns an integrationId used in all subsequent auth and tool operations. - name: Integration Auth description: >- Endpoints for managing authentication credentials for a third-party integration. Supports API Key, Basic, and Bearer token credential types — scoped to an integration and injected automatically by tools when executing. Returns an authId used in all subsequent get, update, and delete operations. - name: Integration Tools description: >- Endpoints for creating and managing API tools backed by a third-party integration. Each tool defines an HTTP endpoint, method, and parameter schema — scoped to an integration and using its stored auth credentials when executing. Returns a toolId used in all subsequent get, update, delete, and execute operations. - name: Webhooks description: >- Endpoints for registering and managing webhooks. A webhook delivers real-time event notifications via HTTP POST when selected events occur on a specific agent — each webhook is scoped to one agent and one or more event types. Payloads are signed with an HMAC secret — verify the signature on your server to confirm authenticity. - name: Test Cases description: >- Endpoints for creating and managing simulation test cases for an agent. A test case defines a conversation scenario — including user persona, goals, and expected behaviour — used to generate a synthetic conversation with the agent. Returns a testCaseId used in all subsequent get, update, delete, and batch-run operations. - name: Batch Runs description: >- Endpoints for creating and managing batch runs of simulation test cases. A batch run executes multiple test cases in parallel against a selected agent and aggregates the results for review. Returns a batchId used in all subsequent get and list test-run operations. - name: Test Runs description: >- Endpoints for retrieving test run results within a batch. Each test run represents a single test case execution within a batch run, identified by a jobId. Use batchId and agentId to scope results to the correct batch. - name: API Keys description: >- Endpoints for creating and managing API keys used to authenticate public API requests. Each key must be included in the X-API-Key request header. Returns a keyId used in all subsequent get, revoke, and delete operations. - name: QA Rules description: >- Endpoints for creating and managing quality assurance rules applied to agent conversations. A QA rule defines evaluation criteria used to automatically assess conversation quality. Returns a qaRuleId used in all subsequent get, update, and delete operations. - name: QA Issues description: >- Endpoints for retrieving and managing quality assurance issues flagged across agent conversations. A QA issue is created with status 'Fail' when a conversation violates one or more QA rules — capturing the offending rule reference. It is created with status 'Success' when the conversation passes the evaluation criteria of QA rule(s). Returns a qaIssueId used in all subsequent get operations. paths: /v1/integrations/{integrationId}/tools: post: tags: - Integration Tools summary: Create Tool description: >- Creates a new API tool under the specified integration. Define the HTTP endpoint, method, and parameter schema the agent will use when invoking the tool. Returns the created tool including its toolId, which is required for subsequent get, update, delete, and execute calls. operationId: createIntegrationTool parameters: - name: integrationId in: path description: Unique identifier of the integration to create the tool under. required: true schema: type: string example: intg_AuUKK371Spr5 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateIntegrationToolRequest' required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/IntegrationToolResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/integrations/{integrationId}/tools status: 400 timestamp: '2026-05-05T10:06:45.788Z' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/integrations/{integrationId}/tools status: 401 timestamp: '2026-05-05T10:06:45.788Z' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/integrations/{integrationId}/tools status: 403 timestamp: '2026-05-05T10:06:45.788Z' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/integrations/{integrationId}/tools status: 404 timestamp: '2026-05-05T10:06:45.788Z' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/integrations/{integrationId}/tools status: 500 timestamp: '2026-05-05T10:06:45.788Z' components: schemas: CreateIntegrationToolRequest: required: - description - method - name - url type: object properties: name: maxLength: 128 minLength: 0 type: string description: >- Action-oriented, snake_case name that uniquely identifies this tool within the integration. AI agents use this name to select the correct tool when deciding which operation to invoke. Must be unique within the integration. Good examples: 'get_customer', 'create_order', 'cancel_subscription'. example: get_customer description: maxLength: 1024 minLength: 0 type: string description: >- Explanation of what this tool does and the exact conditions under which an AI agent should invoke it. Agents rely on this description to match a task to the correct tool — be specific about the action, the resource it operates on, and any inputs the agent must supply. example: >- Fetches a Shopify customer record by customer ID. Call this tool when you need to look up customer details such as name, email, or order history. method: type: string description: >- HTTP method used when invoking this tool's endpoint. GET retrieves a resource without side effects. POST creates a new resource. PUT fully replaces an existing resource. PATCH partially updates an existing resource. DELETE removes a resource. example: GET enum: - GET - POST - PUT - PATCH - DELETE url: maxLength: 1024 minLength: 0 type: string description: >- Full URL of the API endpoint this tool calls. Supports {{variable}} placeholders for path segments the agent resolves at runtime (e.g., {{customerId}} in the path). Path variables embedded here do not need to be redeclared in queryParams. example: >- https://my-store.myshopify.com/admin/api/2024-01/customers/{{customerId}}.json headers: type: array description: >- Static HTTP headers sent on every request made by this tool. Merged with headers defined at the integration and auth levels; tool-level headers take precedence on key conflicts. Values may contain {{variable}} placeholders resolved by the agent at runtime. Leave empty if no tool-specific headers are needed. example: - key: Content-Type value: application/json items: $ref: '#/components/schemas/HeaderEntry' queryParams: type: array description: >- Query string parameters appended to the URL on every invocation (e.g., ?status=active&limit=10). Values support {{variable}} placeholders so the agent can supply them at runtime. Path variables already embedded in the URL using {{variable}} syntax do not need to be listed here. example: - key: status value: '{{status}}' items: $ref: '#/components/schemas/QueryParam' bodyParams: type: object description: >- Request body payload sent when this tool is invoked, as a JSON object. Values support {{variable}} placeholders that the agent resolves at runtime. Provide only for POST, PUT, and PATCH tools. Leave empty or omit for GET and DELETE — body content is ignored for those methods. example: first_name: '{{firstName}}' email: '{{email}}' additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array description: >- Request body to create a new API tool under an integration. A tool represents a single callable API operation — for example 'get_customer' or 'create_order' — that an AI agent can invoke at runtime. Dynamic values are declared using {{variable}} placeholders in the URL, headers, query params, or body; the agent resolves these at invocation time. IntegrationToolResponse: type: object properties: toolId: type: string description: >- Unique identifier for this tool. Use this value as toolId when executing, updating, or deleting this tool. example: tool_X9pLm2Wq8Rt3 integrationId: type: string description: >- Unique identifier of the integration this tool belongs to. Use this value as integrationId when making requests scoped to the parent integration. example: intg_AuUKK371Spr5 name: type: string description: >- Action-oriented name for this tool that identifies the operation it performs. AI agents use this name to match a task to the correct tool. Follows snake_case convention (e.g., 'get_customer', 'create_order'). example: get_order_details description: type: string description: >- Explanation of what this tool does and when an AI agent should invoke it. Agents rely on this description to decide whether this tool matches the current task. A good description names the action, the resource it operates on, and required inputs. example: >- Fetches order details from Shopify by order ID. Call this tool when you need to retrieve order status, line items, or shipping info. method: type: string description: >- HTTP method used when invoking this tool's endpoint. GET retrieves a resource without side effects. POST creates a new resource. PUT fully replaces an existing resource. PATCH partially updates an existing resource. DELETE removes a resource. example: GET enum: - GET - POST - PUT - PATCH - DELETE url: type: string description: >- Full URL of the API endpoint this tool calls, including any {{variable}} placeholders that the agent resolves at runtime using the declared parameters. Path segments wrapped in {{}} (e.g., {{orderId}}) are substituted before the request is sent. example: >- https://my-store.myshopify.com/admin/api/2024-01/orders/{{orderId}}.json scope: type: string description: >- Visibility scope of this tool. 'local' means the tool is private to your account and only accessible within your integrations. 'community' means the tool is shared and discoverable by other users. example: local enum: - local - community headers: $ref: '#/components/schemas/JsonNode' queryParams: $ref: '#/components/schemas/JsonNode' bodyParams: $ref: '#/components/schemas/JsonNode' createdAt: type: string description: >- UTC timestamp when this tool was created, in ISO 8601 format. Use for auditing or determining how long the tool has been active. format: date-time example: '2024-04-20T10:00:00.000Z' updatedAt: type: string description: >- UTC timestamp when this tool was last modified, in ISO 8601 format. Use to detect configuration changes or invalidate cached tool definitions. format: date-time example: '2024-04-21T08:30:00.000Z' description: >- Represents a single callable API tool registered under an integration. Each tool maps to one specific API operation (e.g., 'Get Order', 'Create Customer') and carries its full invocation config: HTTP method, endpoint URL, headers, and parameters. AI agents use this response to understand what the tool does and how to invoke it. Error: type: object properties: timestamp: type: string description: Error timestamp in ISO format format: date-time status: type: integer description: HTTP status code example: 400 error: type: string description: Error type or HTTP status message example: Bad Request message: type: string description: Detailed error message example: Email is required path: type: string description: Request path where error occurred example: /v1/users validationErrors: type: object description: Field validation errors (if any) example: |- { "email": "Email is required", "name": "Name is too short" } description: Standard error response HeaderEntry: required: - key - value type: object properties: key: maxLength: 256 minLength: 0 type: string description: HTTP header name exactly as expected by the target API. example: Content-Type value: maxLength: 1024 minLength: 0 type: string description: >- Static value for this header sent with every request. Must be a fixed string — use queryParams or bodyParams for dynamic values. example: application/json description: >- A single static HTTP header included in every request made by this tool. Tool-level headers are merged with integration-level and auth-level headers; tool-level values take precedence on key conflicts. example: - key: Content-Type value: application/json QueryParam: required: - key type: object properties: key: maxLength: 128 minLength: 0 type: string description: Query parameter name as expected by the target API. example: status value: maxLength: 1024 minLength: 0 type: string description: >- Value for this query parameter. Use a {{variable}} placeholder for values the agent supplies at runtime. Static string values are also accepted for fixed parameters. example: '{{status}}' description: >- A single query string parameter appended to the request URL at invocation time. Use {{variable}} placeholders in values for parameters the agent supplies dynamically. Path variables embedded in the endpoint URL using {{variable}} syntax are separate and do not need to be declared here. example: - key: status value: '{{status}}' JsonNode: type: object description: >- Dynamic key-value pairs that were passed to the agent at call start for personalisation. Keys correspond to variable names defined in the agent's configuration (e.g., 'customer_name', 'account_id'). Null or empty if no dynamic variables were provided when the call was created. example: customer_name: Michael account_id: ACC-001 securitySchemes: apiKeyAuth: type: apiKey description: >- Authenticate every request by passing your API key in the `X-API-Key` header. To get your key, go to Dashboard → API Keys and create or copy your Production API key. name: X-API-Key in: header ````