The learning API.

Send Authorization: Bearer YOUR_ACCOUNT_KEY to the Conceiver API URL for your deployment. JSON bodies use Content-Type: application/json. Mutations need an Idempotency-Key, except training-text ingestion, whose canonical file content supplies its replay identity.

Routes

Select a model

GET /v1/models lists the current hosted modes. Language can be selected directly:

{"model":"language"}

JSON also requires the agent host and an opaque compatibility-scope digest:

{
  "model": "json",
  "contract": "toolving-conceiver-json-v1",
  "client": {
    "kind": "agent-harness",
    "host": "pi",
    "compatibilityScope": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}

Instances share private learning only inside the same account and compatibility scope. Omitting model retains the default language selection for existing clients.

GET /v1/storage returns enabled, its backend, and applicable byte accounting. Saving a training sequence requires enabled storage for managed customer accounts. Ingestion remains available without storage, but that live learning is not retained after final retirement.

Teach an answer

After creating an instance, use its returned ID:

curl "$TOOLVING_API_URL/v1/instances/$INSTANCE_ID/teach" \
  -H "Authorization: Bearer $TOOLVING_API_KEY" \
  -H "Idempotency-Key: invoice-answer" \
  -H "Content-Type: application/json" \
  -d '{"question":"Where do invoices go?","answer":"Finance / inbox"}'

Questions and answers are single-line strings. Outer whitespace is trimmed by the model. Queries record observations and predictions; use a new key for a new observation, even if the question is unchanged. Support for raw JSON syntax within Conceiver's taught language is in active development.

Training sequence text

Reading an instance's training sequence follows evidence from the account's private plastic trie to the teaching occurrences that support constructions. It returns the assembled text without storing it, so Free accounts can copy and manage it locally. Saving the same content as an account file requires enabled storage. The text contains no addresses or event envelopes:

Where do invoices go?
Finance / inbox

Where do alerts go?
Operations / alerts

Every teaching is two nonempty adjacent lines. One empty line separates teachings, and the file ends with LF. Ingestion rejects other layouts and sends each accepted pair through the normal teaching path. Re-ingesting the same content in one model compatibility scope is idempotent.

Prediction confidence

A successful query operation returns a receipt with its native prediction in result:

{
  "status": "ANSWER",
  "text": "talked",
  "output": "talked",
  "confidence": "confident",
  "evidence": {
    "format": "text/markdown",
    "markdown": "The examples and counterexamples behind this decision."
  }
}

confidence is hypothesis, confident, or high. The release policy assigns those levels to one, two, and three or more independent supporting examples. They describe evidence, not probability percentages. Contradictions lower confidence. An unresolved prediction carries the available evidence instead of inventing an answer:

{
  "status": "UNRESOLVED",
  "confidence": "hypothesis",
  "evidence": {
    "format": "text/markdown",
    "markdown": "Relevant evidence for downstream decision-making."
  }
}

Episodic memory

Set withMemory to true on a query to return complete relevant episodes with the decision evidence:

{
  "question": "Where do invoices go?",
  "withMemory": true
}

The response evidence then includes episodes, an array of complete input and output examples. A successful memory-enabled query costs 2 credits. A standard prediction or retrieval costs 1 credit.

Without account storage, memory is ephemeral and final instance retirement discards it. With storage, final retirement saves learned capabilities in a verified artifact that a fresh instance loads automatically. The retirement result includes the artifact format, SHA-256 digest and byte count.

Check status to determine whether an answer was returned. No-support results omit confidence. Older stored receipts and instances using older application bundles can also lack it; a new instance uses the updated bundle with the same account's existing learning. Recovery through /v1/operations/{id} and retries return the original confidence after later learning.

Recovery and errors

Reusing a key with different content returns 409. Invalid input returns 422. An accepted operation interrupted by a lost runtime response may return 503 with an operation ID. Inspect that operation or repeat the same request with its original key; the accepted event remains durable.

Only your account can access its instances, sequences and predictions. Saved sequences keep their model version. A model-version mismatch remains an error rather than silently changing the saved work.

The customer deployment exposes its interactive native schema at API reference. An earlier website deployment may still expose the older learner service there; check that its schema contains /v1/instances.

Customer account

The browser account page uses Clerk session bearer tokens for /v1/account, key management at /v1/account/keys, and operation counts at /v1/account/usage. Machine API keys authorize the learning routes above; they do not authorize browser account management. Operation counts come from durable native operation identities, so retrying the same accepted request does not add another operation. These counts do not define prices or charges.