Plans API
Search the workflows an agent has seen before when you need direct visibility into prior reasoning plans.
Plans are stored reasoning workflows from prior agent runs. Hyperstruck agents already search their known workflows during normal reasoning, so most users do not need to call the Plans API directly.
Use this API when you want to query that memory surface yourself: for example, to see whether an agent has handled a sales follow-up workflow like the one you are about to send, inspect similar prior account goals, or compare relevant history across a small set of agents.
Access control
Plan search requires agents:read and read access on each agent queried. See Access control (FGA and RBAC).
Usually automatic
Start with normal agent runs first. Agents already look for relevant known workflows while planning, so direct plan search is mainly for inspection, debugging, routing, and custom UI surfaces.
Search one agent
GET /agents/{agent_id}/plans/similar searches one agent's prior plans using a natural-language query.
curl -H "Authorization: Bearer <API_KEY>" \
"https://api.hyperstruck.com/agents/<AGENT_ID>/plans/similar?q=client+XYZ+sales+follow-up+plan&limit=10"Prop
Type
Required scope: agents:read
Search multiple agents
POST /plans/similar searches across an explicit set of tenant-owned agents and merges the most similar results.
curl -X POST \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
"https://api.hyperstruck.com/plans/similar" \
-d '{
"agent_ids": ["<AGENT_ID>", "<SECOND_AGENT_ID>"],
"q": "find workflows for planning a sales follow-up with next steps and buying committee risks",
"limit": 10
}'Prop
Type
Every agent_id must be accessible to your tenant. The endpoint searches agents in parallel, caps each agent at 10 candidate plans, sorts matches by similarity, and may return partial_failures if one agent's retrieval path fails while other results are still available.
Required scope: agents:read
Response shape
Each result includes the matched plan metadata, a similarity_score, and any candidate learnings surfaced alongside that plan.
candidate_learnings stay compact in plan-search responses. If a candidate learning has instance evidence and you need to inspect it, fetch the full learning with GET /agents/{agent_id}/learnings/{learning_id}.
{
"items": [
{
"plan": {
"plan_id": "plan-123",
"agent_id": "00000000-0000-0000-0000-000000000000",
"goal": "Create a follow-up sales execution plan for a call with client XYZ",
"is_success": true,
"executed_at": "2026-04-12T10:11:12Z",
"num_steps": 0
},
"similarity_score": 0.83,
"candidate_learnings": [
{
"learning_id": "learning-1",
"content": "At client XYZ, directors and below are usually influencers, not final decision-makers, so map the buying committee before assigning next steps.",
"score": 0.71,
"trust_level": "agent_verified"
}
]
}
],
"retrieved_at": "2026-04-21T08:00:00Z",
"partial_failures": []
}When to query plans directly
- Use direct plan search when building an internal "what has this agent seen before?" view.
- Use it before dispatching a high-stakes sales workflow if you want to inspect similar prior account goals and outcomes yourself.
- Use multi-agent search to route an account workflow to the agent with the most relevant sales history.
- Use it while debugging memory behavior, especially when an agent seems to miss or over-weight prior workflow context.
You usually should not query plans just to make an agent smarter before a run. Send the goal to the agent; Hyperstruck already searches relevant known workflows during planning.
Related pages
- Access control (FGA and RBAC) for scope and FGA requirements
- Agents API for dispatching goals that automatically use relevant known workflows
- Learnings API for directly managing reusable lessons
- Reasoning for the conceptual model behind plan-aware execution