SDK API Reference

The SDK API has two parts: telemetry endpoints (authenticated with SDK bearer tokens) for receiving events from your agents, and management endpoints (authenticated with JWT cookies) for managing tokens and viewing agent data from the dashboard.

SDK tokens work everywhere

SDK tokens (Bearer sdk_...) now authenticate against all NodeLoom API endpoints, not just the telemetry endpoints below. Each token has a configurable RBAC role (Admin, Builder, Operator, Viewer). See the API Reference overview for details.

Telemetry Endpoints (SDK Token Auth)

These endpoints are used by the SDKs to send telemetry data. They authenticate using a bearer token in the Authorization header.

Authentication

Authorization: Bearer sdk_...

Ingest Telemetry

POST

/api/sdk/v1/telemetry

Submit a batch of telemetry events

Field	Type	Required	Description
`events`	array	Yes	Array of telemetry event objects (max 100 per batch)
`sdk_version`	string	No	SDK version string for diagnostics
`sdk_language`	string	No	SDK language identifier (e.g., "python", "typescript")

Request

{
  "events": [
    {
      "type": "trace_start",
      "trace_id": "abc-123",
      "agent_name": "customer-support-agent",
      "agent_version": "1.2.0",
      "environment": "production",
      "input": { "query": "How do I reset my password?" },
      "timestamp": "2026-03-06T10:00:00.000Z"
    },
    {
      "type": "span",
      "trace_id": "abc-123",
      "span_id": "span-1",
      "name": "openai-chat",
      "span_type": "llm",
      "input": { "prompt": "..." },
      "output": { "response": "..." },
      "token_usage": {
        "prompt_tokens": 150,
        "completion_tokens": 200,
        "total_tokens": 350,
        "model": "gpt-4o"
      },
      "timestamp": "2026-03-06T10:00:01.000Z",
      "end_timestamp": "2026-03-06T10:00:03.000Z"
    },
    {
      "type": "trace_end",
      "trace_id": "abc-123",
      "status": "success",
      "output": { "answer": "You can reset your password from..." },
      "timestamp": "2026-03-06T10:00:05.000Z"
    }
  ],
  "sdk_version": "0.1.0",
  "sdk_language": "python"
}

200 OK

{
  "accepted": 3,
  "rejected": 0,
  "errors": []
}

If some events in the batch fail validation, the response includes per-event errors with their index:

200 OK (partial rejection)

{
  "accepted": 2,
  "rejected": 1,
  "errors": [
    { "index": 1, "error": "span_type is required for span events" }
  ]
}

Health Check

GET

/api/sdk/v1/health

Check if the SDK API is available (no authentication required)

200 OK

{
  "status": "ok",
  "service": "nodeloom-sdk-api",
  "version": "1"
}

Event Types

Each event in the batch must have a type field. The following types are supported:

trace_start

Marks the beginning of a trace. Creates an execution in NodeLoom.

Field	Type	Required	Description
`type`	string	Yes	"trace_start"
`trace_id`	string	Yes	Unique trace identifier (max 64 chars)
`agent_name`	string	Yes	Name of your agent (max 255 chars)
`agent_version`	string	No	Version string for your agent
`environment`	string	No	"production" (default), "staging", or "development"
`input`	object	No	Input data for the trace
`metadata`	object	No	Arbitrary metadata
`timestamp`	string	No	ISO 8601 timestamp (defaults to server time)

span

Records an individual operation within a trace. Maps to a node execution (step) in NodeLoom.

Field	Type	Required	Description
`type`	string	Yes	"span"
`trace_id`	string	Yes	Trace this span belongs to
`span_id`	string	No	Unique span identifier (auto-generated if omitted)
`parent_span_id`	string	No	Parent span ID for nested spans
`name`	string	No	Human-readable name for this span
`span_type`	string	Yes	"llm", "tool", "retrieval", "agent", "chain", or "custom"
`status`	string	No	"success" or "error"
`input`	object	No	Input data for the span
`output`	object	No	Output data from the span
`error`	string	No	Error message if the span failed
`token_usage`	object	No	Token usage object (see below)
`timestamp`	string	No	ISO 8601 start timestamp
`end_timestamp`	string	No	ISO 8601 end timestamp

Token Usage Object

Field	Type	Description
`prompt_tokens`	integer	Number of input/prompt tokens
`completion_tokens`	integer	Number of output/completion tokens
`total_tokens`	integer	Total tokens (computed from prompt + completion if omitted)
`model`	string	Model name for cost attribution

trace_end

Marks the completion of a trace. Updates the execution status in NodeLoom and triggers monitoring hooks (anomaly detection, drift alerts, evaluations).

