n8n Quickstart
Status: Active
Version: v1.2.0
Last updated: 2026-02-25
Companion docs:
- Agent Integration Kit — canonical 4-step flow with curl examples
- Public API Contract — error codes, job lifecycle, quotas
Prerequisites
- n8n instance (self-hosted or cloud, v1.20+)
- RGL8R integration key (create via
POST /api/integration-keysor Admin UI) - API base URL (e.g.,
https://api.rgl8r.com)
Store credentials in n8n’s Credential Manager — never hardcode keys in workflow nodes.
4-Node Workflow: SIMA Screening
Importable template: Download
n8n-sima-screening.jsonand import it directly into your n8n instance via Settings → Import from File.
This workflow implements the canonical flow: authenticate → enqueue → poll → fetch results.
Node 1: Token Exchange
Exchange your integration key for a short-lived bearer token.
| Setting | Value |
|---|---|
| Node type | HTTP Request |
| Method | POST |
| URL | {{ $env.RGL8R_BASE_URL }}/api/auth/token/integration |
| Headers | x-api-key: {{ $credentials.rgl8rApiKey }} |
| Response | JSON |
Extract from response:
{{ $json.access_token }}— bearer token for subsequent requests{{ $json.expires_in }}— token lifetime in seconds (default 3600)
Node 2: Enqueue Screening
Start a SIMA batch screening job.
| Setting | Value |
|---|---|
| Node type | HTTP Request |
| Method | POST |
| URL | {{ $env.RGL8R_BASE_URL }}/api/sima/batch |
| Headers | Authorization: Bearer {{ $node["Token Exchange"].json.access_token }} |
| Content-Type | application/json |
| Body | {"skus": null, "runPolicy": "always", "screeningAuthority": "US"} |
Extract from response:
{{ $json.jobId }}— job identifier for polling- Expected status code:
202
Node 3: Poll Loop (Wait + Guard + Check + Branch)
Poll job status until terminal state (COMPLETED or FAILED), with a built-in iteration guard.
Sub-node 3a: Wait
| Setting | Value |
|---|---|
| Node type | Wait |
| Duration | 10 seconds |
Sub-node 3b: Poll Guard (Code)
Uses n8n’s built-in $runIndex to count how many times this node has executed. Throws after 40 iterations (~7 minutes at 10s intervals) to prevent runaway polling if a job stalls. The counter is maintained by the n8n runtime and cannot be reset by upstream node outputs.
Sub-node 3c: Check Job Status
| Setting | Value |
|---|---|
| Node type | HTTP Request |
| Method | GET |
| URL | {{ $env.RGL8R_BASE_URL }}/api/jobs/{{ $node["Enqueue Screening"].json.jobId }} |
| Headers | Authorization: Bearer {{ $node["Token Exchange"].json.access_token }} |
Sub-node 3d: Completed? (IF)
| Setting | Value |
|---|---|
| Condition | {{ $json.status }} equals COMPLETED |
| True branch | → Job Results (Node 4) |
| False branch | → Failed? (IF) |
Sub-node 3e: Failed? (IF)
| Setting | Value |
|---|---|
| Condition | {{ $json.status }} equals FAILED |
| True branch | → Job Failed (error output) |
| False branch | → back to Wait (Sub-node 3a) |
Node 4: Job Results
Extract the job-scoped screening summary from the completed job response. This uses the job’s own outcomes and reconciliation payload — not the tenant-wide /api/sima/results endpoint — so results are always scoped to the run that just completed.
Output includes:
outcomes.atRisk,outcomes.needsReview,outcomes.cleared— aggregate countsreconciliation.skusFound,reconciliation.skusScreened— coverage metrics
To fetch per-SKU detail after the summary, add a follow-up HTTP Request node calling GET /api/sima/results.
SHIP Upload Variant
For freight audit uploads, replace Node 2 with a multipart file upload:
| Setting | Value |
|---|---|
| Node type | HTTP Request |
| Method | POST |
| URL | {{ $env.RGL8R_BASE_URL }}/api/ship/upload |
| Headers | Authorization: Bearer {{ $node["Token Exchange"].json.access_token }} |
| Content-Type | multipart/form-data |
| Body | Binary file field named file |
The response returns { jobId, status } — use the same poll loop (Node 3) and replace Node 4 with:
GET /api/ship/findings— list findings with variance amountsGET /api/ship/summary— KPI summary (total variance, finding counts)
Troubleshooting
| Symptom | Likely Cause | Action |
|---|---|---|
401 INVALID_API_KEY on Node 1 | Bad or revoked integration key | Rotate key via POST /api/integration-keys/:id/rotate or Admin UI |
401 INVALID_TOKEN on Nodes 2-4 | Bearer token expired | Re-run Node 1; check expires_in and reduce poll duration |
403 SCOPE_DENIED | Integration key missing required scope | Reissue key with required scopes |
400 INVALID_REQUEST on Node 2 | Malformed payload (e.g., bad screeningAuthority) | Validate request body against OpenAPI spec |
| Poll loop never terminates | Worker backlog or job failure | Check GET /api/jobs/:id response for error field; verify max-iterations guard |
429 RATE_LIMITED | Too many requests | Add exponential backoff: 5s → 10s → 20s between polls |
Next Steps
- SHIP upload workflow: Replace Node 2 with the SHIP variant above
- Catalog upload: Use
POST /api/catalog/upload(multipart) for TRADE catalog ingestion - Webhook triggers: Replace polling with webhook-triggered n8n workflows for instant job completion notifications
- Error notifications: Add an n8n Error Trigger node to alert on job failures via Slack/email
Plan ID: P12-A | Last updated: 2026-02-25