POST /learn/{pid} — Submit State Label Corrections - NSP

POST /learn/{pid} lets you teach the NSP daemon what state keys really mean. When the probe labels a field with a generic name like unknown_0x4a2f, when it assigns the wrong type to a value, or when an action is bound to the wrong function, you can submit a correction and the daemon incorporates it into the schema registry. Your correction takes effect on the very next probe cycle — typically within 2 seconds — and the schema version is bumped so you can track when the change landed.

Endpoint

POST /substrate/v1/learn/{pid}
X-Substrate-Key: <key>
Content-Type: application/json

integer

required

OS process ID of the target application. Obtain from GET /apps.

Request Body

{
  "corrections": [
    {
      "observed_key": "unknown_0x4a2f",
      "correct_label": "inbox.unread_count",
      "correct_type": "number",
      "confidence": 0.95,
      "notes": "This field always matches the unread badge count in the Gmail tab title"
    }
  ],
  "schema_version": "1.4.2"
}

array

required

List of label corrections to submit. You may include multiple corrections in a single request.

Show Correction item fields

string

required

The key as it currently appears in the objects map — including unknown or mislabeled keys like unknown_0x4a2f.

string

required

The dot-notation label this key should carry, for example "inbox.unread_count".

string

required

The correct type for the value. One of: number, string, boolean, object, array.

float

required

Your confidence that this correction is accurate, from 0.0 (uncertain) to 1.0 (certain). Higher confidence corrections are weighted more strongly in the schema registry.

string

Optional plain-language description that explains why this correction is correct. Include any observations that would help the daemon or other agents understand the mapping.

string

required

The current schema version from SubstrateState.schema_version. The daemon uses this to detect stale corrections — if the schema has already moved past the version you supply, the correction may be rejected.

Response

{
  "accepted": 1,
  "rejected": 0,
  "new_schema_version": "1.4.3",
  "message": "1 correction applied. Schema updated to 1.4.3."
}

integer

Number of corrections that were validated and written to the schema registry.

integer

Number of corrections that were rejected, for example due to a stale schema_version or an invalid correct_type value.

string

The schema version after accepted corrections were applied. Use this value as schema_version in subsequent /learn calls.

string

Human-readable summary of the outcome.

When to Use `/learn`

Submit corrections in any of the following situations:

A state key appears as unknown_XXXX — the probe could not automatically label it, but you know what it represents.
A key has the wrong type — for example the probe labeled a numeric badge count as string instead of number.
An action is bound to the wrong runtime function — for example archive is invoking the wrong method on a JVM target.
You want to improve the overall confidence score for an application after initial attachment.

Every accepted correction bumps the schema_version by a patch increment. After submitting corrections, re-read the state via GET /state/{pid} to confirm that the new labels appear in the objects map within the next probe cycle (within 2 seconds of acceptance).

Error Responses

Status	Code	Description
`400`	`bad_request`	Invalid `correct_type` value or malformed correction entry.
`401`	`unauthorized`	Missing or invalid `X-Substrate-Key` header.
`404`	`not_found`	The specified PID is not tracked by the daemon.
`429`	`rate_limited`	Exceeded the 10 requests/second rate limit.

Endpoints

Data Models

POST /learn/{pid} — Submit State Label Corrections

Endpoint

Request Body

Response

When to Use `/learn`

Error Responses

​Endpoint

​Request Body

​Response

​When to Use /learn

​Error Responses

Endpoint

Request Body

Response

When to Use `/learn`

Error Responses