Skip to main content
POST
/
v2
/
sandcastles
/
{id}
/
library
/
patches
Create Library Patch (writeback)
curl --request POST \
  --url https://app.textql.com/v2/sandcastles/{id}/library/patches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "description": "<string>",
  "draft": false,
  "patch_number": 123
}
'
{
  "patch_id": "<string>",
  "patch_number": 123,
  "git_ref": "<string>",
  "has_conflicts": true,
  "conflicts": "<string>",
  "auto_approved": true,
  "diffs": [
    {
      "name": "<string>",
      "old_path": "<string>",
      "new_path": "<string>",
      "additions": 123,
      "deletions": 123,
      "is_new": true,
      "is_delete": true,
      "is_rename": true,
      "is_binary": true
    }
  ],
  "raw_diff": "<string>"
}
This is the writeback half of the Context Library. 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 patch, not a silent commit.

​
Workflow

1

Stage your changes

Edit files under /sandbox/files/library using Exec or Upload. A patch can only be created from real, staged file changes.
2

(Optional) Preview the diff

Call Diff Library to confirm what will be written back before authoring a patch.
3

Create the patch

POST /v2/sandcastles/:id/library/patches with a title and description. The patch is submitted OPEN for admin review (or DRAFT if you set draft: true).
4

Handle conflicts / iterate

If has_conflicts is true the patch stays RESERVED and the session’s library/ is re-materialized with .rej markers. Resolve them and re-submit with the same patch_number to file a new patchset.

​
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-patch workflow — otherwise models try to “save” before editing, or file empty patches. A description that mirrors the in-product tool works well: 
Writeback your changes under /sandbox/files/library to the organization's
Context Library by creating or updating a patch. Patches are the only way to
persist library changes; they are submitted for admin review.

Edit the files first and make sure all changes are written to the local
library/ directory — only then create a patch (creating one with no changes
fails). Write a descriptive title (<=50 chars) and a Markdown description.

To revise an existing patch, pass its patch_number (this creates a new
patchset). If the response reports merge conflicts, resolve the .rej files and
re-submit with the same patch_number. Do not create .bak backup files in the
library before patching.
Permissions are enforced twice: the mount you edited was already pruned to your OWNERS access, and every changed path is re-validated at merge — a patch can never widen access. If an auto-approve rule matches, status comes back approved and the change is already live.

Authorizations

​
Authorization
string
header
required

API key or JWT token

Path Parameters

​
id
string
required

Sandbox ID

Body

application/json
​
title
string

Short summary (≤50 chars). Required for a new patch.

Maximum string length: 50
​
description
string

Markdown explanation of the changes. Required for a new patch.

​
draft
boolean
default:false

File as DRAFT instead of OPEN (not yet ready for review).

​
patch_number
integer<int32>

Set to revise an existing patch (creates a new patchset).

Response

Patch created or updated

​
patch_id
string
​
patch_number
integer<int32>
​
status
enum<string>

Patch lifecycle state after submission.

Available options:
open,
draft,
approved,
reserved
​
git_ref
string
​
has_conflicts
boolean
​
conflicts
string

Human-readable conflict view (present when has_conflicts).

​
auto_approved
boolean
​
diffs
object[]
​
raw_diff
string