NSP Agent API Reference — Overview and Conventions - NSP

The NSP Agent API is a REST and WebSocket API served locally by the NSP daemon on http://127.0.0.1:7842. Every endpoint except /health lives under the /substrate/v1 path prefix and requires an API key. Use this page as your quick-reference for authentication, available endpoints, response codes, and the standard error envelope that every failure returns.

Base URL

http://127.0.0.1:7842

All endpoints except GET /health are mounted under the /substrate/v1 prefix. For example, the apps list lives at http://127.0.0.1:7842/substrate/v1/apps.

Authentication

Pass your API key in the X-Substrate-Key header on every request except GET /health. Requests that omit the header, or that supply an invalid key, receive a 401 response immediately.

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

Content Type

Set Content-Type: application/json on all requests that include a body (POST endpoints). All responses are returned as application/json.

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 state snapshot for a process
`GET`	`/substrate/v1/schema/{pid}`	✓	100/s	Action schema without state objects
`POST`	`/substrate/v1/action`	✓	10/s	Execute a typed action
`WS`	`/substrate/v1/watch/{pid}`	✓	—	Real-time state change stream
`GET`	`/substrate/v1/diff/{pid}`	✓	100/s	Field-level diff between probe cycles
`POST`	`/substrate/v1/verify`	✓	100/s	Evaluate a state expression
`POST`	`/substrate/v1/learn/{pid}`	✓	10/s	Submit state label corrections

Common Response Codes

Code	Meaning
`200`	Success
`400`	Bad request — invalid or missing parameters
`401`	Unauthorized — missing or invalid API key
`404`	PID or application not found
`422`	Verification failed — action ran but the post-action state check did not pass
`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

When a request fails, the daemon returns a JSON body with a structured error object. Every field is always present.

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

string

Machine-readable error identifier. Use this field in error-handling logic rather than parsing message.

string

Human-readable description of what went wrong.

string

Unique ID for this request. Include it in bug reports or support requests.

Request Tracing

Every response — success or failure — includes an X-Request-Id header you can use for distributed tracing and log correlation.

X-Request-Id: 01j5abc123def456

Endpoints

Data Models

NSP Agent API Reference — Overview and Conventions

Base URL

Authentication

Content Type

Endpoint Summary

Common Response Codes

Error Response Format

Request Tracing

​Base URL

​Authentication

​Content Type

​Endpoint Summary

​Common Response Codes

​Error Response Format

​Request Tracing

Base URL

Authentication

Content Type

Endpoint Summary

Common Response Codes

Error Response Format

Request Tracing