n8n-nodes-screpy

The official Screpy community node for n8n.

Use Screpy in n8n workflows to manage SEO projects, start and inspect crawls, retrieve technical SEO data, compare projects and crawls, and monitor Core Web Vitals and uptime. The node covers every operation in the Screpy REST API V1 and can also be used as an AI Agent tool.

Features

• Complete Screpy REST API V1 coverage
• Native cursor pagination with Return All, Limit, and Starting Cursor controls
• Structured page, link, and image filters
• Read-only and mutating project operations
• Project and crawl comparisons
• AI Agent tool support through n8n's usableAsTool capability
• No runtime dependencies
• Credential validation against the authenticated Screpy account

Requirements

• n8n with community node support
• Node.js 22.22.0 or later for local development
• A Screpy account with REST API access
• A Screpy API key

Installation

n8n Community Nodes

1. Open Settings > Community Nodes in n8n.
2. Select Install.
3. Enter n8n-nodes-screpy.
4. Confirm the installation.

Self-hosted n8n

Install the package in the n8n custom nodes directory:

npm install n8n-nodes-screpy

Restart n8n after installation. See the n8n community node installation documentation for deployment-specific instructions.

Credentials

1. Sign in to Screpy.
2. Open Settings > Connected Apps.
3. Create a REST API key.
4. Choose Read-only for read operations or Read and write for all operations.
5. Copy the key when Screpy displays it. The key is shown only once.
6. In n8n, create a Screpy API credential and paste the key.

The credential test calls GET /account. Screpy API keys are different from Screpy MCP OAuth credentials. See the Screpy API authentication guide.

Operations

Resource	Operation	Screpy API operation
Account	Get	GET /account
Account	Get Usage	GET /account/usage
Comparison	Compare Crawls	POST /comparisons/crawls
Comparison	Compare Projects	POST /comparisons/projects
Crawl	Get Many	GET /projects/{project_uid}/crawls
Crawl	Get Status	GET /projects/{project_uid}/crawls/{crawl_uid}
Crawl	Get Summary	GET /projects/{project_uid}/crawls/{crawl_uid}/summary
Crawl	Start	POST /projects/{project_uid}/crawls
Crawl Data	Get Image Sources	GET /projects/{project_uid}/crawls/{crawl_uid}/images/sources
Crawl Data	Get Images	GET /projects/{project_uid}/crawls/{crawl_uid}/images
Crawl Data	Get Link Sources	GET /projects/{project_uid}/crawls/{crawl_uid}/links/sources
Crawl Data	Get Links	GET /projects/{project_uid}/crawls/{crawl_uid}/links
Crawl Data	Get On-Page Overview	GET /projects/{project_uid}/crawls/{crawl_uid}/on-page-overview
Crawl Data	Get Page	GET /projects/{project_uid}/crawls/{crawl_uid}/pages/detail
Crawl Data	Get Pages	GET /projects/{project_uid}/crawls/{crawl_uid}/pages
Crawl Data	Get Quick Wins	GET /projects/{project_uid}/crawls/{crawl_uid}/quick-wins
Health	Get Core Web Vitals	GET /projects/{project_uid}/core-web-vitals
Health	Get Uptime	GET /projects/{project_uid}/uptime
Project	Create	POST /projects
Project	Delete	DELETE /projects/{project_uid}
Project	Get	GET /projects/{project_uid}
Project	Get Many	GET /projects
Project	Update	PATCH /projects/{project_uid}

Pagination

List operations use Screpy's opaque cursor pagination.

• Enable Return All to request every available page.
• Disable Return All and set Limit to return at most 1–100 items.
• Set Starting Cursor to continue from a cursor saved by an earlier API response.

Never construct or modify a Screpy cursor. The node passes meta.next_cursor back to the API exactly as received.

Crawl Data Filters

The Get Pages, Get Links, and Get Images operations support up to 20 structured filters. Each filter has a field, operator, and value.

Available operators:

• Equals
• Not Equal
• Greater Than
• Greater Than or Equal
• Less Than
• Less Than or Equal
• In
• Contains
• Is Null

Use numeric comparison operators only with numeric fields and Contains only with string fields. For In, enter comma-separated values or a JSON array with 1–100 items. For Is Null, leave the value empty to check for null, or enter false to check for non-null values.

Quick Wins

The node exposes every Quick Wins category and only shows the date ranges supported by the selected category. If required project data is not connected, Screpy may return an empty data set with warnings. The node preserves those warnings as an output item so workflows can handle the unavailable state explicitly.

AI Agent Tools

The Screpy node is marked with usableAsTool: true. In n8n versions that support app nodes as tools, connect it to an AI Agent and select the required resource and operation. Credentials and Screpy access rules still apply to every tool call.

Error Handling

The node uses n8n's standard API error handling. Use HTTP status codes and Screpy's optional error code for workflow decisions:

• 401: invalid, expired, or revoked API key
• 403: missing scope, plan access, or feature access
• 404: inaccessible project or crawl
• 409: operation conflicts with current state
• 422: invalid input, cursor, or filter
• 429: rate limit exceeded
• 503: temporary Screpy service failure

Mutating operations require a key with both api:read and api:write scopes.

Development

npm install
npm run lint
npm run build

Run a local n8n development instance with hot reload:

npm run dev

The project uses the official @n8n/node-cli toolchain. A global n8n installation is not required for development.

Publishing

Semantic-version tags such as 0.1.0 trigger the GitHub Actions publish workflow. The workflow publishes through n8n-node release with npm provenance. Configure npm Trusted Publishing for the screpylabs/n8n-nodes-screpy repository before the first release.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for responsible disclosure instructions.

License

MIT © Screpy