Field	Type	Required	Description
`type`	string	Yes	"trace_end"
`trace_id`	string	Yes	Trace to complete
`status`	string	No	"success" or "error"
`output`	object	No	Final output data
`error`	string	No	Error message if the trace failed
`timestamp`	string	No	ISO 8601 completion timestamp

event

A standalone event that does not create an execution. Useful for logging custom metrics or events outside of a trace.

Field	Type	Required	Description
`type`	string	Yes	"event"
`name`	string	No	Event name
`level`	string	No	Log level (info, warning, error)
`data`	object	No	Event data payload
`timestamp`	string	No	ISO 8601 timestamp

Guardrail Check

Run guardrail safety checks on arbitrary text without a workflow execution. Supports prompt injection detection, PII redaction, content filtering, custom rules, and semantic similarity.

POST

/api/guardrails/check

Run guardrail checks on text content

See the full request/response schema in the Guardrails API Reference.

Example

curl -X POST "https://your-instance.nodeloom.io/api/guardrails/check?teamId=TEAM_ID" \
  -H "Authorization: Bearer sdk_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Check this content", "detectPromptInjection": true, "applyCustomRules": true}'

Feedback

Submit and retrieve feedback for executions and traces. Feedback is used for evaluation, quality monitoring, and fine-tuning.

Submit Feedback

POST

/api/sdk/v1/feedback

Submit feedback for an execution or trace

Field	Type	Required	Description
`execution_id`	UUID	No	The execution to attach feedback to
`trace_id`	string	No	The trace to attach feedback to
`span_id`	string	No	Optional span within the trace
`rating`	integer	No	Rating from 1 to 5
`comment`	string	No	Free-text feedback comment
`tags`	string[]	No	Array of tags for categorizing feedback

Request

{
  "execution_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "abc-123",
  "rating": 5,
  "comment": "Great response, very accurate",
  "tags": ["accurate", "helpful"]
}

200 OK

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "execution_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "abc-123",
  "rating": 5,
  "created_at": "2026-03-24T10:00:00.000Z"
}

List Feedback

GET

/api/sdk/v1/feedback

List feedback with optional filters

Parameter	Type	Default	Description
`execution_id`	UUID	—	Filter by execution ID
`page`	integer	0	Page number (zero-indexed)
`size`	integer	20	Page size

200 OK

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "execution_id": "550e8400-e29b-41d4-a716-446655440000",
      "trace_id": "abc-123",
      "rating": 5,
      "comment": "Great response, very accurate",
      "tags": ["accurate", "helpful"],
      "created_at": "2026-03-24T10:00:00.000Z"
    }
  ],
  "page": 0,
  "size": 20,
  "total": 1
}

Sentiment Analysis

Analyze the sentiment of text using a configured LLM provider. Returns sentiment classification, score, confidence, and granular emotion breakdowns.

Analyze Sentiment

POST

/api/sdk/v1/sentiment

Analyze text sentiment

Field	Type	Required	Description
`text`	string	Yes	The text to analyze
`credential_id`	UUID	No	LLM credential to use (defaults to team default)

Request

{
  "text": "I absolutely love how fast the response was!",
  "credential_id": "550e8400-e29b-41d4-a716-446655440000"
}

200 OK

{
  "sentiment": "positive",
  "score": 0.92,
  "confidence": 0.97,
  "emotions": {
    "joy": 0.85,
    "sadness": 0.02,
    "anger": 0.01,
    "fear": 0.01,
    "surprise": 0.15,
    "disgust": 0.0
  },
  "summary": "The text expresses strong positive sentiment with high joy."
}

Cost Summary

Retrieve aggregated cost and token usage data for your team, with optional filtering by time range and workflow.

Get Cost Summary

GET

/api/sdk/v1/costs

Get cost summary for the team

Parameter	Type	Default	Description
`from`	ISO instant	—	Start of the time range
`to`	ISO instant	—	End of the time range
`workflow_id`	UUID	—	Filter by workflow ID

200 OK

{
  "totalCost": 12.45,
  "totalTokens": 1250000,
  "promptTokens": 750000,
  "completionTokens": 500000,
  "models": [
    { "model": "gpt-4o", "tokens": 800000 },
    { "model": "claude-sonnet-4-20250514", "tokens": 450000 }
  ],
  "from": "2026-03-01T00:00:00Z",
  "to": "2026-03-24T23:59:59Z"
}

Custom Metrics

Retrieve aggregated custom metrics that your agents have reported via telemetry events.

Get Aggregated Metrics

GET

/api/sdk/v1/metrics

Get aggregated custom metrics

Parameter	Type	Default	Description
`name`	string	—	Filter by metric name
`from`	ISO instant	—	Start of the time range
`to`	ISO instant	—	End of the time range

200 OK

{
  "name": "response_quality",
  "count": 1520,
  "avg": 0.87,
  "min": 0.12,
  "max": 1.0,
  "sum": 1322.4,
  "from": "2026-03-01T00:00:00Z",
  "to": "2026-03-24T23:59:59Z"
}

