API Reference

The NodeLoom REST API lets you manage workflows, executions, credentials, teams, and more programmatically. All endpoints follow consistent conventions for authentication, error handling, and pagination.

Base URL

All API requests are made to the following base URL:

text

https://your-nodeloom-instance.com

Replace this with your actual NodeLoom instance URL. For self-hosted deployments, this is the URL where your backend service is running.

Authentication

NodeLoom uses httpOnly cookie-based sessions for browser clients (handled automatically) and SDK tokens for programmatic access. SDK tokens can be generated from Settings → Observability SDK.

SDK tokens authenticate against all API endpoints (workflows, executions, credentials, guardrails, etc.), not just telemetry. Each token has a configurable RBAC role (Admin, Builder, Operator, or Viewer) that determines its permissions.

Example: list workflows with an SDK token

curl -H "Authorization: Bearer sdk_..." \
  https://your-instance.nodeloom.io/api/workflows?teamId=YOUR_TEAM_ID

SDK tokens

Create tokens with a specific role in Settings → Observability SDK. The effective permission is the lesser of the token's role and the team owner's role, preventing privilege escalation. See the SDK documentation for details.

Content Type

All requests that include a body must set the following header:

text

Content-Type: application/json

All responses are returned as JSON unless otherwise specified.

Rate Limiting

API requests are rate-limited based on your subscription tier. Rate limit headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed per window
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets

Tier	Requests / minute
Free	60
Team	300
Business	1,000
Enterprise	5,000

429 Too Many Requests

When you exceed the rate limit, the API returns a 429 status code. Back off and retry after the X-RateLimit-Reset time.

Error Response Format

All error responses follow a consistent JSON structure:

Error response

{
  "status": 400,
  "error": "Bad Request",
  "message": "Workflow name is required",
  "timestamp": "2026-02-17T10:30:00.000Z",
  "path": "/api/workflows"
}

HTTP Status	Meaning
`400`	Bad Request: invalid input or missing required fields
`401`	Unauthorized: missing or expired authentication
`403`	Forbidden: insufficient permissions for this action
`404`	Not Found: resource does not exist
`409`	Conflict: resource already exists or state conflict
`429`	Too Many Requests: rate limit exceeded
`500`	Internal Server Error: unexpected server failure

API Sections

The API is organized into the following sections:

Workflows

Create, update, delete, and execute workflows

Executions

List, inspect, cancel, and export execution logs

Credentials

Manage and test third-party credentials

Agent Chat

Chat sessions and streaming messages with AI agents

Widgets

Dashboard widget management and public chat API

Monitoring

Token usage, anomaly detection, and scheduled reports

Guardrails

Run safety checks on arbitrary text from external agents

Teams

Team management, members, and role assignments

Audit

Audit logs, integrity verification, and SIEM export

Quick Start