Description
@openserp/n8n-nodes-openserp
n8n community node for OpenSERP. It supports web search, image search, single and batch URL extraction, OpenSERP Cloud account/pricing calls, Cloud engine capability/status calls, and use as a tool by n8n AI Agents.
Install
In n8n, install the community package:
@openserp/n8n-nodes-openserp
Install with npm:
npm install @openserp/n8n-nodes-openserp
Credentials
Create an OpenSERP API credential.
OpenSERP Cloud:
API Key: osklive...
Base URL: leave empty, or use https://api.openserp.org/v1
API keys are available at https://openserp.org/dashboard/keys.
Self-hosted OpenSERP:
API Key: leave empty
Base URL: http://localhost:7000
For a server running on another machine, set Base URL to that server’s root URL, for example http://openserp-host:7000. Do not append /v1 to a self-hosted URL.
The credential test calls /v1/me when an API key is present and /health when no API key is present.
Use with n8n AI Agents
OpenSERP uses n8n’s native app-node tool wrapper. The normal OpenSERP node and the generated OpenSERP Tool are shipped in this same package; a second repository or npm package is not required.
1. Install or update to @openserp/[email protected] or later, then restart n8n.
2. Add an AI Agent and connect a chat model.
3. From the AI Agent’s Tool connector, add OpenSERP Tool.
4. Select the OpenSERP credential, resource, operation, and any limits you want to keep under workflow-owner control.
5. For fields the model should choose, select n8n’s Let the model define this parameter button.
Recommended AI-controlled fields:
- Query for web or image search.
- Region, Language, Date Range, File Extension, and Site when the user’s request should determine filters.
- URL for single-page extraction.
- Resource and Operation, which define the tool’s purpose.
- Limit, Engines, Mode, extraction depth, and timeout, which affect cost, latency, and result size.
- Credentials and base URL.
Recommended workflow-controlled fields:
For example, configure one OpenSERP Tool as Search / Mega, keep Limit: 10, Mode: Balanced, and Extract Top Results: false, then let the model fill Query, Region, and Language. A second tool can be configured as Extract / Get Content and let the model fill only URL.
n8n adds a generated tool description based on the selected resource and operation. You can switch it to a manual description when the agent needs stricter routing instructions, for example: Search the public web for current factual information. Return source URLs with the result.
On older self-hosted n8n releases that block community packages from being used as tools, set the following environment variable and restart n8n:
N8NCOMMUNITYPACKAGESALLOWTOOL_USAGE=true
The $fromAI() function and the model-fill button only work while the node is connected to an AI Agent as a tool. Keep fixed limits for untrusted prompts so the model cannot create unexpectedly large searches or extraction requests.
Operations
error instead of failing the whole batch.Search and image operations add openserp_meta to the first output item. This contains request telemetry such as status, request ID, credits, engine used, and response metadata.
Cloud paging and errors
The Cloud credential sends Authorization: Bearer with your API key (osklivexxx). For web paging, keep Limit at 10, add Start, and use the previous response’s openserpmeta.pagination.nextstart while has_more is true. Google, Bing, and Yandex accept multiples of 10; Baidu supports early pages, Ecosia any offset, and DuckDuckGo only the first page. Search / Mega / Balanced rejects Start above 0; use Single, Any, or Fast for later pages.
Date Range is a publication-date range (YYYYMMDD..YYYYMMDD), supported by Cloud web search on Google and Ecosia. Unsupported paging/date filters return 400 invalid_request without charge. Change the parameters before retrying.
Engines / Get Status returns operational status and latency. Any starts engines in your order, overlapping slow attempts; Fast prioritizes recent health and latency. Use openserpmeta.engineused for the winner; enginestried and enginesskipped may be absent.
When Continue On Fail is enabled, failed items include status, code, requestid, and retryafter when available. Honor the delay when scheduling retries; 503 engine_unavailable carries 60 seconds. The node does not retry automatically.
Good Workflow Fits
Examples
Web search:
Resource: Search
Operation: Single
Engine: Google
Query: openserp
Limit: 10
Multi-engine image search:
Resource: Image
Operation: Mega
Engines: Google, Bing, DuckDuckGo
Mode: Balanced
Query: openserp logo
Extract a URL:
Resource: Extract
Operation: Get Content
URL: https://openserp.org
Mode: Auto
Extract several URLs in one request:
Resource: Extract
Operation: Get Content (Many URLs)
URLs: https://openserp.org
https://openserp.org/docs
Mode: Auto
Read a geo-fenced page as a local visitor by setting the Region extract option to a two-letter country code such as DE. On OpenSERP Cloud this adds 1 credit per extracted URL.
Resources
Example workflow
Import examples/web-search.json into n8n, select an
OpenSERP API credential with your API key (osklivexxx), then run the workflow.
Cloud requests use Authorization: Bearer authentication. For a self-hosted
OpenSERP server, leave the key empty and set its base URL in the credential.
Development
The node uses n8n HTTP helpers and has no runtime dependencies. Keep node and
credential names, parameter values, and output items compatible with existing workflows.
npm install
npm run lint
npm run typecheck
npm run build
npm test
npm run scan:local
npm pack --dry-run
Run the example in a local n8n instance before releasing. Publish through the
GitHub Actions workflow with npm provenance. After publishing, scan the exact
release:
npm run scan:published -- @openserp/n8n-nodes-openserp@VERSION
