Quickstart
The lowest-friction path from a fresh API key to a working Hyperstruck agent run.
This is the fastest first-success path: create an agent, dispatch a goal, and optionally store a manual learning.
No provider credentials needed
Hyperstruck pays for the model calls an agent makes, so there are no provider credentials to upload.
Keep the first call small
Start with the minimum required fields. Full API reference lives in the OpenAPI docs. If you omit optional fields here, Hyperstruck uses sane defaults.
Minimal flow
1. Create an agent
Create an agent with a name and core_config.instructions. That is the whole requirement. There is no model to pick, and unrecognized fields are rejected rather than ignored.
curl -X POST "https://api.hyperstruck.com/agents" \
-H "Authorization: Bearer <YOUR_HYPERSTRUCK_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "Sales Execution Assistant",
"core_config": { "instructions": "You are a helpful sales execution assistant." }
}'Add an optional description when you want the agent listing to explain itself.
2. Dispatch a goal
Use the returned AGENT_ID to start a run.
curl -X POST "https://api.hyperstruck.com/agents/<AGENT_ID>/goals" \
-H "Authorization: Bearer <YOUR_HYPERSTRUCK_API_KEY>" \
-H "Content-Type: application/json" \
-d '{ "goal": "Create a follow-up sales execution plan for a call with client XYZ" }'Or use the Python SDK
The same two steps with the client doing the plumbing. Install it with pip install hyperstruck.
from hyperstruck import Hyperstruck
hs = Hyperstruck(api_key="<YOUR_HYPERSTRUCK_API_KEY>")
agent = hs.agents.create(
name="Sales Execution Assistant",
instructions="You are a helpful sales execution assistant.",
)
run = agent.run("Create a follow-up plan for the client XYZ call")
print(run.result)Runs block until the goal resolves. Use await agent.arun(...) inside an event loop, and fall back to the REST calls above from any language the SDK does not cover.
3. Optionally store a manual learning
Reasoning runs can already extract learnings automatically. Use manual storage when you want direct editorial control, including structured entity/outcome evidence for a concrete observation.
curl -X POST "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings" \
-H "Authorization: Bearer <YOUR_HYPERSTRUCK_API_KEY>" \
-H "Content-Type: application/json" \
-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"
}
}
]
}'See Learnings API for the full instance evidence shape and storage rules.
4. Reuse the same capabilities from developer tooling
Once the API flow works, you can expose the same capabilities in developer tooling.
/hyper-reasoning Create a follow-up sales execution plan for a call with client XYZ
/hyper-learning search client XYZ decision makers
/hyper-learning storeCommon next knobs
- Agent creation optional fields:
description,status(defaults toactive),reasoning_profile(defaults tofull),home_space_id, and everything insidecore_config. - Goal dispatch optional fields:
context,session_id,worker_profile,metadata - Manual learning optional fields:
utility,source_goal,applicable_goals,applicable_tools,privacy,instances
Who pays for model calls
Hyperstruck does. There is no provider credential to upload and no model to choose: every reasoning component runs a model benchmarked for that component's job.