---
title: "Record one agent decision observation, or adopt/reject a decision-engine recommendation. Append-only; never creates, resolves or signals an Action."
method: POST
path: "/decisions"
---

# Record one agent decision observation, or adopt/reject a decision-engine recommendation. Append-only; never creates, resolves or signals an Action.

`POST /decisions`

## Request

- Base URL: `https://forbiz.io/api/public/agent`
- URL: `https://forbiz.io/api/public/agent/decisions`
- Auth: HTTP bearer

Two shapes on one endpoint.

1) DECISION OBSERVATION (existing, unchanged): send decisionType + decisionSummary.

2) ENGINE DISPOSITION (v1.11.0): send disposition = ADOPTED | REJECTED | OVERRIDDEN | ACTED_ON together with the recommendation, stateFingerprint and engineVersion returned by GET /decisions/recommendation. This is the ONLY write path for the decision ledger: evaluating a recommendation never persists anything, and exactly one event is persisted per disposition. Retrying with the same Idempotency-Key replays the original event instead of creating a second one.

ATTRIBUTION (1.32.0): every credential class can write here, including a trial credential minted by POST /bootstrap. The event is attributed to the machine identity that presented the credential, and a storage failure answers 400 decision_not_recorded with a next step — never an internal constraint name.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `decisionType` 'act' | 'wait' | 'investigate' | 'ask' | 'ignore' | 'store' | 'follow_up' | 'do_not_send' | 'reconcile' | 'escalate' | 'other'
  - `subjectType` string: e.g. action, outreach, campaign_target, person, organization.
  - `subjectId` string
  - `decisionSummary` string: One short factual sentence.
  - `priorContextUsed` string: Which stored context mattered, in plain language.
  - `memoryEffect` string: How stored history changed the decision, if it did.
  - `actionIdsUsed` string[]
  - `outreachIdsUsed` string[]
  - `personIdsUsed` string[]
  - `organizationIdsUsed` string[]
  - `evidenceIdsUsed` string[]
  - `signalIdsUsed` string[]
  - `executionIdsUsed` string[]
  - `humanQuestionRequired` boolean
  - `humanQuestionText` string
  - `priorHistoryChangedDecision` boolean
  - `contradictionDetected` boolean
  - `staleStateDetected` boolean
  - `duplicateActionPrevented` boolean
  - `duplicateSendPrevented` boolean
  - `hardBounceReusePrevented` boolean
  - `activeConversationCollisionPrevented` boolean
  - `executionMismatchDetected` boolean
  - `unverifiedClaimBlocked` boolean
  - `affectedTargetCount` integer
  - `decisionConfidence` number
  - `disposition` 'ADOPTED' | 'REJECTED' | 'OVERRIDDEN' | 'ACTED_ON'
  - `recommendation` string
  - `stateFingerprint` string
  - `engineVersion` string
  - `projectId` string
  - `actionId` string
  - `rationale` string

## Response `201`

Decision recorded

- object
  - `ok` boolean
  - `decision_event_id` string

## Other responses

- `208`: Idempotent replay of a previous request with the same Idempotency-Key. Nothing was applied again.
- `400`: Validation error

---

[API](https://skmtc.dev/forbiz/apis/forbiz-external-agent-api.md) · [All operations](https://skmtc.dev/forbiz/apis/forbiz-external-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forbiz/apis/forbiz-external-agent-api/revisions/e5b10d59dc5f?raw)