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.
Provider credentials are optional
Hyperstruck can run agents with a platform-provided model credential. Upload your own provider credential only when you need a tenant default or agent-specific override.
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. If you omit provider and model fields, Hyperstruck intelligently uses the best-suited model by default.
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 defaults:
status="active",model_provider="openai",model_name="gpt-5.4-mini",reasoning_profile="full",memory_profile="default",knowledge_scope="agent" - Goal dispatch optional fields:
context,session_id,worker_profile,metadata - Manual learning optional fields:
utility,source_goal,applicable_goals,applicable_tools,privacy,instances
When to upload credentials
You usually do not need provider credentials for the first run because Hyperstruck provides a platform default. Upload credentials only when you want model billing, provider selection, or endpoint control under your own account.
Credential resolution is:
- A matching active
agent_overridecredential for the agent wins first. - If none exists, Hyperstruck uses a matching active
tenant_default. - If neither exists, Hyperstruck uses the platform default credential and intelligently selects the best-suited model.
Use Credentials API when you want to bring your own provider account.