Agent routes: teach, upgrade

Reference for Agent, one group of Agent routes.

Agent.teach

Teach adds a rule to a Customer’s own minted Agent that binds only that Customer’s Tenant. Verb page.

Text

POST /{namespace}/agents/{agent}/teach

Path: agent. Body, as JSON: the other inputs. Emits Agent.taught.

Inputs

Input	Type	Required	Description
`agent`	Agent	required	The minted Agent.
`rule`	`text`	required	The rule, in plain words.
`case`	`text`	required	A case the rule must pass, kept with the Tenant’s cases.

Returns

Output	Type	Required	Description
`agent`	Agent	required	The Agent with the rule.

Refuses when

Check	Error	Fix	Then call
The key is valid, but its scopes do not allow this operation	`forbidden`	Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them.	None.
A rule that would widen what the product’s Role contract allows	`refused`	Clear what the check names, then call it again.	None.
`agent` is missing, or is not a agent	`invalid-input`	Send `agent` as a agent, then call it again.	None.
`rule` is missing, or is not a text	`invalid-input`	Send `rule` as a text, then call it again.	None.
`case` is missing, or is not a text	`invalid-input`	Send `case` as a text, then call it again.	None.
The `Idempotency-Key` was sent before with another operation or other input	`idempotency-mismatch`	Send a new key for new input; reuse a key only to retry the same request.	None.

Example

Terminal

curl -X POST https://api.sb/leaseline.app/agents/agent_tCzKDMorKn/teach \
  -H "Authorization: Bearer $SB_TOKEN" \
  -H "Idempotency-Key: leaseline-agent-teach-1" \
  -H "Content-Type: application/json" \
  -d '{"rule":"Example rule","case":"Example case"}'

JSON

{
  "api": "https://api.sb/leaseline.app",
  "agent": {
    "$id": "https://api.sb/leaseline.app/agents/agent_tCzKDMorKn",
    "$type": "Agent",
    "instructions": "Write as the property manager’s assistant. Never promise a rent the manager has not set.",
    "model": "claude-opus-5-5",
    "status": "seated"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Agent.teach",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

Agent.upgrade

Upgrade moves a Customer’s minted Agent to a new Version once every case in its Tenant passes on that Version. Verb page.