# Needle

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

- **Category:** artificial intelligence
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 16
- **Triggers:** 0
- **Slug:** `NEEDLE`
- **Version:** 20260316_00

## Tools

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `files` | array | Yes | List of files to add to the collection. Each file must have a name and URL. |
| `collection_id` | string | Yes | The unique identifier of the collection to add files to |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `files` | array | Yes | List of files to add to the local connector |
| `connector_id` | string | Yes | The unique identifier of the local connector to add files to |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Collection

**Slug:** `NEEDLE_CREATE_COLLECTION`

Tool to create a new collection. Use after confirming the collection name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name of the collection. Must be unique within your account. |
| `metadata` | object | No | Optional arbitrary JSON metadata associated with the collection. |
| `description` | string | No | Optional human-readable description of the collection. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `os` | string | Yes | Operating system of the device (e.g., macOS, Windows, Linux) |
| `cpu` | string | Yes | CPU model/architecture of the device |
| `name` | string | Yes | Name for the local connector. Should be descriptive of the device or purpose. |
| `folders` | array | Yes | List of folders to monitor for file indexing |
| `device_name` | string | Yes | Name of the device running the connector |
| `device_model` | string | Yes | Model identifier of the device |
| `serial_number` | string | Yes | Serial number or unique identifier for the device |
| `collection_ids` | array | Yes | List of collection IDs to associate with this local connector. Files from the monitored folders will be indexed into these collections. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_ids` | array | Yes | List of file IDs to delete from the collection |
| `collection_id` | string | Yes | The unique identifier of the collection from which to delete files |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `by` | string ("name" | "file_ids") | Yes | Method to identify files for deletion: 'name' to delete by filename, 'file_ids' to delete by file IDs |
| `name` | string | No | Name of the file to delete. Required when 'by' is 'name' |
| `file_ids` | array | No | List of file IDs to delete. Required when 'by' is 'file_ids' |
| `connector_id` | string | Yes | The unique identifier of the connector from which to delete files |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `collection_id` | string | Yes | The unique identifier of the collection to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get collection stats

**Slug:** `NEEDLE_GET_COLLECTION_STATS`

Tool to retrieve statistics for a specific collection by its ID. Use when you need document count, index size, and timestamps after confirming the collection exists. Zero document count is a valid response for empty collections, not an error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `collection_id` | string | Yes | The unique identifier of the collection. Verify the exact ID when collections have similar names to avoid retrieving stats for the wrong collection. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_id` | string | Yes | The unique identifier of the file to download |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content_type` | array | Yes | 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | string | Yes | The unique identifier of the local connector. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Collection Files

**Slug:** `NEEDLE_LIST_COLLECTION_FILES`

Tool to list all files within a specific collection by its ID. Returns file metadata (including file URLs) only — not document text content; fetch file URLs separately to access content. Use when you have a collection ID and need to retrieve its files. Supports pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Number of files to return per page, must be >=1 |
| `offset` | integer | No | Number of items to skip for pagination, must be >=0 |
| `collection_id` | string | Yes | Unique identifier of the collection Multiple collections can share similar names; verify the correct collection_id before operating on returned files. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of collections to return (if supported by API) |
| `offset` | integer | No | Number of collections to skip before collecting results (if supported by API) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Connectors

**Slug:** `NEEDLE_LIST_CONNECTORS`

Tool to list connectors. Use to retrieve all configured connectors in your account.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | The natural-language search query to find relevant content in the collection. |
| `top_k` | integer | No | Maximum number of search results to return. Default is 10 (maximum). |
| `offset` | integer | No | Offset for pagination to skip a number of results. |
| `options` | object | No | Optional pass-through object for additional retrieval parameters supported by the API (e.g., filters, future knobs). |
| `max_distance` | string | No | Maximum similarity distance threshold for results, between 0 and 1. Lower values mean stricter relevance. Example: '0.65'. |
| `collection_id` | string | Yes | The unique identifier of the collection to search in. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |