> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Needle

> Needle provides retrieval-augmented generation (RAG) tools that enable semantic search across your data, facilitating the development of AI agents and applications.

![Needle logo](https://mintcdn.com/composio-preview/9YPuzjEU4UlMnwGq/images/toolkits/needle.svg?fit=max\&auto=format\&n=9YPuzjEU4UlMnwGq\&q=85\&s=b271f795aa01a2287c53d40a387dbe8d)

* **Category:** artificial intelligence
* **Auth:** API\_KEY
* **Composio-managed OAuth available?** N/A
* **Tools:** 16
* **Triggers:** 0
* **Slug:** `NEEDLE`
* **Version:** 20261101\_00

## Tools

> [accordion] Add files to a collection
>
> **Slug:** `NEEDLE_ADD_FILES_TO_COLLECTION`
>
> Tool to add files to a collection by providing file URLs. Use when you need to add one or more files to an existing collection. URLs can be public or private (generated via the Files API).
>
> #### Input Parameters
>
> **files** `array` *required*
>
> List of files to add to the collection. Each file must have a name and URL.
>
> **collection\_id** `string` *required*
>
> The unique identifier of the collection to add files to
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Add Files to Local Connector
>
> **Slug:** `NEEDLE_ADD_FILES_TO_LOCAL_CONNECTOR`
>
> Tool to add files to a local connector by providing file metadata. Use when you need to add external files to a connector using their URLs.
>
> #### Input Parameters
>
> **files** `array` *required*
>
> List of files to add to the local connector
>
> **connector\_id** `string` *required*
>
> The unique identifier of the local connector to add files to
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Create Collection
>
> **Slug:** `NEEDLE_CREATE_COLLECTION`
>
> Tool to create a new collection. Use after confirming the collection name.
>
> #### Input Parameters
>
> **name** `string` *required*
>
> Name of the collection. Must be unique within your account.
>
> **metadata** `object`
>
> Optional arbitrary JSON metadata associated with the collection.
>
> **description** `string`
>
> Optional human-readable description of the collection.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Create Local Connector
>
> **Slug:** `NEEDLE_CREATE_LOCAL_CONNECTOR`
>
> Tool to create a local connector that monitors specified folders on a device. Use when setting up file indexing from a local machine into Needle collections.
>
> #### Input Parameters
>
> **os** `string` *required*
>
> Operating system of the device (e.g., macOS, Windows, Linux)
>
> **cpu** `string` *required*
>
> CPU model/architecture of the device
>
> **name** `string` *required*
>
> Name for the local connector. Should be descriptive of the device or purpose.
>
> **folders** `array` *required*
>
> List of folders to monitor for file indexing
>
> **device\_name** `string` *required*
>
> Name of the device running the connector
>
> **device\_model** `string` *required*
>
> Model identifier of the device
>
> **serial\_number** `string` *required*
>
> Serial number or unique identifier for the device
>
> **collection\_ids** `array` *required*
>
> List of collection IDs to associate with this local connector. Files from the monitored folders will be indexed into these collections.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Delete files from a collection
>
> **Slug:** `NEEDLE_DELETE_FILES_FROM_COLLECTION`
>
> Tool to delete files from a specific collection by providing file IDs. Use after confirming valid file IDs to remove from the collection.
>
> #### Input Parameters
>
> **file\_ids** `array` *required*
>
> List of file IDs to delete from the collection
>
> **collection\_id** `string` *required*
>
> The unique identifier of the collection from which to delete files
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Delete files from local connector
>
> **Slug:** `NEEDLE_DELETE_FILES_FROM_LOCAL_CONNECTOR`
>
> Tool to delete files from a local connector by filename or file IDs. Use when you need to remove files from a connector's local storage.
>
> #### Input Parameters
>
> **by** `string ("name" | "file_ids")` *required*
>
> Method to identify files for deletion: 'name' to delete by filename, 'file\_ids' to delete by file IDs
>
> **name** `string`
>
> Name of the file to delete. Required when 'by' is 'name'
>
> **file\_ids** `array`
>
> List of file IDs to delete. Required when 'by' is 'file\_ids'
>
> **connector\_id** `string` *required*
>
> The unique identifier of the connector from which to delete files
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Get Collection
>
> **Slug:** `NEEDLE_GET_COLLECTION`
>
> Tool to retrieve details for a specific collection by its ID. Use when you need to get collection metadata including name, creation date, and search query count.
>
> #### Input Parameters
>
> **collection\_id** `string` *required*
>
> The unique identifier of the collection to retrieve.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Get collection stats
>
> **Slug:** `NEEDLE_GET_COLLECTION_STATS`
>
> Retrieve statistics for a collection by ID, including user, chunk and character counts and file counts and bytes grouped by status.
>
> #### Input Parameters
>
> **collection\_id** `string` *required*
>
> The unique identifier of the collection. Verify the exact ID when collections have similar names to avoid retrieving stats for the wrong collection.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Get File Download URL
>
> **Slug:** `NEEDLE_GET_FILE_DOWNLOAD_URL`
>
> Tool to get a short-lived signed private download URL for a Needle file. Use when you need to retrieve file content but the public storage URL requires authentication. The returned URL should be used immediately as it expires quickly.
>
> #### Input Parameters
>
> **file\_id** `string` *required*
>
> The unique identifier of the file to download
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Get File Upload URL
>
> **Slug:** `NEEDLE_GET_FILE_UPLOAD_URL`
>
> Tool to get signed URLs for uploading local files to Needle. Use when you need to upload files to a collection. The upload URLs are valid for a short time, so upload files immediately after receiving the URLs. Multiple content types can be specified to generate multiple upload URLs in a single request.
>
> #### Input Parameters
>
> **content\_type** `array` *required*
>
> MIME types for files to upload (e.g., application/pdf, text/plain, image/jpeg). Multiple content types can be provided to generate multiple upload URLs at once.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Get local connector
>
> **Slug:** `NEEDLE_GET_LOCAL_CONNECTOR`
>
> Tool to retrieve details of a local connector by its ID. Use when you need information about a specific local connector's configuration, device details, and associated folders.
>
> #### Input Parameters
>
> **connector\_id** `string` *required*
>
> The unique identifier of the local connector.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Collection Files
>
> **Slug:** `NEEDLE_LIST_COLLECTION_FILES`
>
> List file metadata for a collection by ID, with pagination parameters. File URLs may be included; the returned total is the number of files in the current response, not necessarily the collection-wide count.
>
> #### Input Parameters
>
> **limit** `integer`
>
> Number of files to return per page, must be >=1
>
> **offset** `integer`
>
> Number of items to skip for pagination, must be >=0
>
> **collection\_id** `string` *required*
>
> Unique identifier of the collection Multiple collections can share similar names; verify the correct collection\_id before operating on returned files.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Collections
>
> **Slug:** `NEEDLE_LIST_COLLECTIONS`
>
> Tool to list collections. Use after authenticating with your API key to page through collections. Similar collection names can exist; always verify the correct `collection_id` from results before performing subsequent operations.
>
> #### Input Parameters
>
> **limit** `integer`
>
> Maximum number of collections to return (if supported by API)
>
> **offset** `integer`
>
> Number of collections to skip before collecting results (if supported by API)
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Connectors
>
> **Slug:** `NEEDLE_LIST_CONNECTORS`
>
> Tool to list connectors. Use to retrieve all configured connectors in your account.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Local Connectors
>
> **Slug:** `NEEDLE_LIST_LOCAL_CONNECTORS`
>
> Tool to list local connectors. Use to retrieve all local connectors configured in your Needle account.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Search Collection
>
> **Slug:** `NEEDLE_SEARCH_COLLECTION`
>
> Tool to perform semantic search within a specific Needle collection and return ranked results with source references. Use when you need to retrieve relevant content from a known collection using natural language queries.
>
> #### Input Parameters
>
> **text** `string` *required*
>
> The natural-language search query to find relevant content in the collection.
>
> **top\_k** `integer`
>
> Maximum number of search results to return. Default is 10 (maximum).
>
> **offset** `integer`
>
> Offset for pagination to skip a number of results.
>
> **options** `object`
>
> Optional pass-through object for additional retrieval parameters supported by the API (e.g., filters, future knobs).
>
> **max\_distance** `string`
>
> Maximum similarity distance threshold for results, between 0 and 1. Lower values mean stricter relevance. Example: '0.65'.
>
> **collection\_id** `string` *required*
>
> The unique identifier of the collection to search in.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not