Alert Webhooks

Register webhook URLs to receive real-time alert notifications. When an alert fires, NodeLoom sends a POST request to each matching webhook.

Register Webhook

POST

/api/sdk/v1/alerts/webhooks

Field	Type	Required	Description
`url`	string	Yes	The webhook URL to receive alert payloads
`secret`	string	No	Shared secret for HMAC signature verification
`event_types`	string[]	No	Filter which event types trigger this webhook

Request

{
  "url": "https://example.com/webhooks/nodeloom-alerts",
  "secret": "whsec_abc123",
  "event_types": ["anomaly_detected", "drift_detected", "error_spike"]
}

200 OK

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "url": "https://example.com/webhooks/nodeloom-alerts",
  "event_types": ["anomaly_detected", "drift_detected", "error_spike"],
  "active": true,
  "created_at": "2026-03-24T10:00:00.000Z"
}

List Webhooks

GET

/api/sdk/v1/alerts/webhooks

List all registered alert webhooks

200 OK

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "url": "https://example.com/webhooks/nodeloom-alerts",
      "event_types": ["anomaly_detected", "drift_detected", "error_spike"],
      "active": true,
      "created_at": "2026-03-24T10:00:00.000Z"
    }
  ]
}

Delete Webhook

DELETE

/api/sdk/v1/alerts/webhooks/:id

Delete a registered webhook

Example

curl -X DELETE "https://your-instance.nodeloom.io/api/sdk/v1/alerts/webhooks/WEBHOOK_ID" \
  -H "Authorization: Bearer sdk_..."

Prompt Templates

Manage versioned prompt templates. Creating a prompt with an existing name automatically adds a new version.

Create / Add Version

POST

/api/sdk/v1/prompts

Create a prompt template or add a new version

Field	Type	Required	Description
`name`	string	Yes	Unique template name (creates new or adds version if exists)
`description`	string	No	Description of the prompt template
`content`	string	Yes	The prompt content with optional {{variable}} placeholders
`variables`	string[]	No	List of variable names used in the template
`model_hint`	string	No	Suggested model for this prompt

Request

{
  "name": "customer-greeting",
  "description": "Greet the customer by name",
  "content": "Hello {{customer_name}}, welcome to {{company}}! How can I help you today?",
  "variables": ["customer_name", "company"],
  "model_hint": "gpt-4o"
}

200 OK

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "customer-greeting",
  "description": "Greet the customer by name",
  "version": 2,
  "content": "Hello {{customer_name}}, welcome to {{company}}! How can I help you today?",
  "variables": ["customer_name", "company"],
  "model_hint": "gpt-4o",
  "action": "version_added",
  "created_at": "2026-03-20T10:00:00.000Z",
  "version_created_at": "2026-03-24T10:00:00.000Z"
}

Get Prompt

GET

/api/sdk/v1/prompts/:name

Get a prompt template by name (optionally a specific version)

Parameter	Type	Default	Description
`version`	integer	latest	Specific version number to retrieve

Example

curl "https://your-instance.nodeloom.io/api/sdk/v1/prompts/customer-greeting?version=1" \
  -H "Authorization: Bearer sdk_..."

List Prompts

GET

/api/sdk/v1/prompts

List all prompt templates

Example

curl "https://your-instance.nodeloom.io/api/sdk/v1/prompts" \
  -H "Authorization: Bearer sdk_..."

Agent Guardrails

Configure per-agent guardrail rules. When set, every execution for the agent is automatically checked against the guardrail policy.

Set Guardrail Config

PUT

/api/sdk/v1/agents/:agentName/guardrails

Set guardrail configuration for an agent

Request

{
  "detectPromptInjection": true,
  "redactPii": true,
  "piiTypes": ["EMAIL", "PHONE", "SSN"],
  "filterContent": true,
  "onViolation": "block",
  "provider": "openai",
  "credentialId": "550e8400-e29b-41d4-a716-446655440000"
}

200 OK

