Create Learning

Storage and identity

Use a registered database with learning methods. Specify db_id when several databases are available; table also requires db_id. RemoteDb and adapters without learning support return 501.

Human JWT callers are scoped when user isolation is enabled. Non-admin service-account PAT callers always self-scope. Scoped readers can access their own and shared records; other-owned records return 404. Shared records cannot be modified or deleted by a scoped caller (403). Admins and unscoped callers retain access under the deployment's authentication and permission configuration.

Supply the identity fields

The endpoint does not fill missing identity fields from the JWT subject. Supply the fields used by the target learning store:

learning_typeRequired identity
user_profile, user_memoryuser_id
session_contextsession_id
entity_memoryentity_id and entity_type; also user_id for namespace user

For example, the body for a user profile is:

{"learning_type":"user_profile","user_id":"your-user-id","content":{"name":"Alex"}}

Use the actual user identity. A scoped caller's supplied user_id must match the caller (403 on mismatch); the broader generated field description does not apply that restriction to admins or unscoped callers. Identity-keyed records reject duplicate creation with 409; use PATCH to update the existing record. Entity memory defaults to namespace global, so explicitly match your store's namespace.

POST/learnings

Create a new learning record. For the identity-keyed learning types (user_profile, user_memory, session_context, entity_memory) the record id is derived deterministically from the identity fields so it reconciles with what the agent reads/writes — provide those fields (else 422), and if a record already exists the request is rejected with 409 (use PATCH to update it). Other types get a generated id. For a scoped (non-admin) caller, the body's user_id must be omitted/null or match the caller (mismatch → 403); admins and unscoped callers may set any user_id. An entity_memory record whose body omits namespace is stored under the global default; the endpoint cannot see how a given store is configured, so a caller writing for a store running with namespace="user" or a custom namespace must pass namespace explicitly or the record will not be visible to it.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

db_id?|

Database ID to use

table?|

The database table to use (requires db_id)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for creating a learning record.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request POST 'https://example.com/learnings' \  --header 'Content-Type: application/json' \  --data-raw '{"learning_type":"string","content":{}}'
{  "learning_id": "string",  "learning_type": "string",  "namespace": "string",  "user_id": "string",  "agent_id": "string",  "team_id": "string",  "session_id": "string",  "entity_id": "string",  "entity_type": "string",  "content": {},  "metadata": {},  "created_at": 0,  "updated_at": 0}