NagentArtefacts
Dev & Technology
Enterprise and White Glove
Company
Needle connects to a Nagent workspace with an API key. Once it is connected, agents can call 16 Needle actions, such as "Add files to a collection", "Add Files to Local Connector" and "Create Collection". Nothing is enabled on connect: each action is allowed one at a time, and an action with side effects runs or waits for a person according to the agent's level.
Every operation an agent can call against Needle, with input parameters and output schema.
NEEDLE_ADD_FILES_TO_COLLECTIONTool 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
List of files to add to the collection. Each file must have a name and URL.
The unique identifier of the collection to add files to
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_ADD_FILES_TO_LOCAL_CONNECTORTool 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
List of files to add to the local connector
The unique identifier of the local connector to add files to
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_CREATE_COLLECTIONTool to create a new collection. Use after confirming the collection name.
Input parameters
Name of the collection. Must be unique within your account.
Optional arbitrary JSON metadata associated with the collection.
Optional human-readable description of the collection.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_CREATE_LOCAL_CONNECTORTool 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
Operating system of the device (e.g., macOS, Windows, Linux)
CPU model/architecture of the device
Name for the local connector. Should be descriptive of the device or purpose.
List of folders to monitor for file indexing
Name of the device running the connector
Model identifier of the device
Serial number or unique identifier for the device
List of collection IDs to associate with this local connector. Files from the monitored folders will be indexed into these collections.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_DELETE_FILES_FROM_COLLECTIONTool to delete files from a specific collection by providing file IDs. Use after confirming valid file IDs to remove from the collection.
Input parameters
List of file IDs to delete from the collection
The unique identifier of the collection from which to delete files
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_DELETE_FILES_FROM_LOCAL_CONNECTORTool 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
Method to identify files for deletion: 'name' to delete by filename, 'file_ids' to delete by file IDs
Name of the file to delete. Required when 'by' is 'name'
List of file IDs to delete. Required when 'by' is 'file_ids'
The unique identifier of the connector from which to delete files
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_COLLECTIONTool 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
The unique identifier of the collection to retrieve.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_COLLECTION_STATSTool 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
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 from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_FILE_DOWNLOAD_URLTool 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
The unique identifier of the file to download
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_FILE_UPLOAD_URLTool 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
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 from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_GET_LOCAL_CONNECTORTool 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
The unique identifier of the local connector.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_LIST_COLLECTION_FILESTool 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
Number of files to return per page, must be >=1
Number of items to skip for pagination, must be >=0
Unique identifier of the collection Multiple collections can share similar names; verify the correct collection_id before operating on returned files.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_LIST_COLLECTIONSTool 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
Maximum number of collections to return (if supported by API)
Number of collections to skip before collecting results (if supported by API)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_LIST_CONNECTORSTool to list connectors. Use to retrieve all configured connectors in your account.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_LIST_LOCAL_CONNECTORSTool to list local connectors. Use to retrieve all local connectors configured in your Needle account.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
NEEDLE_SEARCH_COLLECTIONTool 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
The natural-language search query to find relevant content in the collection.
Maximum number of search results to return. Default is 10 (maximum).
Offset for pagination to skip a number of results.
Optional pass-through object for additional retrieval parameters supported by the API (e.g., filters, future knobs).
Maximum similarity distance threshold for results, between 0 and 1. Lower values mean stricter relevance. Example: '0.65'.
The unique identifier of the collection to search in.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
Agents can call 16 Needle actions on Nagent, including "Add files to a collection", "Add Files to Local Connector" and "Create Collection". Add files to a collection: Add files to a collection by providing file URLs. Each action is listed on this page with its input parameters and its output.
Needle connects with an API key, under your workspace's own connection. Nothing is enabled on connect: each action is allowed one at a time and can be scoped to the agents that need it.
Add files to a collection takes 2 required inputs: files and collection_id. It returns data, error and successful.