Agents API

Create agents, dispatch goals, monitor runs, resume suspended work, and inspect session history.

Use the Agents API when you want Hyperstruck to run task-level reasoning for an agent.

Access control

Every endpoint requires an API key scope and matching object-level access on the agent or space. See Access control (FGA and RBAC) for the full permissions matrix.

Start with the minimum required fields

Keep the first request copy/paste-friendly. Full API reference lives in the OpenAPI docs. If you omit optional fields here, Hyperstruck uses sane defaults.

You do not pick a model

You can create and run an agent without uploading provider credentials, using a platform-provided one. There is no model field on an agent: every reasoning component runs a model benchmarked for that component's job, pinned, with no silent substitution if one is unavailable. Provider credentials change whose account is billed and which endpoint is called, not which model runs. See Credentials API.

Core lifecycle

List agents

No query params are required.

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

Prop

Type

Required scope: agents:read

Access: returns only agents in spaces you can view.

List spaces

GET /spaces lists spaces you can read. Use the returned UUIDs for home_space_id when creating agents or filtering the agent inventory.

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

Required scope: agents:read

Create an agent

Prop

Type

Unknown fields are rejected

Agent creation refuses any field it does not recognize rather than ignoring it, so a typo or a retired field fails loudly instead of silently doing nothing. The fields above, plus core_config, are the whole surface. For everything inside core_config, see Agent configuration.

description is useful when you want a clearer summary of the agent's role.

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/agents" \
  -d '{
    "name": "Operations Assistant",
    "description": "Helps coordinate internal operations workflows and follow-up tasks.",
    "core_config": {
      "instructions": "You are a helpful operations assistant."
    }
  }'

Prop

Type

core_config can be patched too, field by field; omitted keys are left unchanged. See Agent configuration for everything it holds, and treat that page as the reference for these fields rather than restating them here.

Required scope: agents:write

Access: requires publish permission on the target home space (defaults to commons when home_space_id is omitted).

Get an agent

GET /agents/{agent_id} returns the stored agent configuration. By default it includes an llm_credential summary for the effective runtime credential without exposing secrets.

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

Prop

Type

llm_credential.source can be customer_agent_override, customer_tenant_default, or platform_default.

Required scope: agents:read

Access: requires read permission on the agent.

Update an agent

PATCH /agents/{agent_id} accepts a partial update. Include at least one field.

curl -X PATCH \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>" \
  -d '{
    "reasoning_profile": "balanced",
    "core_config": {
      "instructions": "You are a helpful operations assistant. Prefer concise plans."
    }
  }'

Required scope: agents:write

Access: requires write permission on the agent.

Delete an agent

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

Required scope: agents:write

Access: requires write permission on the agent.

Dispatch a goal

POST /agents/{agent_id}/goals returns 202 Accepted with a run handle. The only required body field is goal.

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/goals" \
  -d '{
    "goal": "Map out a migration plan with milestones and risks"
  }'

Prop

Type

Required scope: agents:execute

Access: requires execute permission on the agent. Keys with only agents:write also qualify because agents:write implies agents:execute.

Ground the answer in a source of truth

Three kinds of text reach a run and are treated very differently:

goal and context steer what to do. They are never evidence: an answer that merely restates the goal is not grounded.
sources are the material the answer must be faithful to. Only sources (and the agent's own tool reads) count as evidence.
references calibrate tone or format and are never treated as fact.

So to ground the answer in your own data, a meeting transcript or a record set, pass that data as sources, not context. Declaring any sources (or references) also switches on the faithfulness check: a claim the sources do not support is refused rather than confidently invented.

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/goals" \
  -d '{
    "goal": "Summarize the decisions and open actions from this meeting",
    "sources": [
      { "text": "<meeting transcript>", "label": "transcript" }
    ]
  }'

Each sources item is a source-of-truth block:

Prop

Type

Each references item is exemplar/calibration material with the same text (required, 100,000-character cap) and optional label, but no id. You may pass up to 25 sources and 25 references per run.

When the answer can't be grounded

If the agent cannot ground its answer in the sources, the run is refused rather than faked. It terminates with status: failed, and the run detail's output carries a plain-language explanation of what could not be supported. The top-level error is a generic message, so read output for the reason.

A grounding refusal currently shares the failed status with a genuine execution error. To tell them apart, inspect the run detail output: a refusal explains which claim was unsupported, whereas an execution error does not.

Poll run status

No body or query params are required.

Completed runs can produce or inspire evidence-backed learnings, but RunResponse does not return learning instances. Use the Learnings API to inspect stored instance evidence.

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

Required scope: agents:read

Access: resolves the run to its agent and requires read permission.

Resume a suspended run

Prop

Type

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://api.hyperstruck.com/runs/<RUN_ID>/resume" \
  -d '{
    "suspension_id": "<SUSPENSION_ID>",
    "decision_type": "approve"
  }'

Required scope: agents:execute

Access: resolves the run to its agent and requires execute permission.

Inspect session messages

No query params are required.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/sessions/<SESSION_ID>/messages"

Prop

Type

Required scope: agents:read

Inspect session runs

No query params are required.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/sessions/<SESSION_ID>/runs"

Prop

Type

Required scope: agents:read

List agent runs

GET /agents/{agent_id}/runs returns runs for one agent. No query params are required.

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

Prop

Type

Required scope: agents:read

List agent sessions

GET /agents/{agent_id}/sessions returns sessions for one agent.

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

Prop

Type

Required scope: agents:read

List definition suggestions

GET /agents/definition-suggestions returns curated starting values for authoring an agent definition, so a caller building one has something discoverable to choose from rather than a blank field.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/definition-suggestions?kind=template"

kind selects the catalog: template, reasoning_profile, mcp_server, guardrail, or code_example. It defaults to template. A kind with no curated content answers with an empty list rather than an error, and some kinds are empty today, so drive a picker off the response rather than off the list of kinds. q filters case-insensitively over label and description. Each item carries id, kind, label, description, and a payload you can lift into the create or update call. Required scope: agents:read.

Access control (FGA and RBAC) for scopes, spaces, and the permissions matrix
Quickstart for the fastest first-success flow
Credentials API for optional tenant defaults and agent overrides
Plans API for directly searching prior workflows when you need inspection or routing
Reasoning for the conceptual overview
Claude Skills for using the same capability in developer tooling

On this page