Accept Suggestions

post/extensions/roboledger/{graph_id}/operations/accept-suggestions

Take the suggestion on every open bank line the filters select, oldest first: each is classified to its suggested_element_id through the same update a single line goes through, and posted too with commit: true. Select by source, agent_id, suggestion_source (agent_default for the learned ones), a date range, or explicit event_ids from a multi-select. A line it cannot take — no suggestion to take, already classified or posted, a closed month, a choice the handler refuses — comes back skipped with the reason, never forced. dry_run: true reports the counts without writing; limit bounds a call and truncated says more matched.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id Constraints: matches `^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?\|sec(?:_[a-zA-Z0-9]{1,20})?\|library)$`

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field	Type	Description
`entity_id`optional	string	The entity whose inbox to act on. Omit for the group parent.
`event_ids`optional	string[]	Explicit lines, as from the inbox's multi-select; each is answered, even one that cannot be taken. The other filters still narrow them.
`source`optional	string	Only lines from this feed (`plaid`, `mercury`).
`agent_id`optional	string	Only one counterparty's lines.
`suggestion_source`optional	string	Only lines whose suggestion came from here: `agent_default` (the counterparty's learned default), `tier0` (the bank's category) or `ai`.
`occurred_from`optional	string (date)	Only lines dated on or after this day.
`occurred_to`optional	string (date)	Only lines dated on or before this day.
`commit`optional	boolean	Post each taken line as well (captured → committed). Off, the lines are classified and wait for a person to post them. Default: `false`
`limit`optional	integer	At most this many lines per call, oldest first; `truncated` in the response says whether more matched. Default: `200` Constraints: 1–1000
`dry_run`optional	boolean	Report what each line would do without writing. A closed month is found only when a line actually posts, so a real run can still skip one a dry run counted. Default: `false`

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/accept-suggestions" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "entity_id": "string",
  "event_ids": [
    "string"
  ],
  "source": "string",
  "agent_id": "string",
  "suggestion_source": "string",
  "occurred_from": "2026-01-31",
  "occurred_to": "2026-01-31",
  "commit": false,
  "limit": 200,
  "dry_run": false
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

AcceptSuggestionsResponse

Command-specific result payload

AcceptSuggestionsResponse fields

Field Type Description

selectedrequired

integer

Lines the filters matched, before the limit.

classifiedrequired

integer

Lines classified to their suggestion and left to post.

committedrequired

integer

Lines classified to their suggestion and posted.

skippedrequired

integer

Lines not taken, each with a reason.

truncatedrequired

boolean

More lines matched than the limit allowed in this call.

dry_runrequired

boolean

Nothing was written.

linesrequired

AcceptSuggestionLine[]

Each line looked at, oldest first.

AcceptSuggestionLine fields

Field	Type	Description
`event_id`required	string	The line.
`outcome`required	string	What happened to it. One of: `classified`, `committed`, `skipped`
`reason`optional	string	Why a skipped line was not taken: `not_open` (already classified, posted or retracted), `no_suggestion` (nothing to take, or a name that matches no account), `source_changed` (the feed changed it after capture), `closed_period`, `locked` (another process holds it; retry), or `refused` (the handler would not post the choice).
`detail`optional	string	The refusal's own words, when there was one.
`element_id`optional	string	The account the suggestion names.
`description`optional	string	The line's description.

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error