{
  "agent_name": "customer-support-agent",
  "guardrail_config": {
    "detectPromptInjection": true,
    "redactPii": true,
    "piiTypes": ["EMAIL", "PHONE", "SSN"],
    "filterContent": true,
    "onViolation": "block",
    "provider": "openai",
    "credentialId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "status": "configured"
}

Get Guardrail Config

GET

/api/sdk/v1/agents/:agentName/guardrails

Get guardrail configuration for an agent

200 OK

{
  "agent_name": "customer-support-agent",
  "guardrail_config": {
    "detectPromptInjection": true,
    "redactPii": true,
    "piiTypes": ["EMAIL", "PHONE", "SSN"],
    "filterContent": true,
    "onViolation": "block",
    "provider": "openai",
    "credentialId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "enabled": true
}

Remove Guardrails

DELETE

/api/sdk/v1/agents/:agentName/guardrails

Remove guardrail configuration from an agent

Example

curl -X DELETE "https://your-instance.nodeloom.io/api/sdk/v1/agents/customer-support-agent/guardrails" \
  -H "Authorization: Bearer sdk_..."

Agent Callback

Register Callback

POST

/api/sdk/v1/agents/:agentName/callback

Request

{
  "callback_url": "https://example.com/webhooks/agent-complete"
}

200 OK

{
  "agent_name": "customer-support-agent",
  "callback_url": "https://example.com/webhooks/agent-complete",
  "status": "registered"
}

Remove Callback

DELETE

/api/sdk/v1/agents/:agentName/callback

Remove the callback URL for an agent

Example

curl -X DELETE "https://your-instance.nodeloom.io/api/sdk/v1/agents/customer-support-agent/callback" \
  -H "Authorization: Bearer sdk_..."

Red Team

Trigger adversarial red team scans against a workflow to test its resilience to prompt injection, jailbreaks, and other attack categories.

Start Red Team Scan

POST

/api/sdk/v1/redteam/scan

Start a red team scan against a workflow

Field	Type	Required	Description
`workflow_id`	UUID	Yes	The workflow to scan
`categories`	string[]	No	Attack categories to test (e.g., "prompt_injection", "jailbreak", "data_leak")

Request

{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "categories": ["prompt_injection", "jailbreak", "data_leak"]
}

200 OK

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "running",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_attacks": 24,
  "completed_attacks": 0,
  "successful_attacks": 0,
  "resilience_score": null,
  "categories": ["prompt_injection", "jailbreak", "data_leak"],
  "created_at": "2026-03-24T10:00:00.000Z"
}

Get Scan Status

GET

/api/sdk/v1/redteam/scan/:scanId

Get the status and results of a red team scan

200 OK

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "completed",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_attacks": 24,
  "completed_attacks": 24,
  "successful_attacks": 3,
  "resilience_score": 0.875,
  "categories": ["prompt_injection", "jailbreak", "data_leak"],
  "created_at": "2026-03-24T10:00:00.000Z",
  "completed_at": "2026-03-24T10:02:30.000Z"
}

Evaluation

Trigger an LLM-as-judge evaluation for a completed execution. The evaluation runs asynchronously and results are available in the dashboard.

Trigger Evaluation

POST

/api/sdk/v1/evaluate

Trigger LLM evaluation for an execution

Field	Type	Required	Description
`execution_id`	UUID	Yes	The execution to evaluate

Request

{
  "execution_id": "550e8400-e29b-41d4-a716-446655440000"
}

200 OK

{
  "status": "queued",
  "execution_id": "550e8400-e29b-41d4-a716-446655440000"
}

Dashboard Endpoints

These endpoints are used by the NodeLoom dashboard to view SDK agents and review ingestion logs. They require JWT cookie authentication and team admin permissions. SDK tokens are managed from Settings → Observability SDK in the dashboard.

List SDK Agents

GET

/api/sdk/management/team/:teamId/agents

List virtual workflows created by SDK agents

200 OK

[
  {
    "id": "uuid",
    "name": "customer-support-agent",
    "agentVersion": "1.2.0",
    "lastExecutedAt": "2026-03-06T14:00:00.000Z",
    "executionCount": 5678,
    "createdAt": "2026-02-15T09:00:00.000Z"
  }
]

Ingestion Logs

GET

/api/sdk/management/team/:teamId/ingestion-logs

Get recent telemetry batch submission logs

Parameter	Type	Default	Description
`page`	integer	0	Page number (zero-indexed)
`size`	integer	50	Page size (max 100)

200 OK

{
  "logs": [
    {
      "id": "uuid",
      "eventsReceived": 25,
      "eventsAccepted": 25,
      "eventsRejected": 0,
      "sdkVersion": "0.1.0",
      "sdkLanguage": "python",
      "processingTimeMs": 42,
      "createdAt": "2026-03-06T14:00:00.000Z"
    }
  ],
  "totalElements": 150,
  "totalPages": 3,
  "currentPage": 0
}

Get SDK Config

GET

/api/sdk/management/team/:teamId/config

Get SDK configuration info for the team

200 OK

{
  "endpoint": "https://your-instance.nodeloom.io/api/sdk/v1",
  "enabled": true,
  "activeTokenCount": 3
}

Error Codes

Status	Meaning
`400`	Invalid request body, missing required fields, or batch size exceeds 100
`401`	Invalid, expired, or revoked SDK token (telemetry endpoints) or missing JWT (management endpoints)
`403`	SDK feature not available on your plan, or insufficient team permissions
`422`	Event validation failed (invalid type, missing trace_id, etc.)

Guardrails

Audit