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.

Platform model defaults are available

You can create and run an agent without uploading provider credentials. By default, Hyperstruck intelligently uses the best-suited model with a platform-provided credential.

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.

Create an agent

Prop

Type

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

Other core_config fields are optional.

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 admin 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": "Summarise 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

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

Core lifecycle

List agents

List spaces

Create an agent

Get an agent

Update an agent

Delete an agent

Dispatch a goal

Ground the answer in a source of truth

When the answer can't be grounded

Poll run status

Resume a suspended run

Inspect session messages

Inspect session runs

List agent runs

List agent sessions

On this page