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

Create a run

/api/v1/owner/runsPOST
Creates immutable task terms and initial authority, then initializes the selected adapter. Returns HTTP 200, including when initialization pauses the new run. Monetary values are decimal strings in cents. Only the default merchant/browser terms support target=hosted.
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/jsonrequired
guardianId?string (uuid)
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
instruction?string
Min length: 5Max length: 4000
service *"merchant" | "bank" | "broker"
target?"local" | "hosted"
Default: "local"
mode?"exact" | "bounded"
Default: "bounded"
channel?"browser" | "http" | "mcp" | "webmcp"
Default: "browser"
trafficActor?"agent" | "human"
executionMode?"replay" | "live"
Default: "replay"
executor?"openai" | "kimi" | "openrouter"
Default: "openai"
interrogator?"openai" | "kimi" | "openrouter"
Default: "openai"
reasoningEvidence?boolean
Default: false
budgetCents?string
Pattern: ^(0|[1-9]\d*)$Max length: 18
terms?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
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" \
  -H "x-halfspan-owner: 1" \
  -b "halfspan_session=<token>" \
  -H "Content-Type: application/json" \
  -d '{
  "service": "bank",
  "channel": "http",
  "mode": "bounded",
  "executionMode": "replay",
  "budgetCents": "25300"
}'
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": "active",
  "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": [
      {
        "id": "bank.beneficiary",
        "label": "Verify beneficiary",
        "operationId": "bank.beneficiary",
        "kind": "click",
        "targetRef": "frozen-bank:observation:bank.beneficiary",
        "args": {},
        "disclosedFields": [
          "terms"
        ],
        "postconditions": [
          "Necessary task information disclosed"
        ],
        "protected": true
      }
    ],
    "actionCatalog": [
      {
        "id": "bank.beneficiary",
        "label": "Verify beneficiary",
        "operationId": "bank.beneficiary",
        "kind": "click",
        "targetRef": "frozen-bank:observation:bank.beneficiary",
        "args": {},
        "disclosedFields": [
          "terms"
        ],
        "postconditions": [
          "Necessary task information disclosed"
        ],
        "protected": true
      }
    ],
    "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": null,
  "pendingPermit": null,
  "clarifications": [],
  "stopContext": null
}