> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mooring applications

> Experimental API for personal documents edited by installed Mooring applications, stored as private artifacts.

> [!NOTE]
>
> 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".

Each Mooring document is a private [artifact](https://docs.crewship.ai/api-reference/artifacts.md) owned by
the person who created it. The experimental personal-document API uses the
existing workspace context and human credentials. Its JSON profile is documented in the
[pilot contract](https://docs.crewship.ai/specs/mooring-pilot). All errors use JSON `{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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.