> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Ontology Change (Writeback)
> Persist a sandcastle's edits to /sandbox/files/library back to the org's Ontology as a reviewable change.
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
Edit files under `/sandbox/files/library` using
[Exec](/api-reference/v2/sandbox/execute-code) or
[Upload](/api-reference/v2/sandbox/upload-file). A change can only be created
from real, staged file changes.
Call [Diff Ontology](/api-reference/v2/sandbox/diff-ontology) to confirm what
will be written back before authoring a 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`).
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:
```text theme={null}
Writeback your changes under /sandbox/files/library to the organization's
Ontology by creating or updating a change. Changes 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 change (creating one with no changes
fails). Write a descriptive title (<=50 chars) and a Markdown description.
To revise an existing change, pass its change_number (this creates a new
changeset). If the response reports merge conflicts, resolve the .rej files and
re-submit with the same change_number. Do not create .bak backup files in the
library before creating a change.
```
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 change can
never widen access. If an auto-approve rule matches, `status` comes back
`approved` and the change is already live.
## OpenAPI
````yaml POST /v2/sandcastles/{id}/ontology/changes
openapi: 3.1.0
info:
title: TextQL v2 API
version: '2.0'
description: >
REST API for TextQL platform operations. All endpoints require Bearer token
authentication.
servers:
- url: https://app.textql.com
security:
- bearerAuth: []
tags:
- name: Chat
description: Create and manage AI chat sessions
- name: Connectors
description: List available data connectors
- name: Playbooks
description: Create, configure, and run automated playbooks
- name: Sandcastles
description: Manage Python sandbox environments for code execution
- name: Changes
description: Review, approve, and deny Ontology changes
- name: API Keys
description: Mint and revoke scoped platform API keys
paths:
/v2/sandcastles/{id}/ontology/changes:
post:
tags:
- Sandcastles
summary: Create Ontology Change (writeback)
description: >
Persist the sandbox's edits to `/sandbox/files/library` back to the
organization's **Ontology** by authoring a reviewable change. This
is the API equivalent of the in-product writeback tool: it diffs the
session library against its baseline snapshot, commits the delta to a
change ref, detects merge conflicts, and submits the change for review.
**Stage first.** A change can only be created from real file changes —
edit files under `/sandbox/files/library` (via
[Exec](/api-reference/v2/sandbox/execute-code) or
[Upload](/api-reference/v2/sandbox/upload-file)) **before** calling
this.
Creating a new change with no changes returns `400`.
**Review & permissions.** The change is submitted `OPEN` for admin
review
(or `DRAFT` when `draft` is true). Every changed path is revalidated
against the caller's `OWNERS` permissions at merge — a change cannot
widen
access. If an auto-approve rule matches, the response status is
`APPROVED` and the change is already live.
**Updates & conflicts.** Pass `change_number` to file a new revision of
an
existing open/draft change (title/description optional — inherited if
omitted). If the library has drifted, the response has
`has_conflicts: true`, the session's `library/` is re-materialized with
`.rej` markers, and the change stays `RESERVED` until you resolve the
conflicts and re-submit with the same `change_number`.
operationId: v2.createOntologyChange
parameters:
- $ref: '#/components/parameters/SandboxId'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
title:
type: string
maxLength: 50
description: Short summary (≤50 chars). Required for a new change.
description:
type: string
description: >-
Markdown explanation of the changes. Required for a new
change.
draft:
type: boolean
default: false
description: File as DRAFT instead of OPEN (not yet ready for review).
change_number:
type: integer
format: int32
description: Set to revise an existing change (creates a new changeset).
responses:
'201':
description: Change created or updated
content:
application/json:
schema:
type: object
properties:
change_id:
type: string
change_number:
type: integer
format: int32
status:
type: string
enum:
- open
- draft
- approved
- reserved
description: Change lifecycle state after submission.
git_ref:
type: string
has_conflicts:
type: boolean
conflicts:
type: string
description: Human-readable conflict view (present when has_conflicts).
auto_approved:
type: boolean
diffs:
type: array
items:
$ref: '#/components/schemas/LibraryChangeDiff'
raw_diff:
type: string
'400':
description: No changes to write back, or invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: Referenced change is approved/denied and cannot be updated
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
parameters:
SandboxId:
name: id
in: path
required: true
schema:
type: string
description: Sandbox ID
schemas:
LibraryChangeDiff:
type: object
description: One changed file in an Ontology change.
properties:
name:
type: string
description: Display name for the change.
old_path:
type: string
new_path:
type: string
additions:
type: integer
format: int64
deletions:
type: integer
format: int64
is_new:
type: boolean
is_delete:
type: boolean
is_rename:
type: boolean
is_binary:
type: boolean
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Machine-readable error code
enum:
- invalid_request
- unauthenticated
- permission_denied
- not_found
- conflict
- rate_limit_exceeded
- internal
- timeout
- cancelled
- execution_failed
- no_report
message:
type: string
description: Human-readable error message
responses:
Unauthorized:
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: unauthenticated
message: Authentication required
Forbidden:
description: Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: permission_denied
message: Insufficient permissions
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: not_found
message: Resource not found
RateLimited:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: rate_limit_exceeded
message: Rate limit exceeded
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: internal
message: Internal server error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key or JWT token
````