These routes are off by default. The first six routes below (
/api/v1/mooring/apps
through the mandate routes) exist only when the server runs with
CREWSHIP_GRIDCRAFT_ENABLED=true. Provenance and the command session exist only
with CREWSHIP_MOORING_ENABLED=true; the command session also needs
CREWSHIP_MOORING_COMMANDS_ENABLED=true. Without CREWSHIP_GRIDCRAFT_ENABLED
or CREWSHIP_MOORING_ENABLED the routes are not registered and return 404.
With Mooring on but CREWSHIP_MOORING_COMMANDS_ENABLED off, the command
session is still registered and returns 503 “native command editing is
disabled”.{error}. Shared
DIRECT agent changes are refused. Native GridCraft retains its existing routes.
GET /api/v1/mooring/apps
Auth: current human workspace credential. Request: no body.
Response: installed manifests with protocol version, format, editor entry and
command JSON Schemas. Statuses: 200, 401, 403, 404.
POST /api/v1/mooring/documents
Auth: current human workspace credential and permission to create artifacts
(OWNER, ADMIN, MANAGER, or the page.create capability).
Request: {app_id,slug,name}. The JSON profile creates a private artifact
owned by the caller;
native GridCraft uses its existing creation/import protocol.
Response: {page_id,slug,name,app_id}. The slug is the creation retry key.
Statuses: 201 created, 200 exact retry, 400 invalid declaration, 401 revoked
credential, 403 denied, 404 unavailable, 409 conflict, 500 persistence failure.
GET /api/v1/pages/{slug}/mooring
Auth: owner of the private artifact, with a current human workspace credential.
Request: slug path parameter, also accepting @ID.
Response: {app_id,manifest,state,editor} with state
{rev,generation,snapshot}. Editor availability includes pinned URL and digest.
Statuses: 200, 401 invalid credential, 404 unavailable or unauthorized,
500 persistence failure, 503 unavailable application.
POST /api/v1/pages/{slug}/mooring/commands
Auth: owner of the private artifact, with a current human workspace credential.
Request: {mutation_id,base_rev,generation,command,arguments}; arguments must
validate against the compiled manifest schema. Full-state replacement requires
an exact base revision and generation.
Response: durable receipt with mutation ID, revision, issuer, state hash,
durability and visibility. Identical retries return the original receipt.
Statuses: 200 committed, 400 invalid command, 401 invalid credential,
404 unavailable or unauthorized, 409 stale base or conflicting mutation key,
500 persistence failure, 503 unavailable application.
POST /api/v1/pages/{slug}/mooring/mandates
Auth: owner of the private artifact, with a current human workspace credential.
Request: {mandate_id,run_id,base_rev,generation,command}. The run must retain
that human’s live host-dispatched chat authority and current workspace policy.
Response: retained mandate packet. Identity and scope cannot be widened.
Statuses: 200 admitted or exact retry, 400 invalid request, 401 invalid
credential, 404 unavailable or unauthorized, 409 changed preconditions,
500 persistence failure.
DELETE /api/v1/pages/{slug}/mooring/mandates/{mandate}
Auth: owner of the private artifact, with a current human workspace credential.
Request: slug and mandate path parameters; no body.
Response: {status: revoked}. Revocation is terminal and exact retries are safe.
Statuses: 200, 401 invalid credential, 404 unavailable or unauthorized,
500 persistence failure.
The generic mooring_command MCP tool and crewship mooring agent CLI forward
signed live-run authority through protected host IPC. No browser or editor
receives the host or agent credential. Every commit rechecks current authority
and retained mandate before issuing its receipt.
GET /api/v1/pages/{slug}/mooring/provenance
Authentication: current original human session or CLI credential with pages:read.
The native route is default-off with Mooring sessions. Request: path slug or
@PageID, query workspace_id; no request body. Current read access to the artifact
and each source chat audience are checked independently. References grant no rights.
Response: JSON {artifacts:[{page_id,title,application_id,provenance,chat_id,message_id,agent_slug,last_revision,edited_at}],artifacts_partial:true}.
Only immutable agent-edit records are projected, never inferred creation. At most
64 recent candidates are checked; inaccessible rows are omitted without returning
their title or source-chat references. The constant partial marker is not a hidden
row count. last_revision is a native saved cut, not a legacy checkpoint ID.
Headers: Cache-Control: no-store. The original credential expiry or three-second
request-send horizon, whichever is earlier, bounds physical delivery.
Statuses: 200 (bounded authorized metadata), 401 (no original human), 403 (current
credential/read scope refused), 404 (artifact or native read unavailable), 503 (current
metadata/transport verification unavailable). Errors are JSON {error}.
The existing GET /api/v1/chats/{chatId}/document-access response also carries
separate artifacts and artifacts_partial fields under the same independent
current checks; these fields do not change document-grant or live-task authority.
POST /api/v1/pages/{slug}/mooring/command-session
Auth: normal current human authentication, workspace membership, current
read/write rights on the artifact, the original identity fence and exact same-origin Origin.
The native command test profile is separately disabled by default. Verified
runtime assets and explicit operator activation are required.
Request: path slug or @ID, workspace query workspace_id or header
X-Workspace-ID, and the closed MooringCommandSessionRequest JSON body.
open accepts optional create and write booleans. Creation initializes only
an empty new artifact as wordcraft-c1-v2; existing documents are never converted.
read, submit and outcome require the returned view. Submit/outcome also
require raw, the exact original command string. Unknown keys, duplicate keys,
case aliases, null fields and oversized bodies are refused. A view is an identity
fence, never an authentication credential or a grant.
Response: MooringCommandSession with view, stable actor, fixed format
and engine, confirmed projection, nullable outcome, and optional pinned editor URL
and digest. Projection contains generation, SQL revision, stable ids and
opaque native_json. Saved requires a matching original operation’s durable SQL
receipt. Unknown outcomes support lookup and confirmed-state recovery without
blind replay. The generated server catalog rejects unqualified/global commands;
engine fixture qualification alone does not establish browser acceptance.
Statuses: 200 confirmed read or original durable outcome, 400 malformed input,
401 invalid authentication before admission, 403 denied identity/artifact/profile or
unavailable open, 409 unconfirmed/conflicting operation, 413 oversized request,
500 persistence failure, 503 disabled or unavailable bounded transport.
This is the browser command-session transport. It does not register a dedicated
CLI command or a native command MCP/chat route. Turning off new editing retains
the native data and never opens it with the legacy adapter.