Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Advance one step

/api/v1/owner/runs/{id}/stepPOST
Runs at most one managed executor outcome. A proposal proceeds through hard checks and guardian review before a permit can execute. Refusal or clarification returns a paused RunView with HTTP 200; it is not an HTTP error.
Examples are synthetic and illustrate response shape; IDs, signatures, and credentials are not usable authority.
Authorization
ownerSession *cookie halfspan_session
Authenticated HttpOnly owner session. Not an executor credential.
Request Bodyapplication/json
Type: object
Response
200 · Successful response. A paused run is an application outcome, not an HTTP error.
guardianBinding?object | null
Show options
Any of:
Option 1
guardianId *string
guardianName *string
serviceId *string
environment *"demo" | "staging" | "production"
policyVersion *integer
Min: -9007199254740991Max: 9007199254740991
policy *object
Show properties
name *string
Min length: 2Max length: 100
serviceId?string | null
Default: null
environment?"demo" | "staging" | "production"
Default: "demo"
channels?"browser" | "http" | "mcp" | "webmcp"[]
Default: []Max items: 4
operations?string[]
Default: []Max items: 30
mode?"exact" | "bounded"
Default: "exact"
budgetCents?string
Default: "13700"Pattern: ^(0|[1-9]\d*)$Max length: 18
instructions?string
Default: ""Max length: 4000
provider?"openai" | "kimi" | "openrouter"
Default: "openai"
Option 2
Type: null
stopContext?object | null
Show options
Any of:
Option 1
version *1
category *"refusal" | "clarification" | "authorization" | "policy" | "capability" | "provider" | "invalid_output" | "execution" | "limit" | "unknown"
source *"executor" | "guardian" | "provider" | "deterministic-policy" | "runtime"
reasonCode *string
message *string
recovery *"clarify" | "approve" | "retry" | "configure" | "review_external" | "new_run" | "none"
attemptId *string
observationId *stringnull
dispatch *"not_dispatched" | "confirmed" | "unconfirmed" | "unknown"
Option 2
Type: null
target?"local" | "hosted"
id *string
goalId *string
instruction *string
service *"merchant" | "bank" | "broker"
mode *"exact" | "bounded"
channel *"browser" | "http" | "mcp" | "webmcp"
executionMode *"replay" | "live"
executor *"openai" | "kimi" | "openrouter"
interrogator *"openai" | "kimi" | "openrouter"
reasoningEvidence *boolean
status *"active" | "paused" | "terminated" | "completed"
stage *string
terms *object
createdAt *string
updatedAt *string
modelCalls *number
observation *object
Show properties
id *string
origin *string
documentEpoch *number
stateRevision *number
runId *string
stage *string
data *object
targets *object[]
Show item properties
id *string
label *string
operationId *string
kind *"navigate" | "observe" | "click" | "fill" | "select" | "service"
targetRef *string
args *object
disclosedFields *string[]
postconditions *string[]
protected *boolean
value?string
url?string
actionCatalog *object[]
Show item properties
id *string
label *string
operationId *string
kind *"navigate" | "observe" | "click" | "fill" | "select" | "service"
targetRef *string
args *object
disclosedFields *string[]
postconditions *string[]
protected *boolean
value?string
url?string
createdAt *string
grants *object[]
Show item properties
id *string
phase *"preparation" | "execution"
service *"merchant" | "bank" | "broker"
mode *"exact" | "bounded"
terms *object
budgetCents *string
Pattern: ^(0|[1-9]\d*)$Max length: 18
consumedCents *string
Pattern: ^(0|[1-9]\d*)$Max length: 18
reservedCents *string
Pattern: ^(0|[1-9]\d*)$Max length: 18
operationCount *number
maxOperations *number
expiresAt *string
revoked *boolean
allowedOperations *string[]
disclosedFields *string[]
proposalId *stringnull
transactionProposal *object | null
Show options
Any of:
Option 1
id *string
service *"merchant" | "bank" | "broker"
terms *object
totalCents *string
Pattern: ^(0|[1-9]\d*)$Max length: 18
stateRevision *number
expiresAt *string
approved *boolean
Option 2
Type: null
executions *object[]
Show item properties
id *string
proposalId *string
grantId *string
service *"merchant" | "bank" | "broker"
terms *object
status *string
reservedCents *string
Pattern: ^(0|[1-9]\d*)$Max length: 18
consumedCents *string
Pattern: ^(0|[1-9]\d*)$Max length: 18
filledUnits *number
cancellationRequested *boolean
createdAt *string
timeline *object[]
Show item properties
id *string
sequence *number
type *string
data *object
createdAt *string
hash *string
previousHash *stringnull
signature *string
lastDecision *object | null
Show options
Any of:
Option 1
decision *"ALLOW" | "PAUSE" | "TERMINATE"
reasonCode *string
explanation *string
clarificationRequest?stringnull
Default: null
Option 2
Type: null
pendingPermit *object | null
Show options
Any of:
Option 1
id *string
runId *string
turnId *string
goalId *string
action *object
Show properties
kind *"navigate" | "observe" | "click" | "fill" | "select" | "service"
operationId *string
Min length: 1Max length: 100
targetRef?string
Max length: 200
url?string
Max length: 500
value?string
Max length: 1000
args?object
Default: {}
observationId *string
documentEpoch *number
stateRevision *number
operationId *string
protectedOperationId *stringnull
expiresAt *string
status *"issued" | "claimed" | "consumed" | "revoked"
grantId *string
transactionProposalId *stringnull
Option 2
Type: null
clarifications *string[]
400 · Request validation failed.
error *string
reasonCode?string
401 · Sign in to the Halfspan workspace.
error *string
reasonCode?string
403 · Console requests must come from the local owner workspace.
error *string
reasonCode?string
404 · Run not found
error *string
reasonCode?string
500 · The local service could not complete this request.
error *string
reasonCode?string
Request example
curl -X POST "https://service.example.com/api/v1/owner/runs/11111111-1111-4111-8111-111111111111/step" \
  -H "x-halfspan-owner: 1" \
  -b "halfspan_session=<token>" \
  -H "Content-Type: application/json" \
  -d '{}'
