> ## Documentation Index > Fetch the complete documentation index at: https://docs.kejue.co/llms.txt > Use this file to discover all available pages before exploring further. # Create Tool > Create a new custom HTTP tool. ## OpenAPI ````yaml /openapi.json post /tools openapi: 3.1.0 info: title: Kejue Public API description: >- The Kejue Public API lets you programmatically create calls, manage campaigns, and retrieve call results. ## Authentication All requests require an API key passed in the `X-API-Key` header: ``` X-API-Key: kej_live_... ``` API keys are scoped to a workspace. Create and manage keys from the Kejue dashboard under **Settings → API Keys**. ## Base URL ``` https://api.kejue.co/api/v1 ``` ## Rate Limits API requests are rate-limited per workspace. If you exceed the limit you'll receive a `429 Too Many Requests` response. ## Errors All error responses follow a consistent format: ```json { "error": "Human-readable message", "code": "ERROR_CODE", "details": {} } ``` version: 1.0.0 servers: - url: https://api.kejue.co/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Agents description: >- Create and manage AI agents (personas). Each agent has a name, prompt, voice configuration, and optional tools. Agents are the core building block — attach voice configs, tools, and use them to make calls. - name: Calls description: >- Create outbound calls, retrieve call details and transcripts, and list calls with filtering. Each call is associated with a contact and optionally an agent and campaign. - name: Persona Calls description: >- Create calls with the full agent configuration pre-loaded. Applies the complete settings hierarchy (workspace → agent → campaign → overrides) with all agent tools, tags, scoring, and webhooks inherited automatically. - name: Contacts description: >- Create and manage contacts. Contacts represent the people your agents call. Each contact has a phone number, name, and optional metadata. Supports single creation, bulk import, and CSV upload. - name: Campaigns description: >- Create and manage calling campaigns. Campaigns let you batch-call a list of contacts with shared settings, scheduling, and retry logic. - name: Tools description: >- Create and manage custom HTTP tools that agents can invoke during calls. Tools let agents fetch data, trigger actions, or integrate with external systems mid-conversation. Each tool supports three parameter types: - **Dynamic parameters** — filled by the AI at runtime (visible to the AI) - **Static parameters** — fixed values sent with every invocation (hidden from the AI) - **System parameters** — values injected from the execution context at runtime, such as `call_id`, `contact_id`, or `workspace_id` (hidden from the AI) - name: Voices description: List available voices for use in agent voice configurations. - name: Phone Numbers description: List phone numbers available in your workspace for making outbound calls. - name: Webhooks description: >- Create and manage webhook subscriptions. Receive real-time notifications for call events (started, ended, etc.) at your specified URL. - name: Models description: List available AI models for use in agent voice configurations. paths: /tools: post: tags: - Tools summary: Create Tool description: Create a new custom HTTP tool. operationId: create_tool_tools_post parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTool' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '400': description: >- The tool config references one or more workspace secrets that do not exist. content: application/json: example: error: 'Unknown secrets referenced: my_api_key' code: BAD_REQUEST details: {} schema: $ref: '#/components/schemas/ErrorResponse' '401': description: >- Missing or invalid API key. Pass a workspace API key in the `X-API-Key` header. content: application/json: example: error: Invalid or missing API key code: UNAUTHORIZED details: {} schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Another tool in this workspace already uses this name. content: application/json: example: error: Tool with name 'send_email' already exists code: CONFLICT details: {} schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request body or query parameters failed validation. content: application/json: example: error: Validation failed code: VALIDATION_ERROR details: errors: - field: body.name message: Field required type: missing schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyAuth: [] components: schemas: CreateTool: properties: name: type: string maxLength: 100 minLength: 1 title: Name description: Tool name (unique per workspace) display_name: anyOf: - type: string - type: 'null' title: Display Name description: Display name description: anyOf: - type: string - type: 'null' title: Description description: Description of when the tool should be used http_config: $ref: '#/components/schemas/HttpConfigInput' description: HTTP configuration dynamic_parameters: anyOf: - items: $ref: '#/components/schemas/DynamicParameterInput' type: array - type: 'null' title: Dynamic Parameters description: Parameters provided by the AI agent at runtime with location routing static_parameters: anyOf: - items: $ref: '#/components/schemas/StaticParameterInput' type: array - type: 'null' title: Static Parameters description: Fixed parameters always sent with requests response_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Response Schema description: Expected response format timeout: type: integer maximum: 60000 minimum: 1000 title: Timeout description: Tool timeout in milliseconds default: 30000 retry_count: type: integer maximum: 5 minimum: 0 title: Retry Count description: Number of retries on failure default: 0 precomputable: type: boolean title: Precomputable description: >- Voice only: if true, Ultravox may invoke this tool speculatively. Safe only for non-mutating tools. Ignored for chat. default: false agent_reaction: $ref: '#/components/schemas/AgentReaction' description: >- Voice only: how the agent reacts when this tool fires. Ignored for chat. default: speaks type: object required: - name - http_config title: CreateTool description: Create a custom HTTP tool. ToolResponse: properties: id: type: string title: Id name: type: string title: Name display_name: anyOf: - type: string - type: 'null' title: Display Name description: anyOf: - type: string - type: 'null' title: Description tool_type: type: string title: Tool Type http_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Http Config parameters: anyOf: - additionalProperties: true type: object - type: 'null' title: Parameters response_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Response Schema timeout: type: integer title: Timeout retry_count: type: integer title: Retry Count precomputable: type: boolean title: Precomputable default: false agent_reaction: $ref: '#/components/schemas/AgentReaction' default: speaks created_at: anyOf: - type: string - type: 'null' title: Created At updated_at: anyOf: - type: string - type: 'null' title: Updated At type: object required: - id - name - tool_type - timeout - retry_count title: ToolResponse description: A custom HTTP tool (public-safe response). ErrorResponse: properties: error: type: string title: Error code: type: string title: Code details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details type: object required: - error - code title: ErrorResponse description: Standard error response. example: code: NOT_FOUND details: contact_id: '123' error: Contact not found HttpConfigInput: properties: url: type: string title: Url description: Endpoint URL method: $ref: '#/components/schemas/HttpMethod' description: HTTP method default: POST headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Headers description: HTTP headers auth_type: anyOf: - $ref: '#/components/schemas/AuthType' - type: 'null' description: 'Auth type: none, basic, bearer, api_key' auth_config: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Auth Config description: Auth configuration timeout_ms: type: integer title: Timeout Ms description: Request timeout in milliseconds default: 30000 type: object required: - url title: HttpConfigInput description: HTTP configuration for a tool. DynamicParameterInput: properties: name: type: string title: Name description: Parameter name description: type: string title: Description description: Description for the LLM to understand when/how to use this parameter default: '' param_type: $ref: '#/components/schemas/ParameterType' description: 'Type: string, number, integer, boolean' default: string location: $ref: '#/components/schemas/ParameterLocation' description: 'Where to send: body, query, path, header' default: body required: type: boolean title: Required description: Whether parameter is required default: false source: type: string enum: - ai - system title: Source description: >- Who provides the value: 'ai' (visible to AI) or 'system' (injected from context, hidden from AI) default: ai system_variable: anyOf: - $ref: '#/components/schemas/SystemVariable' - type: 'null' description: >- Which system variable to inject when source is 'system' (e.g. call_id, contact_id) type: object required: - name title: DynamicParameterInput description: >- A tool parameter — either filled by the AI or injected by the system. When source is "ai" (default): the AI sees this parameter and provides the value. When source is "system": the value is injected from execution context (hidden from AI). StaticParameterInput: properties: name: type: string title: Name description: Parameter name value: type: string title: Value description: Static value (supports variable substitution like {workspace_id}) location: $ref: '#/components/schemas/ParameterLocation' description: 'Where to send: body, query, path, header' default: body type: object required: - name - value title: StaticParameterInput description: A fixed parameter always sent with requests. AgentReaction: type: string enum: - speaks - silent - speaks-once title: AgentReaction description: |- How the voice agent reacts when a tool call fires. Ultravox-specific. Ignored by chat tool-calling. - SPEAKS: agent speaks naturally around the tool call (Ultravox default) - SILENT: agent stays silent until the tool returns - SPEAKS_ONCE: agent speaks at most one filler line during the tool call HttpMethod: type: string enum: - GET - POST - PUT - PATCH - DELETE title: HttpMethod description: HTTP methods for tool requests. AuthType: type: string enum: - none - basic - bearer - api_key title: AuthType description: Authentication types for HTTP tools. ParameterType: type: string enum: - string - number - integer - boolean - object - array title: ParameterType description: Data types for tool parameters. ParameterLocation: type: string enum: - body - query - path - header title: ParameterLocation description: Where to send a parameter in an HTTP request. SystemVariable: type: string enum: - call_id - workspace_id - contact_id - conversation_id - persona_id - channel - campaign_id title: SystemVariable description: >- System variables that can be injected into tool parameters at runtime. These are resolved from ToolContext during execution and are hidden from the AI. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Workspace API key (e.g. `kej_live_...`) ````