Mandates

Ask the person to change a running plan's settings

Changed on

0.236.0, grantee only. {strategy: {explore?, goal_kind?, pace?}, reason} on an ACTIVE strategy mandate; only those three keys, validated like the owner's tune (422 strategy_not_editable for any other key, invalid_strategy for a bad value, no_change when they already hold, invalid_reason when reason is empty or over 300 characters). NOTHING changes until the grantor accepts. One pending request per mandate: a newer one replaces it only after 10 minutes (429 too_soon before that; 429 too_many_today past 5 a day) and, replacing, does not notify again. Any version or status change of the plan clears a pending request. The grantor gets the Activity row strategy_tune_requested (agents, important) and the mandates live topic fires; the request rides on the mandate as tune_request {id, changes, reason, at}. A key the person locked ("Keep this plan as is") is 422 plan_locked ("You asked to keep this plan as is.", locked). A self-approved plan has no one to ask: 422 self_approved (use PATCH /mandates/{id}). Not the grantee: 404.

post/api/v1/mandates/{id}/tune_requests

Request

  • Base URL: https://saltapp.ai
  • URL: https://saltapp.ai/api/v1/mandates/{id}/tune_requests
  • Auth: API key in header api-key

Path parameters

idstring required

Request body

reasonstring required

Response

OK

idstring uuid required
kind'explicit' | 'governance' | 'connection' required
status'proposed' | 'active' | 'paused' | 'revoked' | 'expired' | 'withdrawn' required

withdrawn (0.240.0): an unanswered proposal that a newer plan for the same goal replaced; nothing was granted. withdrawn_reason says why.

labelstring nullable
starts_atstring date-time nullable
expires_atstring date-time nullable
standingboolean
grantee_fingerprintstring nullable
key_changedboolean
parent_idstring nullable
depthinteger
versioninteger required
chat_idstring nullable
reasonstring nullable

The asking agent's own words (at most 1000 characters). Data, never Salt's sentence.

estimated_costobject nullable

A budget ask: {amount (decimal string), currency, period (daily|weekly|monthly)?, chain?}.

approved_by'self' | 'null' nullable

0.236.0: self when a ROOT agent approved its own plan (grantor == grantee, no card); null otherwise.

locksstring[]

0.243.0, "Keep this plan as is": the keys of a running plan the grantor locked against the agent's own tuning (all locks every tunable key). Set by the grantor with PATCH locks. Empty when nothing is locked.

plan_idstring nullable

0.240.0: the plan this grant was asked for (set with plan_id on the proposal); stopping or expiring the plan ends the grant too.

approve_firstobject[]

0.240.0: for each public-post / public-room / first-message row of this grant, {capability, mode, approved, needed}: the asks the person has approved so far and how many it takes (3) before the agent may ask to be told instead of asked.

withdrawn_reasonstring nullable

0.240.0: "Replaced by a newer plan" when status is withdrawn, else null.

resume_tokenstring nullable

Opaque (at most 200 characters), supplied by the asking agent and echoed on every mandate event so it resumes the exact parked step.

client_idstring nullable
client_namestring nullable
proposed_by_idstring nullable
accepted_atstring date-time nullable
paused_atstring date-time nullable
pause_reasonstring nullable
revoked_atstring date-time nullable
revoke_reasonstring nullable
childrenobject[]
trailobject

Changes

  • 323df4224efaRevision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status