Act on the desk’s suggestions
How the desk works for you: detectors watch your own data and draft plans — low stock worth ordering, reviews waiting too long, stock worth moving. You only ever see what your own permissions could run; taking one opens a scratchpad you approve and realize yourself.
Work · a guided walk in 3 steps.
The steps
- Check the desk — The check runs every active detector now — new findings become offers, each with its why and a drafted plan. — refreshSuggestions
- Take what you agree with — Taking mints a scratchpad from the drafted plan — reviewed and realized under your own permissions, like any other. — takeSuggestion, transitionScratchpad, realizeScratchpad
- Decline what you won’t do — A decline is a learning signal — the desk stops re-offering that finding while your reason stands. — declineSuggestion
The calls
Every operation this use case runs, in the order it first appears, with the request and the response its reference page shows.
refreshSuggestions
refreshSuggestions — mutation · Ask the suggestions desk to look now — it runs every active detector for one organization and refreshes the offers.
Example request
mutation ExampleRefreshSuggestions($organizationId: ID!) {
refreshSuggestions(organizationId: $organizationId) {
minted
superseded
expired
skippedDuplicate
skippedDeclined
skippedTaken
skippedCapped
schemasEnsured
doomedHeld
parkedSkills
}
}Variables:
{
"organizationId": "01900000-0000-7000-8000-44b781470000"
}Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.
Example response
{
"data": {
"refreshSuggestions": {
"minted": 1,
"superseded": 1,
"expired": 1,
"skippedDuplicate": 1,
"skippedDeclined": 1,
"skippedTaken": 1,
"skippedCapped": 1,
"schemasEnsured": 1,
"doomedHeld": 1,
"parkedSkills": 1
}
},
"extensions": {
"at": {
"callId": "01EXAMPLE-CALL-ID",
"version": {
"requested": {
"name": "genesis",
"number": 0
},
"serviced": {
"name": "genesis",
"number": 0
}
}
}
}
}takeSuggestion
takeSuggestion — mutation · Take a suggestion — a scratchpad is created with its drafted plan, ready for your review and approval.
Example request
mutation ExampleTakeSuggestion($input: TakeSuggestionInput!) {
takeSuggestion(input: $input) {
id
sysId
type
caption
status
parentId
rootId
createdAt
updatedAt
revisionNum
revision
origin
intent
planRevision
approvedPlanRevision
inFlightSeq
realizationFault
}
}Variables:
{
"input": {
"id": "01900000-0000-7000-8000-37386ae00000",
"revision": "01900000-0000-7000-8000-b7960e180000",
"reason": "Correcting a miscount."
}
}Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.
Example response
{
"data": {
"takeSuggestion": {
"id": "01900000-0000-7000-8000-37386ae00000",
"sysId": "SD-EXMP-0000-000F",
"type": "Scratchpad",
"caption": "Blue jeans",
"status": "draft",
"parentId": "01900000-0000-7000-8000-065235280000",
"rootId": "01900000-0000-7000-8000-a093dd800000",
"createdAt": "2027-01-31T00:00:00.000Z",
"updatedAt": "2027-01-31T00:00:00.000Z",
"revisionNum": 1,
"revision": "01900000-0000-7000-8000-b7960e180000",
"origin": "<origin>",
"intent": "<intent>",
"planRevision": 1,
"approvedPlanRevision": 1,
"inFlightSeq": 1,
"realizationFault": "<realization fault>"
}
},
"extensions": {
"at": {
"callId": "01EXAMPLE-CALL-ID",
"version": {
"requested": {
"name": "genesis",
"number": 0
},
"serviced": {
"name": "genesis",
"number": 0
}
}
}
}
}transitionScratchpad
transitionScratchpad — mutation · Move a scratchpad through its life — hold the plan for review, reopen it for editing, approve it, or abandon it.
Example request
mutation ExampleTransitionScratchpad($id: ID!, $revision: ID!, $op: ScratchpadTransitionOp!, $reason: String) {
transitionScratchpad(id: $id, revision: $revision, op: $op, reason: $reason) {
id
sysId
type
caption
status
parentId
rootId
createdAt
updatedAt
revisionNum
revision
origin
intent
planRevision
approvedPlanRevision
inFlightSeq
realizationFault
}
}Variables:
{
"id": "01900000-0000-7000-8000-37386ae00000",
"revision": "01900000-0000-7000-8000-b7960e180000",
"op": "ready",
"reason": "Correcting a miscount."
}Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.
Example response
{
"data": {
"transitionScratchpad": {
"id": "01900000-0000-7000-8000-37386ae00000",
"sysId": "SD-EXMP-0000-000F",
"type": "Scratchpad",
"caption": "Blue jeans",
"status": "draft",
"parentId": "01900000-0000-7000-8000-065235280000",
"rootId": "01900000-0000-7000-8000-a093dd800000",
"createdAt": "2027-01-31T00:00:00.000Z",
"updatedAt": "2027-01-31T00:00:00.000Z",
"revisionNum": 1,
"revision": "01900000-0000-7000-8000-b7960e180000",
"origin": "<origin>",
"intent": "<intent>",
"planRevision": 1,
"approvedPlanRevision": 1,
"inFlightSeq": 1,
"realizationFault": "<realization fault>"
}
},
"extensions": {
"at": {
"callId": "01EXAMPLE-CALL-ID",
"version": {
"requested": {
"name": "genesis",
"number": 0
},
"serviced": {
"name": "genesis",
"number": 0
}
}
}
}
}realizeScratchpad
realizeScratchpad — mutation · Execute an approved plan — create its records one step at a time under YOUR OWN permissions.
Example request
mutation ExampleRealizeScratchpad($id: ID!, $revision: ID!, $reason: String) {
realizeScratchpad(id: $id, revision: $revision, reason: $reason) {
id
sysId
type
caption
status
parentId
rootId
createdAt
updatedAt
revisionNum
revision
origin
intent
planRevision
approvedPlanRevision
inFlightSeq
realizationFault
}
}Variables:
{
"id": "01900000-0000-7000-8000-37386ae00000",
"revision": "01900000-0000-7000-8000-b7960e180000",
"reason": "Correcting a miscount."
}Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.
Example response
{
"data": {
"realizeScratchpad": {
"id": "01900000-0000-7000-8000-37386ae00000",
"sysId": "SD-EXMP-0000-000F",
"type": "Scratchpad",
"caption": "Blue jeans",
"status": "draft",
"parentId": "01900000-0000-7000-8000-065235280000",
"rootId": "01900000-0000-7000-8000-a093dd800000",
"createdAt": "2027-01-31T00:00:00.000Z",
"updatedAt": "2027-01-31T00:00:00.000Z",
"revisionNum": 1,
"revision": "01900000-0000-7000-8000-b7960e180000",
"origin": "<origin>",
"intent": "<intent>",
"planRevision": 1,
"approvedPlanRevision": 1,
"inFlightSeq": 1,
"realizationFault": "<realization fault>"
}
},
"extensions": {
"at": {
"callId": "01EXAMPLE-CALL-ID",
"version": {
"requested": {
"name": "genesis",
"number": 0
},
"serviced": {
"name": "genesis",
"number": 0
}
}
}
}
}declineSuggestion
declineSuggestion — mutation · Decline a suggestion — say why, and the desk keeps your reason so it learns.
Example request
mutation ExampleDeclineSuggestion($id: ID!, $revision: ID!, $reason: String!) {
declineSuggestion(id: $id, revision: $revision, reason: $reason) {
id
sysId
type
caption
status
parentId
rootId
createdAt
updatedAt
revisionNum
revision
skill
schemaId
why
dedupKey
expiresAt
takenScratchpadId
declineReason
}
}Variables:
{
"id": "01900000-0000-7000-8000-37386ae00000",
"revision": "01900000-0000-7000-8000-b7960e180000",
"reason": "Correcting a miscount."
}Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.
Example response
{
"data": {
"declineSuggestion": {
"id": "01900000-0000-7000-8000-37386ae00000",
"sysId": "SU-EXMP-0000-000F",
"type": "Suggestion",
"caption": "Blue jeans",
"status": "open",
"parentId": "01900000-0000-7000-8000-065235280000",
"rootId": "01900000-0000-7000-8000-a093dd800000",
"createdAt": "2027-01-31T00:00:00.000Z",
"updatedAt": "2027-01-31T00:00:00.000Z",
"revisionNum": 1,
"revision": "01900000-0000-7000-8000-b7960e180000",
"skill": "<skill>",
"schemaId": "01900000-0000-7000-8000-e5ee57ab0000",
"why": "<why>",
"dedupKey": "<dedup key>",
"expiresAt": "2027-01-31T00:00:00.000Z",
"takenScratchpadId": "01900000-0000-7000-8000-65ec6b4e0000",
"declineReason": "<decline reason>"
}
},
"extensions": {
"at": {
"callId": "01EXAMPLE-CALL-ID",
"version": {
"requested": {
"name": "genesis",
"number": 0
},
"serviced": {
"name": "genesis",
"number": 0
}
}
}
}
}