n8n Quickstart
Status: Active
Version: v1.1.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
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 + IF)
Poll job status until terminal state (COMPLETED or FAILED).
Sub-node 3a: Wait
| Setting | Value |
|---|---|
| Node type | Wait |
| Duration | 5 seconds |
Sub-node 3b: 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 3c: IF (loop control)
| Setting | Value |
|---|---|
| Node type | IF |
| Condition | {{ $json.status }} is not equal to COMPLETED AND is not equal to FAILED |
| True branch | → back to Wait (Sub-node 3a) |
| False branch | → Fetch Results (Node 4) |
Set a maximum iterations limit (e.g., 40) on the loop to prevent runaway polling.
Node 4: Fetch Results
Retrieve screening results after job completion.
| Setting | Value |
|---|---|
| Node type | HTTP Request |
| Method | GET |
| URL | {{ $env.RGL8R_BASE_URL }}/api/sima/results?limit=50 |
| Headers | Authorization: Bearer {{ $node["Token Exchange"].json.access_token }} |
| Response | JSON |
Results include SIMA screening outcomes: AT_RISK, NEEDS_REVIEW, CLEARED per SKU.
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 (P12-B): When available, replace polling with webhook-triggered n8n workflows
- 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