> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools SDK Reference

> SDK reference for the Tools API, available in Node.js and Python.

## Tools

### List Tools

Lists all workspace tools. By default, returns all tools in a single response. Set `limit` to enable cursor-based pagination with `starting_after` and `ending_before`.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.tools.list(limit=300)

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.tools.list({
      limit: 300,
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[float],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Literal["list"],
        "data": Union[DataFunctionTool, DataJSONSchemaTool, DataHTTPTool, DataMCPTool, DataCodeExecutionTool],
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: string;
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create a Tool

Creates a new tool in the workspace.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import orq_ai_sdk
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.tools.create(request=orq_ai_sdk.RequestBodyJSONSchemaTool(
          path="Default",
          key="<key>",
          description="runway border pro mortally recount accredit promptly",
          status="live",
          type="json_schema",
          json_schema=orq_ai_sdk.RequestBodyJSONSchema(
              name="<value>",
              description="lovable past madly uh-huh by",
              schema_=orq_ai_sdk.RequestBodySchema(
                  type="<value>",
                  properties={
                      "key": "<value>",
                  },
                  required=[],
              ),
          ),
      ))

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.tools.create({
      path: "Default",
      key: "<key>",
      description: "runway border pro mortally recount accredit promptly",
      status: "live",
      type: "json_schema",
      jsonSchema: {
        name: "<value>",
        description: "lovable past madly uh-huh by",
        schema: {
          type: "<value>",
          properties: {
            "key": "<value>",
          },
          required: [],
        },
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "path": str,  # required
        "key": str,  # required
        "display_name": Optional[str],
        "description": str,  # required
        "status": Optional[Literal["live", "draft", "pending", "published"]],
        "type": Literal["function"],  # required
        "function": {  # required
            "name": str,  # required
            "description": Optional[str],
            "strict": Optional[bool],
            "parameters": {  # optional
                "type": Literal["object"],  # required
                "properties": Dict[str, Any],  # required
                "required": List[str],  # required
                "__pydantic_extra__": Dict[str, Any],
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      path: string;  // required
      key: string;  // required
      display_name?: string | undefined;
      description: string;  // required
      status?: "live" | "draft" | "pending" | "published" | undefined;
      type: "function";  // required
      function: {  // required
        name: string;  // required
        description?: string | undefined;
        strict?: boolean | undefined;
        parameters?: {
          type: "object";  // required
          properties: Record<string, unknown>;  // required
          required: string[];  // required
          __pydantic_extra__?: Record<string, unknown>;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": Optional[str],
        "path": str,
        "key": str,
        "display_name": Optional[str],
        "description": str,
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "project_id": str,
        "workspace_id": str,
        "created": str,
        "updated": str,
        "status": Optional[Literal["live", "draft", "pending", "published"]],
        "type": Literal["function"],
        "function": {
            "name": str,
            "description": Optional[str],
            "strict": Optional[bool],
            "parameters": {  # optional
                "type": Literal["object"],
                "properties": Dict[str, Any],
                "required": List[str],
                "__pydantic_extra__": Dict[str, Any],
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id?: string | undefined;
      path: string;
      key: string;
      display_name?: string | undefined;
      description: string;
      created_by_id?: string | null | undefined;
      updated_by_id?: string | null | undefined;
      project_id: string;
      workspace_id: string;
      created: string;
      updated: string;
      status?: "live" | "draft" | "pending" | "published" | undefined;
      type: "function";
      function: {
        name: string;
        description?: string | undefined;
        strict?: boolean | undefined;
        parameters?: {
          type: "object";
          properties: Record<string, unknown>;
          required: string[];
          __pydantic_extra__?: Record<string, unknown>;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Update a Tool

Updates a tool in the workspace.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import orq_ai_sdk
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.tools.update(tool_id="<id>", request_body=orq_ai_sdk.UpdateFunctionTool(
          path="Default",
          status="live",
          type="function",
      ))

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.tools.update({
      toolId: "<id>",
      requestBody: {
        path: "Default",
        status: "live",
        type: "function",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "tool_id": str,  # required
        "request_body": Union[UpdateFunctionTool, UpdateJSONSchemaTool, UpdateHTTPTool, UpdateMCPTool, UpdateCodeExecutionTool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      toolId: string;  // required
      requestBody?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": Optional[str],
        "path": str,
        "key": str,
        "display_name": Optional[str],
        "description": str,
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "project_id": str,
        "workspace_id": str,
        "created": str,
        "updated": str,
        "status": Optional[Literal["live", "draft", "pending", "published"]],
        "type": Literal["function"],
        "function": {
            "name": str,
            "description": Optional[str],
            "strict": Optional[bool],
            "parameters": {  # optional
                "type": Literal["object"],
                "properties": Dict[str, Any],
                "required": List[str],
                "__pydantic_extra__": Dict[str, Any],
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id?: string | undefined;
      path: string;
      key: string;
      display_name?: string | undefined;
      description: string;
      created_by_id?: string | null | undefined;
      updated_by_id?: string | null | undefined;
      project_id: string;
      workspace_id: string;
      created: string;
      updated: string;
      status?: "live" | "draft" | "pending" | "published" | undefined;
      type: "function";
      function: {
        name: string;
        description?: string | undefined;
        strict?: boolean | undefined;
        parameters?: {
          type: "object";
          properties: Record<string, unknown>;
          required: string[];
          __pydantic_extra__?: Record<string, unknown>;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a Tool

Deletes a tool by key.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      orq.tools.delete(tool_id="<id>")

      # Use the SDK ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    await orq.tools.delete({
      toolId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "tool_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      toolId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Tool

Retrieves a tool by id.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.tools.retrieve(tool_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.tools.retrieve({
      toolId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "tool_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      toolId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": Optional[str],
        "path": str,
        "key": str,
        "display_name": Optional[str],
        "description": str,
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "project_id": str,
        "workspace_id": str,
        "created": str,
        "updated": str,
        "status": Optional[Literal["live", "draft", "pending", "published"]],
        "type": Literal["function"],
        "function": {
            "name": str,
            "description": Optional[str],
            "strict": Optional[bool],
            "parameters": {  # optional
                "type": Literal["object"],
                "properties": Dict[str, Any],
                "required": List[str],
                "__pydantic_extra__": Dict[str, Any],
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id?: string | undefined;
      path: string;
      key: string;
      display_name?: string | undefined;
      description: string;
      created_by_id?: string | null | undefined;
      updated_by_id?: string | null | undefined;
      project_id: string;
      workspace_id: string;
      created: string;
      updated: string;
      status?: "live" | "draft" | "pending" | "published" | undefined;
      type: "function";
      function: {
        name: string;
        description?: string | undefined;
        strict?: boolean | undefined;
        parameters?: {
          type: "object";
          properties: Record<string, unknown>;
          required: string[];
          __pydantic_extra__?: Record<string, unknown>;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Tools Versions

Returns version history for a specific tool

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.tools.list_versions(tool_id="<id>", limit=10)

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.tools.listVersions({
      toolId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "tool_id": str,  # required
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      toolId: string;  // required
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Literal["list"],
        "data": {
            "id": str,
            "created_at": str,
            "updated_at": str,
            "created_by_id": Optional[str],
            "updated_by_id": Optional[str],
            "version": str,
            "description": Optional[str],
            "checksum": str,
            "entity_type": str,
            "entity_id": str,
            "data": Dict[str, Any],
            "workspace_id": str,
        },
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        createdAt: string;
        updatedAt: string;
        createdById?: string;
        updatedById?: string;
        version: string;
        description?: string;
        checksum: string;
        entityType: string;
        entityId: string;
        data: Record<string, any>;
        workspaceId: string;
      };
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Tools Versions

Returns a specific version of a tool

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.tools.get_version(tool_id="<id>", version_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.tools.getVersion({
      toolId: "<id>",
      versionId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "tool_id": str,  # required
        "version_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      toolId: string;  // required
      versionId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "created_at": str,
        "updated_at": str,
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "version": str,
        "description": Optional[str],
        "checksum": str,
        "entity_type": str,
        "entity_id": str,
        "data": Dict[str, Any],
        "workspace_id": str,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      createdAt: string;
      updatedAt: string;
      createdById?: string;
      updatedById?: string;
      version: string;
      description?: string;
      checksum: string;
      entityType: string;
      entityId: string;
      data: Record<string, any>;
      workspaceId: string;
    }
    ```
  </CodeGroup>
</Expandable>