> ## Documentation Index > Fetch the complete documentation index at: https://docs.conduit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Custom Tool > Creates a custom code tool from Python or JavaScript source. Requires a token with write access. See List Custom Tool Runtimes for the code contract. ## OpenAPI ````yaml POST /v1/custom-tools openapi: 3.0.0 info: title: Conduit API version: 1.0.0 description: Public API for Conduit. servers: - url: https://api.conduit.ai description: Production security: [] tags: - name: meta description: Discovery and API metadata endpoints. - name: agents description: >- V2 chat agent configuration, including instructions, skills, triggers, and automation behavior. - name: contacts description: >- Contact profile and contact-scoped related resources such as tickets and calls. - name: workspaces description: Workspaces accessible to the current API token. - name: escalations description: >- Chat escalations that require operator review, including message, proposed response, and disposition context when available. - name: conversations description: >- Canonical message threads. Use these endpoints to list threads, inspect conversation state, read transcripts, and send replies. - name: tickets description: >- Operational queue items tied to conversations, including ticket-scoped transcripts and replies. - name: calls description: Phone call records, transcripts, summaries, and recordings when available. - name: reservations description: >- PMS reservations synced from the workspace's integrations (Hostaway, Guesty, Airbnb, etc.), including guest identity, payment status, and stay dates. - name: appointments description: >- Scheduled appointments (bookings) backed by the Conduit booking service. Exposes allocation context and the upstream booking-service `external_id`. - name: helpdesk_tickets description: >- Helpdesk tickets mirrored from external helpdesk integrations (Zendesk, Pylon, Plain), including requester identity and upstream metadata. - name: kb description: >- Knowledge base search and node management. Nodes represent knowledge base entries (files or directories), chunks are the indexed retrieval units used by search. - name: skills description: >- Workspace agent skills that can be attached to V2 chat agents. Sidebar/global-assistant skills are intentionally excluded. - name: custom_tools description: >- Custom code tools: user-authored Python/JavaScript functions executed in a sandbox when an agent calls them. Includes a runtimes endpoint describing the entrypoint signature, return shape, and available dependencies per language. paths: /v1/custom-tools: post: tags: - custom_tools summary: Create custom tool description: >- Creates a custom code tool. Requires a token with write access. See GET /v1/custom-tools/runtimes for the code contract. operationId: createCustomTool requestBody: required: true content: application/json: schema: type: object properties: workspace_id: type: string name: type: string minLength: 1 maxLength: 64 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ description: >- Unique tool name within the workspace. Lowercase kebab-case (e.g. `lookup-order-status`), at most 64 characters. This is how the agent references the tool. description: type: string maxLength: 1024 language: type: string enum: - python - javascript description: >- Runtime the tool's code is executed in. Determines the entrypoint signature and which dependencies are available (see GET /v1/custom-tools/runtimes). code: type: string minLength: 1 description: >- The tool's source code. Must define a single entrypoint named `main`. Python: `def main(**params):` — parameters arrive as keyword args. Return a dict containing a string `message` key, optionally a `rawData` key with structured data. JavaScript: `async function main(params) { ... }` — parameters arrive as a single object. Return an object containing a string `message` key, optionally a `rawData` key. Writes statically validate that the code defines `main` and includes a return statement; runtime execution validates the returned object. Standard library modules are always importable. A curated set of third-party packages installs automatically on first import. Query GET /v1/custom-tools/runtimes for the exact signature, return contract, and available dependencies per language. parameters: type: object additionalProperties: type: object properties: type: type: string description: >- JSON-schema-style parameter type, e.g. `string`, `number`, `boolean`, `object`, `array`. required: type: boolean description: Whether the agent must supply this parameter. description: type: string description: >- What this parameter is. Shown to the model to help it fill the value correctly. execution_message_description: type: string description: >- Optional per-parameter note surfaced while the tool is running. enum_values: type: array items: type: string description: Optional closed set of allowed string values. required: - type - required - description description: >- Parameters the tool accepts, keyed by parameter name. Each becomes a key in the `params` object/dict passed to `main`. execution_message_description: type: string description: >- Short status line shown to the user while the tool runs, e.g. `Looking up order status`. enable_globally: type: boolean description: >- When true, the tool is available to every agent in the workspace without per-agent enablement. required: - workspace_id - name - language - code description: >- Request body for creating a custom code tool. Requires a token with write access. example: workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o name: lookup-order-status description: Look up the fulfillment status of an order by id. language: python code: |- def main(**params): order_id = params["order_id"] return {"message": f"Order {order_id} is shipped"} parameters: order_id: type: string required: true description: The order id to look up. execution_message_description: Looking up order status enable_globally: false responses: '201': description: Custom tool created content: application/json: schema: type: object properties: data: type: object properties: id: type: string workspace_id: type: string name: type: string description: type: string language: type: string enum: - python - javascript description: >- Runtime the tool's code is executed in. Determines the entrypoint signature and which dependencies are available (see GET /v1/custom-tools/runtimes). code: type: string parameters: type: object additionalProperties: type: object properties: type: type: string description: >- JSON-schema-style parameter type, e.g. `string`, `number`, `boolean`, `object`, `array`. required: type: boolean description: Whether the agent must supply this parameter. description: type: string description: >- What this parameter is. Shown to the model to help it fill the value correctly. execution_message_description: type: string description: >- Optional per-parameter note surfaced while the tool is running. enum_values: type: array items: type: string description: Optional closed set of allowed string values. required: - type - required - description description: >- Parameters the tool accepts, keyed by parameter name. Each becomes a key in the `params` object/dict passed to `main`. execution_message_description: type: string nullable: true enable_globally: type: boolean validated: type: boolean version: type: number created_at: type: string required: - id - workspace_id - name - description - language - code - parameters - execution_message_description - enable_globally - validated - version - created_at required: - data description: Single custom code tool response. example: data: id: kg77c0dy0mgdpzmqz6tesry8w184002s workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o name: lookup-order-status description: Look up the fulfillment status of an order by id. language: python code: |- def main(**params): order_id = params["order_id"] # ... fetch status ... return { "message": f"Order {order_id} is shipped", "rawData": {"status": "shipped"}, } parameters: order_id: type: string required: true description: The order id to look up. execution_message_description: Looking up order status enable_globally: false validated: true version: 1 created_at: '2026-04-01T17:22:10.000Z' '400': description: Invalid request content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id '409': description: Conflict content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: type: string required: - error description: Standard error response. example: error: Invalid workspace id security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Token description: >- Conduit API token. Use `Authorization: Bearer `. Read/write endpoints require a token with write access. ````