> ## 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. # Run Custom Tool > Executes a custom code tool with the given parameters and returns its result. The code runs in the sandbox exactly as an agent would invoke it. A tool whose own code fails still returns 200 with success: false. Requires a token with write access. ## OpenAPI ````yaml POST /v1/custom-tools/{id}/run 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/{id}/run: post: tags: - custom_tools summary: Run custom tool description: >- Executes a custom code tool with the given parameters and returns its result. The code runs in the sandbox exactly as an agent would invoke it. A tool whose own code fails still returns 200 with `success: false`; a non-2xx only means the tool was not found or the arguments were rejected. Requires a token with write access. operationId: runCustomTool parameters: - schema: type: string description: Custom tool id. example: kg77c0dy0mgdpzmqz6tesry8w184002s required: true name: id in: path requestBody: required: false content: application/json: schema: type: object description: >- Request body for running a custom code tool. Requires a token with write access since execution can have side effects. properties: workspace_id: type: string description: >- Optional workspace override. If omitted, Conduit resolves the tool's workspace automatically. example: j57demo8f8x7c9v0n2q4r6t8y1u3i5o parameters: type: object additionalProperties: true description: >- Arguments passed to the tool's `main` entrypoint, keyed by parameter name. Every parameter the tool marks as `required` must be present. example: workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o parameters: order_id: ord_12345 responses: '200': description: Custom tool run result content: application/json: schema: type: object description: >- Result of executing a custom code tool. A non-2xx is only returned when the tool could not be found or the arguments were rejected; a tool whose code fails returns 200 with `success: false`. properties: data: type: object properties: success: type: boolean description: >- Whether the tool's code ran to completion and returned the expected shape. `false` means the code threw or returned an invalid result; see `error`. message: type: string nullable: true description: The `message` string the tool returned, if any. result: nullable: true description: >- The full structured object the tool returned (including `message` and any `rawData`), if the run succeeded. error: type: string nullable: true description: >- Failure reason when `success` is false, otherwise null. logs: type: string nullable: true description: Captured stdout/stderr from the run, if any. run_time_ms: type: number description: Wall-clock execution time in milliseconds. required: - success - message - result - error - logs - run_time_ms required: - data example: data: success: true message: Order ord_12345 is shipped result: message: Order ord_12345 is shipped rawData: status: shipped error: null logs: null run_time_ms: 842 '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 '404': description: Not found 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. ````