NSP API Reference — endpoints, auth, and error format - NSP

The NSP daemon exposes a REST and WebSocket API on http://127.0.0.1:7842. All endpoints except GET /health are prefixed with /substrate/v1 and require an API key. You interact with this API from any HTTP client, the official Python SDK, or directly from an AI agent’s tool calls.

Base URL

http://127.0.0.1:7842

The daemon binds to the loopback address by default. You cannot reach it over the public network unless you configure a reverse proxy — this is intentional. All endpoint paths (except /health) share the /substrate/v1 prefix.

Authentication

Pass your API key in the X-Substrate-Key request header on every call:

curl -H "X-Substrate-Key: sk_nsp_a1b2c3d4e5f6..." \
     http://127.0.0.1:7842/substrate/v1/apps

If auth_enabled is false in /health, you may omit the header. For the WebSocket endpoint (/watch), pass the key as a key query parameter instead, since not all WebSocket clients support custom headers at the upgrade phase.

Generate and revoke API keys from the Nelieo platform dashboard. Keys are scoped to your daemon instance — they are not global credentials.

Endpoint Summary

Method	Path	Auth	Rate Limit	Description
`GET`	`/health`	None	None	Daemon liveness probe
`GET`	`/substrate/v1/apps`	✓	100/s	List all tracked applications
`GET`	`/substrate/v1/state/{pid}`	✓	100/s	Full semantic state snapshot for a process
`GET`	`/substrate/v1/schema/{pid}`	✓	100/s	Available actions for a process
`POST`	`/substrate/v1/action`	✓	10/s	Execute a typed action on a process
`WS`	`/substrate/v1/watch/{pid}`	✓	—	Real-time state-change stream
`GET`	`/substrate/v1/diff/{pid}`	✓	100/s	Field-level diff since a capture ID
`POST`	`/substrate/v1/verify`	✓	100/s	Evaluate a state expression inline
`POST`	`/substrate/v1/learn/{pid}`	✓	10/s	Submit labeling corrections

Content Type

Send Content-Type: application/json on all POST requests. Every response body is application/json. Requests that omit the content-type header on POST routes return 400 Bad Request.

Request IDs

Every response — including errors — includes an X-Request-Id header containing a time-ordered unique identifier:

X-Request-Id: 01j5abc123def456

Include this value whenever you file a bug report or open a support ticket. The daemon logs every request with its ID, so the support team can correlate your report with the exact trace.

Common HTTP Response Codes

Code	Meaning
`200`	Request succeeded
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — API key missing or invalid
`404`	Resource not found — PID or app not tracked
`422`	Unprocessable — action ran but post-state verification failed
`426`	Upgrade Required — WebSocket endpoint called over plain HTTP
`429`	Rate limit exceeded
`503`	Daemon overloaded, or probe not yet ready
`504`	Timeout — request exceeded 30 s (or 120 s for `/action`)

Error Response Format

All error responses use a consistent JSON envelope. Parse the error.code field programmatically; use error.message for human-readable context:

{
  "error": {
    "code": "not_found",
    "message": "Process 12847 is not tracked. Is the app running?",
    "request_id": "01j5abc123def456"
  }
}

error.code

string

Machine-readable error identifier. Use this in switch / match logic. Examples: not_found, rate_limited, verification_failed, probe_timeout, missing_verify_expression.

error.message

string

Human-readable description of what went wrong and, where possible, how to fix it.

error.request_id

string

The same value sent in the X-Request-Id response header. Always include this in bug reports.

Authentication Example

curl -i \
  -H "X-Substrate-Key: sk_nsp_a1b2c3d4e5f6..." \
  http://127.0.0.1:7842/substrate/v1/apps

from nelieo import NspClient

client = NspClient(api_key="sk_nsp_a1b2c3d4e5f6...", base_url="http://127.0.0.1:7842")

# The SDK injects X-Substrate-Key automatically on every request.
apps = await client.list_apps()

Endpoints

Data Models

NSP API Reference — endpoints, auth, and error format

Base URL

Authentication

Endpoint Summary

Content Type

Request IDs

Common HTTP Response Codes

Error Response Format

Authentication Example

​Base URL

​Authentication

​Endpoint Summary

​Content Type

​Request IDs

​Common HTTP Response Codes

​Error Response Format

​Authentication Example

Base URL

Authentication

Endpoint Summary

Content Type

Request IDs

Common HTTP Response Codes

Error Response Format

Authentication Example