Create Ontology Change (writeback)
Sandcastles
Create Ontology Change (Writeback)
Persist a sandcastle’s edits to /sandbox/files/library back to the org’s Ontology as a reviewable change.
POST
Create Ontology Change (writeback)
This is the writeback half of the Ontology. The library is mounted into
every sandcastle at
/sandbox/files/library, pruned to your OWNERS
permissions. Reads happen over the filesystem; writes back to canonical,
versioned org context happen here — as a reviewable change, not a silent commit.Workflow
1
2
(Optional) Preview the diff
Call Diff Ontology to confirm what
will be written back before authoring a change.
3
Create the change
POST /v2/sandcastles/:id/ontology/changes with a title and description.
The change is submitted OPEN for admin review (or DRAFT if you set
draft: true).4
Handle conflicts / iterate
If
has_conflicts is true the change stays RESERVED and the session’s
library/ is re-materialized with .rej markers. Resolve them and re-submit
with the same change_number to file a new changeset.Driving this from an agent loop
If you let an LLM decide when to write back, give the tool a description that teaches the stage-then-change workflow — otherwise models try to “save” before editing, or file empty changes. A description that mirrors the in-product tool works well:Authorizations
API key or JWT token
Path Parameters
Sandbox ID
Body
application/json
Short summary (≤50 chars). Required for a new change.
Maximum string length:
50Markdown explanation of the changes. Required for a new change.
File as DRAFT instead of OPEN (not yet ready for review).
Set to revise an existing change (creates a new changeset).
Response
Change created or updated
Change lifecycle state after submission.
Available options:
open, draft, approved, reserved Human-readable conflict view (present when has_conflicts).