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 learnings.

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.

A learning you write is not scrubbed for you

Automatic extraction strips credentials, personal data and the raw goal text before a learning is stored. A learning you POST here is stored as you send it, source_goal included, and defaults to shareable. Send generalized learnings and a description of the task, never a customer's raw request. See Sharing and visibility.

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 the pool of learnings promoted across agents in your organization, filtered to the spaces you can read. It requires an Enterprise subscription; other plans get a 403. What has to be true before a learning reaches that pool is covered in Sharing and visibility.

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

Reject a learning

POST /agents/{agent_id}/learnings/{learning_id}/reject archives a live learning with curator provenance, for a learning that should not be in play at all.

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings/<LEARNING_ID>/reject" \
  -d '{
    "reason_code": "manually_curated",
    "reason": "Superseded by the revised escalation policy"
  }'

Prop

Type

Required scope: agents:write

Rejection is editorial, not evidential. It takes the learning out of circulation and leaves its utility and trust untouched, which is the difference between this and unhelpful reinforcement: reinforcement says the learning did not work, rejection says it should not have been there at all.

List the claims behind a learning

GET /agents/{agent_id}/learnings/{learning_id}/claims lists the claims connected to a learning, so you can see which specific claims it is leaning on.

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

Prop

Type

This endpoint pages at 25 by default, so a learning leaning on more claims than that returns a partial list unless you follow next_cursor.

Required scope: claims:read

This is the read that answers why does the agent believe this learning applies here, and it is where a stale learning usually shows itself: one resting on a claim that has since been superseded or held for review.

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 promoted across agents in your organization, filtered to the spaces you can read. It requires an Enterprise subscription. Evidence is stripped at promotion time, so items report org_stripped and summarize cross-agent corroboration rather than carrying the cases the learning was formed from. See Sharing and visibility.

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 learning.
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
Claims API for governing the claims a learning can lean on

On this page