> ## Documentation Index > Fetch the complete documentation index at: https://docs.brosbots.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Tool > Create a new tool. Returns the created tool. ## OpenAPI ````yaml /api-reference/openapi.en.json post /api/v1/tools openapi: 3.1.0 info: title: Brosbots API description: > The public Brosbots REST API. Build and manage voice agents, run outbound campaigns, read calls and usage, and manage phone numbers, tools, knowledge bases and integrations. ## Authentication Every request must include your organization's API key in the `X-API-Key` header: ``` X-API-Key: bb_live_... ``` You create and revoke keys in the dashboard: click your account in the bottom-left corner of the sidebar, then **Brosbots API**. ## Base URL ``` https://app.brosbots.com/api/v1 ``` ## Conventions - Request and response bodies are JSON (`Content-Type: application/json`). - Timestamps are ISO 8601 with a timezone. - Lists are paginated with `page` / `limit` parameters; responses include `total_count` / `total_pages`. - Errors use standard HTTP status codes with a JSON body: `{"detail": "a human-readable reason"}`. - `{agent_id}` accepts the agent's public ID (`agent_...`) or its number. ## Limits There is no fixed per-key request-rate limit today. `429` comes from the calling endpoints (`POST /agents/{agent_id}/calls` and `POST /triggers/{trigger_id}/calls`) when every outbound channel is busy; its `Retry-After` header says how many seconds to wait. Handle `429` generally: wait as long as `Retry-After` says, or back off exponentially when it is absent. A request-rate limit may be introduced. version: 1.0.0 servers: [] security: - ApiKeyAuth: [] paths: /api/v1/tools: post: tags: - Tools summary: Create Tool description: Create a new tool. Returns the created tool. operationId: post_tools parameters: - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' - name: X-API-Key in: header required: false schema: anyOf: - type: string - type: 'null' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateToolRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: CreateToolRequest: properties: name: type: string maxLength: 255 description: anyOf: - type: string - type: 'null' category: type: string default: http_api icon: anyOf: - type: string maxLength: 50 - type: 'null' default: globe icon_color: anyOf: - type: string maxLength: 7 - type: 'null' default: '#3B82F6' definition: oneOf: - $ref: '#/components/schemas/HttpApiToolDefinition' - $ref: '#/components/schemas/EndCallToolDefinition' - $ref: '#/components/schemas/TransferToolDefinition' - $ref: '#/components/schemas/IntegrationToolDefinition' discriminator: propertyName: type mapping: end_call: '#/components/schemas/EndCallToolDefinition' http_api: '#/components/schemas/HttpApiToolDefinition' integration: '#/components/schemas/IntegrationToolDefinition' transfer: '#/components/schemas/TransferToolDefinition' type: object required: - name - definition title: CreateToolRequest description: Request schema for creating a tool. ToolResponse: properties: id: type: integer tool_uuid: type: string name: type: string description: anyOf: - type: string - type: 'null' category: type: string icon: anyOf: - type: string - type: 'null' icon_color: anyOf: - type: string - type: 'null' status: type: string definition: additionalProperties: true type: object created_at: type: string format: date-time updated_at: anyOf: - type: string format: date-time - type: 'null' created_by: anyOf: - $ref: '#/components/schemas/CreatedByResponse' - type: 'null' type: object required: - id - tool_uuid - name - description - category - icon - icon_color - status - definition - created_at - updated_at title: ToolResponse description: Response schema for a tool. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array type: object title: HTTPValidationError HttpApiToolDefinition: properties: schema_version: type: integer description: Schema version default: 1 type: type: string const: http_api description: Tool type config: $ref: '#/components/schemas/HttpApiConfig' description: HTTP API configuration type: object required: - type - config title: HttpApiToolDefinition description: Tool definition for HTTP API tools. EndCallToolDefinition: properties: schema_version: type: integer description: Schema version default: 1 type: type: string const: end_call description: Tool type config: $ref: '#/components/schemas/EndCallConfig' description: End Call configuration type: object required: - type - config title: EndCallToolDefinition description: Tool definition for End Call tools. TransferToolDefinition: properties: schema_version: type: integer description: Schema version default: 1 type: type: string const: transfer description: Tool type config: $ref: '#/components/schemas/TransferConfig' description: Transfer configuration type: object required: - type - config title: TransferToolDefinition description: Tool definition for Transfer Call tools. IntegrationToolDefinition: properties: schema_version: type: integer description: Schema version default: 1 type: type: string const: integration description: Tool type config: $ref: '#/components/schemas/IntegrationConfig' description: Integration configuration type: object required: - type - config title: IntegrationToolDefinition description: Tool definition for pre-built integration tools. CreatedByResponse: properties: id: type: integer provider_id: type: string type: object required: - id - provider_id title: CreatedByResponse description: Response schema for the user who created a tool. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array msg: type: string type: type: string type: object required: - loc - msg - type title: ValidationError HttpApiConfig: properties: method: type: string description: HTTP method (GET, POST, PUT, PATCH, DELETE) url: type: string description: Target URL headers: anyOf: - additionalProperties: type: string type: object - type: 'null' description: Static headers to include credential_uuid: anyOf: - type: string - type: 'null' description: ID of the stored credential used for authentication. parameters: anyOf: - items: $ref: '#/components/schemas/ToolParameter' type: array - type: 'null' description: Parameters that the tool accepts from LLM timeout_ms: anyOf: - type: integer - type: 'null' description: Request timeout in milliseconds default: 5000 trigger_phrases: anyOf: - items: type: string type: array - type: 'null' description: What callers say when this tool is the right one wait_message: anyOf: - type: string - type: 'null' description: Said to the caller while the request runs response_fields: anyOf: - items: type: string type: array - type: 'null' description: Dotted paths of the response fields read back to the model error_message: anyOf: - type: string - type: 'null' description: What the agent tells the caller when the request fails template_id: anyOf: - type: string - type: 'null' description: Wizard template the tool was created from type: object required: - method - url title: HttpApiConfig description: Configuration for HTTP API tools. EndCallConfig: properties: messageType: type: string enum: - none - custom description: Type of goodbye message default: none customMessage: anyOf: - type: string - type: 'null' description: Custom message to play before ending the call type: object title: EndCallConfig description: Configuration for End Call tools. TransferConfig: properties: destination_number: anyOf: - type: string - type: 'null' description: Default phone number to transfer to (E.164) message: anyOf: - type: string - type: 'null' description: Message spoken before transferring parameters: anyOf: - items: $ref: '#/components/schemas/ToolParameter' type: array - type: 'null' description: >- Parameters the LLM can pass. A destination_number it passes is used only when it is one of the numbers configured on the agent. type: object title: TransferConfig description: Configuration for Transfer Call tools. IntegrationConfig: properties: provider: type: string description: Integration provider, e.g. 'weather' or 'crm_lookup' action: anyOf: - type: string - type: 'null' description: Provider action parameters: anyOf: - items: $ref: '#/components/schemas/ToolParameter' type: array - type: 'null' description: Parameters the LLM can pass to the integration crm_type: anyOf: - type: string - type: 'null' description: CRM to query, e.g. 'hubspot' api_key: anyOf: - type: string - type: 'null' description: API key for the CRM type: object required: - provider title: IntegrationConfig description: Configuration for pre-built integration tools (weather, CRM lookup...). ToolParameter: properties: name: type: string description: Parameter name (used as key in request body) type: type: string description: 'Parameter type: string, number, or boolean' description: type: string description: Description of what this parameter is for required: type: boolean description: Whether this parameter is required default: true type: object required: - name - type - description title: ToolParameter description: A parameter that the tool accepts. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- Your organization's API key (account in the bottom-left of the dashboard → Brosbots API). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.