Inspectable state

See what a shared mind understands, inspect its evidence, and control what influences its answers.

A mind develops understandings through experience. Inspection exposes those understandings as statements, supporting or contradicting experiences, and models that organize related understandings.

These endpoints require a backend project API key, an active shared mind, and inspection enabled for your organization. Actor-private minds return 403, even if you also supply an actor token. Keep inspection and intervention controls on your trusted backend.

Read what matters

curl "https://api.pluralmatter.com/v1/minds/mind_example/understandings?limit=5" \
  -H "Authorization: Bearer $PLURAL_MATTER_API_KEY"

Each understanding has an opaque id, its own statement, an influence band, an experience count, and a state:

active: eligible to influence answers.
suppressed: directly held out by a standing influence; it remains inspectable and restorable.
excluded: held out because its sources are covered by another suppression.

Influence describes prominence in answering, not certainty or truth. When statementAvailable is false, inspect the evidence rather than treating “Statement unavailable” as a learned claim.

The response also includes models, a compact landscape, and active influences. A model is a coherent body of understanding about something. Models include less prominent groups and groups whose members are currently suppressed. An understanding may belong to several models. modelGroups is a compatibility alias of models.

To continue a list, send the returned nextOffset as offset with its revision. A changed mind returns 409; restart the list rather than combining old and new pages. The unfiltered first page includes every restore control, so it may exceed limit when many understandings are suppressed.

Add model_id to browse the complete membership of a model. total and nextOffset then refer to that model. The landscape remains a compact view of the whole mind.

See what changed

The list response includes recentChanges across the whole mind, including understandings outside the current page or selected model. It compares the current state with its nearest retained predecessor. from and to, when available, identify that comparison interval; they do not promise a weekly trend or a complete event history.

Changes distinguish new understandings, revised statements, increased or decreased confidence, changed evidence, changed evidence standing, and understandings no longer present. Confidence reflects the mind’s assessment, not verified truth. Ordinary recall, changing prominence and elapsed time do not count as learning. A removed understanding was not necessarily disproved.

Model changes describe coherent bodies of understanding appearing, changing, or no longer appearing as separate models. Understanding changes include an opaque id, the current or last known statement, human-readable changes, and whether the understanding is still present. Statement revisions also include previousStatement. These historical entries may no longer resolve through the current detail endpoint.

When status is available, list rows include a trend summary or Unchanged. When no earlier state remains available, status is unavailable, the change lists are empty, and row trends are omitted. Do not interpret unavailable history as an absence of learning. The dashboard shows a compact list that expands to all returned changes.

Inspect why

curl "https://api.pluralmatter.com/v1/minds/mind_example/understandings/UNDERSTANDING_ID" \
  -H "Authorization: Bearer $PLURAL_MATTER_API_KEY"

The detail response contains the understanding and all available evidence. Each excerpt states whether it supports or contradicts the understanding and includes a date when known. An understanding removed by later learning returns 404; an answer's retained trace can still describe what influenced that earlier answer.

Expectations and outcomes

curl "https://api.pluralmatter.com/v1/minds/mind_example/expectations?limit=5" \
  -H "Authorization: Bearer $PLURAL_MATTER_API_KEY"

This returns recorded expectations, newest first, with opaque identifiers and dates when known. It reads existing state without generating or judging an outcome. Use nextOffset and revision to continue; 409 means a verdict or its evidence changed, so restart pagination.

open: awaiting an outcome that settles the expectation.
confirmed: the mind assessed a later experience as supporting the expectation.
refuted: the mind assessed a later experience as contradicting the expectation.
unverifiable: a historical verdict exists, but its grounding is unavailable to inspect; recordedOutcome preserves that earlier verdict.

Confirmed and refuted entries include the outcome experience in outcome.text, with occurredAt when known. If the experience is removed, the entry becomes unverifiable rather than continuing to claim accessible supporting evidence. When expectationAvailable is false, the statement is unavailable. Decision reasoning and numeric confidence are not part of this response.

Ask without teaching

curl https://api.pluralmatter.com/v1/minds/mind_example/query \
  -H "Authorization: Bearer $PLURAL_MATTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"What matters for customer renewals?"}'

This returns matching understandings. It does not generate an answer, record access, or teach the mind.

Pin an understanding

Pins keep selected understandings prominent and protect them from routine forgetting. New evidence can still revise them: a pin does not make a statement true or preserve every historical source.

curl https://api.pluralmatter.com/v1/minds/mind_example/influences \
  -H "authorization: Bearer $MIND_API_KEY" \
  -H "content-type: application/json" \
  -d '{"understanding_id":"UNDERSTANDING_ID","effect":"pin"}'

The understanding list returns all pins separately from suppression influences, plus the authoritative pinLimit. The default capacity is 25 per mind. Plural Matter admins can adjust the limit; lowering it preserves existing pins and blocks new pins until there is room. A full mind returns 409 when another pin is requested. Repeating an existing pin returns that pin.

Delete the returned influence ID to unpin, using the same removal operation shown below. Unpinning resumes ordinary prominence and retention without rewinding learning. An understanding can be both pinned and suppressed; suppression still holds it out of answers. In the dashboard, Pin and Unpin appear on understanding rows and in Why, and the pinned list keeps every Unpin control accessible.

Preview, suppress, restore

Preview the same question with and without a pending suppression:

curl https://api.pluralmatter.com/v1/minds/mind_example/influence-preview \
  -H "Authorization: Bearer $PLURAL_MATTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"What matters for customer renewals?","understanding_id":"UNDERSTANDING_ID"}'

before and after show the understandings available for that question from one captured state. affectedUnderstandings counts the full impact across the mind, including other understandings that share the suppressed sources. A preview makes no changes. It previews context, so generated answers can differ from the apparent emphasis of either list.

