Learnings API

Manually store, search, retrieve, and reinforce learnings when you want direct control over what the system carries forward.

Hyperstruck can already extract learnings automatically from reasoning runs. The Learnings API is the lighter manual control surface for teams that want to inject, curate, search, and reinforce specific lessons.

Access control

Read operations require agents:read and read access on the agent. Write operations require agents:write and curate access on the agent. Deleting all learnings requires admin access. See Access control (FGA and RBAC).

Start small

Start with the minimum required fields. Full API reference lives in the OpenAPI docs.

Store a learning

Prop

Type

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings" \
  -d '{
    "content": "qualify_lead returns cold for cybersecurity companies",
    "applicable_tools": ["qualify_lead"],
    "instances": [
      {
        "entity_values": {
          "company": "CrowdShield",
          "industry": "cybersecurity"
        },
        "outcome": {
          "tier": "cold",
          "score": "0.12"
        },
        "source_context": "api"
      }
    ]
  }'

This endpoint returns 202 Accepted with a request_id handle. Background processing handles validation and indexing, so it may take a moment before the learning appears in search results.

There is no learning type to choose. Hyperstruck derives how a learning behaves from its evidence (the entities, outcomes, and tools you attach), not from a category label you pick up front. Supply good content, applicable_tools, and instances, and the platform does the rest.

instances is optional and backward-compatible. Use it for concrete input-to-outcome examples, tool behavior observations, test cases, compacted external-run evidence, and other structured evidence. Do not store raw logs, secrets, PII, or internal hostnames.

Each evidence instance must include non-empty entity_values and outcome maps with string keys and string values. If source_context is omitted, the platform API defaults it to api. API-sourced evidence is content-addressed by its entity values and outcome, so duplicate entity/outcome examples collapse into one instance.

Required scope: agents:write

Access: requires curate permission on the agent.

List learnings

GET /agents/{agent_id}/learnings returns an audit inventory of learnings for one agent.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings"

Prop

Type

Required scope: agents:read

Search learnings

The only required query param is q.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings/search?q=migration+dependency+graph"

Prop

Type

org scope searches shared learnings across agents and is available on eligible plans.

Required scope: agents:read

Each result wraps a learning and its relevance score. A learning carries its two-axis standing: utility is the value it delivered when applied, and reliability is how corroborated it is across independent observations (with the supporting corroboration_count). Results may also include compact evidence instances:

{
  "items": [
    {
      "learning": {
        "learning_id": "learning-1",
        "content": "qualify_lead returns cold for cybersecurity companies",
        "standing": {
          "utility": 0.74,
          "reliability": 0.5,
          "corroboration_count": 2
        },
        "trust_level": "unverified",
        "instances": [
          {
            "id": "instance-1",
            "entity_values": {
              "company": "CrowdShield",
              "industry": "cybersecurity"
            },
            "outcome": {
              "tier": "cold",
              "score": "0.12"
            },
            "source_context": "api",
            "created_at": "2026-05-17T02:01:00Z"
          }
        ]
      },
      "score": 0.88
    }
  ],
  "total": 1
}

Get a learning

No body or query params are required.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings/<LEARNING_ID>"

Required scope: agents:read

Read responses include the full learning, its standing, and the evidence instances currently attached:

{
  "learning_id": "learning-1",
  "content": "qualify_lead returns cold for cybersecurity companies",
  "standing": {
    "utility": 0.74,
    "reliability": 0.5,
    "corroboration_count": 2
  },
  "trust_level": "unverified",
  "privacy": "shareable",
  "scope": "agent",
  "is_archived": false,
  "applicable_tools": ["qualify_lead"],
  "instances": [
    {
      "id": "instance-1",
      "entity_values": {
        "company": "CrowdShield",
        "industry": "cybersecurity"
      },
      "outcome": {
        "tier": "cold",
        "score": "0.12"
      },
      "source_context": "api",
      "created_at": "2026-05-17T02:01:00Z"
    }
  ]
}

Reinforce a learning

Prop

Type

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings/<LEARNING_ID>/reinforce" \
  -d '{
    "is_helpful": true
  }'

Reinforcement updates the learning's standing and advances its trust level. Helpful feedback raises utility and adds corroboration; unhelpful feedback lowers utility:

{
  "learning_id": "learning-1",
  "standing": {
    "utility": 0.79,
    "reliability": 0.55,
    "corroboration_count": 3
  },
  "trust_level": "unverified",
  "times_applied": 1,
  "times_helpful": 1
}

Required scope: agents:write

Inspect learning evidence graph

GET /agents/{agent_id}/learnings/graph returns a lineage graph around one learning.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings/graph?learning_id=<LEARNING_ID>"

Prop

Type

Required scope: agents:read

Delete all learnings for an agent

DELETE /agents/{agent_id}/learnings removes every learning memory for the agent and returns a deleted_count.

curl -X DELETE \
  -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings"

Required scope: agents:write

Access: requires admin permission on the agent.

List org-shared learnings

GET /org/learnings lists learnings shared across agents in your organization. Available on eligible plans.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/org/learnings"

Prop

Type

Required scope: agents:read

When to use manual learning

Use automatic learning first for low-friction compounding improvement.
Use manual learning when you want direct editorial control over a lesson.
Use reinforcement when you want to strengthen or down-rank a retrieved learning based on whether it helped.

Access control (FGA and RBAC) for scopes and space reach
Quickstart for the fastest end-to-end flow
Learning for the conceptual model
Agents API for reasoning runs that can produce automatic learnings
Plans API for searching prior workflows and their candidate learnings

On this page