Response example
{
  "id": "11111111-1111-4111-8111-111111111111",
  "goalId": "33333333-3333-4333-8333-333333333333",
  "instruction": "Transfer $250.00 from operating-usd to the established beneficiary Cedar Studio, with a $3.00 fee. Do not read balances or transaction history.",
  "service": "bank",
  "mode": "bounded",
  "channel": "http",
  "executionMode": "replay",
  "executor": "openai",
  "interrogator": "openai",
  "reasoningEvidence": false,
  "status": "paused",
  "stage": "initial",
  "terms": {
    "source": "operating-usd",
    "beneficiary": "beneficiary-cedar",
    "beneficiaryName": "Cedar Studio",
    "principalCents": "25000",
    "feeCents": "300",
    "currency": "USD"
  },
  "createdAt": "2026-10-26T12:00:00.000Z",
  "updatedAt": "2026-10-26T12:00:00.000Z",
  "modelCalls": 0,
  "observation": {
    "id": "44444444-4444-4444-8444-444444444444",
    "origin": "http://127.0.0.1:4302",
    "documentEpoch": 1,
    "stateRevision": 1,
    "runId": "11111111-1111-4111-8111-111111111111",
    "stage": "initial",
    "data": {},
    "targets": [],
    "actionCatalog": [],
    "createdAt": "2026-10-26T12:00:00.000Z"
  },
  "grants": [
    {
      "id": "frozen-bank-grant",
      "phase": "execution",
      "service": "bank",
      "mode": "bounded",
      "terms": {
        "source": "operating-usd",
        "beneficiary": "beneficiary-cedar",
        "beneficiaryName": "Cedar Studio",
        "principalCents": "25000",
        "feeCents": "300",
        "currency": "USD"
      },
      "budgetCents": "25300",
      "consumedCents": "0",
      "reservedCents": "0",
      "operationCount": 0,
      "maxOperations": 12,
      "expiresAt": "2026-10-26T12:15:00.000Z",
      "revoked": false,
      "allowedOperations": [
        "bank.beneficiary",
        "bank.prepare",
        "bank.transfer",
        "bank.status",
        "bank.cancel"
      ],
      "disclosedFields": [
        "terms",
        "proposalId",
        "totalCents",
        "expiresAt",
        "executionId",
        "status",
        "filledUnits",
        "cancellationRequested"
      ],
      "proposalId": null
    }
  ],
  "transactionProposal": null,
  "executions": [],
  "timeline": [],
  "lastDecision": {
    "decision": "PAUSE",
    "reasonCode": "EXECUTOR_REFUSAL",
    "explanation": "I cannot assist with an unauthorized transfer.",
    "clarificationRequest": null
  },
  "pendingPermit": null,
  "clarifications": [],
  "stopContext": {
    "version": 1,
    "category": "refusal",
    "recovery": "clarify",
    "source": "executor",
    "reasonCode": "EXECUTOR_REFUSAL",
    "message": "I cannot assist with an unauthorized transfer.",
    "attemptId": "55555555-5555-4555-8555-555555555555",
    "observationId": "44444444-4444-4444-8444-444444444444",
    "dispatch": "not_dispatched"
  }
}