Apply with the returned revision as preview_revision:

curl https://api.pluralmatter.com/v1/minds/mind_example/influences \
  -H "Authorization: Bearer $PLURAL_MATTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"understanding_id":"UNDERSTANDING_ID","preview_revision":"PREVIEW_REVISION"}'

The revision is checked when the influence is saved. If learning or another intervention changed the mind, the request returns 409 without applying it. Refresh the preview before trying again.

Sources are included by default. If older provenance is incomplete, source-inclusive preview or suppression returns 409. Explicitly setting include_evidence to false in both requests holds out only the selected understanding; its source material and other understandings remain eligible. Choose that narrower effect deliberately. An existing suppression with incomplete source mapping may pause answering until it is restored.

The response contains influence.id. Restore with:

curl -X DELETE https://api.pluralmatter.com/v1/minds/mind_example/influences/INFLUENCE_ID \
  -H "Authorization: Bearer $PLURAL_MATTER_API_KEY"

Success returns 204 with no body. Restore removes the standing suppression; it does not rewind learning that occurred in the meantime. Repeating a suppression returns its existing influence. Restoring an already removed influence returns 404.

Read what influenced an answer

For shared minds with inspection enabled, successful JSON message responses include:

{
  "mind": {
    "influenced_by": ["OPAQUE_UNDERSTANDING_ID"],
    "influence_trace": {
      "asOf": "2026-09-04T12:00:00.000Z",
      "understandings": [
        {
          "id": "OPAQUE_UNDERSTANDING_ID",
          "statement": "Customers value reliable service.",
          "statementAvailable": true
        }
      ]
    }
  }
}

These are the understandings selected as answer context, with their statements retained at answer time. They are not a claim that each statement caused a particular sentence. An empty list means no understandings were selected; an absent extension means no trace is available or inspection is unavailable.

Streaming responses put the same extension in message_start.message.mind. Other stream events retain their normal shapes. Receiving the extension does not mean the response finished; continue handling stream errors and completion. Check the response content type on retries: a successful idempotent replay can return JSON even when the original request streamed.

GET /v1/requests/{request_id} includes influenced_by and influence_trace at the top level once the trace is durably available. Poll using x-mind-request-id. This trace survives later revision or removal of the understanding. Older requests may not have a trace. Actor-private minds, disabled inspection, and inactive minds do not expose these fields through public request lookup.

Model and contemplation status

GET /v1/minds/{mind_id}/lifecycle returns the same semantic models as the understanding list, the number of pending updates, and recent contemplation operation statuses. It does not expose internal storage lifecycle states.

A completed contemplation can include a durable reflection report. Find an operation ID in lifecycle.contemplations, then read it:

curl "https://api.pluralmatter.com/v1/minds/mind_example/contemplate/OPERATION_ID" \
  -H "Authorization: Bearer $PLURAL_MATTER_API_KEY"

When available, reflection.understandings records the statements and change labels from that run, including a previousStatement when wording changed. reflection.models records changes to the mind’s semantic models. These are historical descriptions captured when contemplation completed; later learning can change the current understanding. Confidence changes describe the mind’s assessment, and removal does not mean disproof.

The report commits with the changed mind and survives later revision or removal of those understandings. Retried delivery of the same completed operation does not run contemplation again. Older operations have no report. Empty lists mean the completed run produced no detected understanding or model changes. An abstained outcome means no reflection was needed.

Operation status remains available through the existing management authorization. The reflection field is omitted when inspection is disabled, the mind is inactive, or an API key requests an actor-private mind. Private reasoning, numeric confidence, and internal identifiers are excluded.

Correct an understanding

For a shared mind, a correction records the operator’s exact words as experience and queues learning. It also supplies contradicting evidence for the addressed understanding while that statement still matches. Existing statements are preserved. The mind may revise its conclusions through learning; a correction does not guarantee truth or a particular answer.

curl https://api.pluralmatter.com/v1/minds/mind_example/corrections \
  -H "Authorization: Bearer $PLURAL_MATTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"understanding_id":"UNDERSTANDING_ID","expected_statement":"Customers prioritize price","statement":"Customers prioritize reliability over the lowest price.","idempotency_key":"customer-feedback-correction-1"}'

Use the exact id and statement returned by inspection. The authenticated key identifies the operator; do not send actor_id. These public endpoints support shared minds only and require inspection to be enabled. Normal learning usage and limits apply.

A 202 response includes request_id and mind_update_status. Acceptance is separate from learning. Poll /v1/requests/REQUEST_ID: committed means learning finished, queued or retryable means it is still pending, and skipped means it could not be learned. Inspect the understanding again after learning to see its current evidence.

If a response is lost, retry the same input with the same idempotency key. Successful replay returns the original request even if the understanding has since changed. Reusing the key with different input returns 409. If a new correction receives 409 because its addressed statement changed, refresh inspection and decide whether the correction still applies before submitting it with a new key.

If the addressed statement changes or disappears after acceptance, the correction is still retained and learned as operator testimony, but it is not attached as contradicting evidence to the changed or missing statement.

Choose an audience in the dashboard

For an actor-private mind, the dashboard offers One actor or Everyone using this mind when you correct an understanding. Choose a recent actor or enter the actor ID your application uses. Your operator identity remains the recorded source in either case.

One actor makes the new correction available only to that actor. If the addressed understanding is also visible to others, its existing standing is preserved for them; the selected actor can still learn from the new private testimony. Everyone using this mind shares the new correction with current and future actors. It does not expose the addressed actor’s earlier private evidence.

The audience is fixed when the correction is accepted. Retrying preserves it; changing the audience requires a new correction. Public inspection and correction endpoints continue to require a shared mind.

Inspectable state

On this page