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

Submit a proposal

/api/v1/turnsPOST
Submits the original TurnProposal contract, not the managed executor envelope. A guardian ALLOW alone is insufficient; only a returned permit can authorize execution. IDs and effect fields in the example must be replaced with the current observation.
Examples are synthetic and illustrate response shape; IDs, signatures, and credentials are not usable authority.
Authorization
serviceBearer *Bearer <token>
Scoped restricted-service session minted by trusted runtime. Cannot be used on owner routes.
Request Bodyapplication/jsonrequired
goalRestatement *string
Min length: 1Max length: 4000
candidates *object[]
Min items: 1Max items: 12
Show item properties
id *string
Min length: 1
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: {}
purpose *string
Min length: 1
disposition *"proposed" | "rejected"
rejectionReason *stringnull
selectedCandidateId *string
justification *object
Show properties
summary *string
Min length: 1Max length: 8000
evidenceRefs *string[]
Max items: 30
expectedEffect *object
Show properties
operationId *string
transactionProposalId *stringnull
disclosedFields *string[]
postconditions *string[]
uncertainties *string[]
Max items: 20
Response
200 · Successful response. A paused run is an application outcome, not an HTTP error.
turnId *string
decision *object
Show properties
decision *"ALLOW" | "PAUSE" | "TERMINATE"
reasonCode *string
explanation *string
clarificationRequest?stringnull
Default: null
permit?object
Show properties
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
timing *object
Show properties
guardianMs *number
policyMs *number
hardMs *number
400 · Request validation failed.
error *string
reasonCode?string
403 · Exact service origin required.
error *string
reasonCode?string
500 · The local service could not complete this request.
error *string
reasonCode?string
Request example
curl -X POST "https://bank.example.com/api/v1/turns" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "goalRestatement": "Transfer $250.00 from operating-usd to the established beneficiary Cedar Studio, with a $3.00 fee. Do not read balances or transaction history.",
  "candidates": [
    {
      "id": "candidate-1",
      "action": {
        "kind": "service",
        "operationId": "bank.beneficiary",
        "args": {}
      },
      "purpose": "Verify beneficiary advances the approved bank workflow.",
      "disposition": "proposed",
      "rejectionReason": null
    }
  ],
  "selectedCandidateId": "candidate-1",
  "justification": {
    "summary": "Use verify beneficiary from the current scoped observation. Preserve the owner-approved terms and release only the action'\''s response fields.",
    "evidenceRefs": [
      "44444444-4444-4444-8444-444444444444"
    ]
  },
  "expectedEffect": {
    "operationId": "bank.beneficiary",
    "transactionProposalId": null,
    "disclosedFields": [
      "terms"
    ],
    "postconditions": [
      "Necessary task information disclosed"
    ]
  },
  "uncertainties": []
}'
Response example
{
  "turnId": "77777777-7777-4777-8777-777777777777",
  "decision": {
    "decision": "ALLOW",
    "reasonCode": "TASK_ALIGNED",
    "explanation": "The beneficiary read matches the approved task.",
    "clarificationRequest": null
  },
  "permit": {
    "id": "66666666-6666-4666-8666-666666666666",
    "runId": "11111111-1111-4111-8111-111111111111",
    "turnId": "77777777-7777-4777-8777-777777777777",
    "goalId": "33333333-3333-4333-8333-333333333333",
    "action": {
      "kind": "service",
      "operationId": "bank.beneficiary",
      "args": {}
    },
    "observationId": "44444444-4444-4444-8444-444444444444",
    "documentEpoch": 1,
    "stateRevision": 1,
    "operationId": "bank.beneficiary",
    "protectedOperationId": "bank.beneficiary",
    "expiresAt": "2026-10-26T12:00:30.000Z",
    "status": "issued",
    "grantId": "frozen-bank-grant",
    "transactionProposalId": null
  },
  "timing": {
    "guardianMs": 620,
    "policyMs": 5,
    "hardMs": 2
  }
}