# API, CLI and MCP All surfaces use the same current-user permissions, connection scope, version checks and quotas. The public agent REST base is `/api/v1`. The browser uses the same handlers under `/api` with an HttpOnly session. Supply `Authorization: Bearer stuff_…` for agents. Never send a credential in a URL. Create a user-owned connection in **Agents**. Choose all current/future spaces or selected spaces/folders; then choose read, write, or write plus management. Default expiry is 90 days. Existing keys retain their old scopes and cannot manage anything unless created with that capability. Account-wide access always intersects the user's current permissions. Revocation takes effect on the next request; rotation invalidates the old secret. Management grants organization, sharing and Trash operations, with the same underlying roles and audience confirmations as the UI. Account-wide management also permits space creation and delegated connections. ## Edit attribution Version history includes account, connection, channel and optional client/model details. Send `X-Stuff-Actor-Type: agent`, `X-Stuff-Client`, `X-Stuff-Model` and `X-Stuff-Model-Provider` on writes, or `attribution` in MCP mutation tools and filesystem write bodies. Only supply actual known values; these are client-reported. [Examples, CLI configuration and historical behavior](https://stuff.ac/connect/attribution.md). ## Filesystem operations for agents `POST /api/v1/fs/{resolve|list|read|read_many|grep|edit|batch}` and matching `fs_*` MCP tools add consistent references, recursive/glob listing, ranged/multiple reads, exact original-text search, guarded edits and bounded atomic batches. CLI `pull-folder` / `push-folder` provide journaled collection workflows. [Schemas, commands, limits and conflict behavior](https://stuff.ac/connect/filesystem.md). Structured REST/MCP errors include retry guidance and conflict details. Classic ID-based routes below remain compatible. ## REST | Method | Route | Behavior | | ------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/library?parent=ID&offset=0` | Up to 200 entries; `nextOffset` for pagination. Omit parent to list connection roots. | | GET | `/search?q=words&tag=wiki-realm&source=el-os&parent=ID&type=office&offset=0` | Names and indexed current text; optional exact metadata filters, recursive folder scope, 50 results/page, authorized facets/counts/snippets. Public-share search is unavailable. | | GET | `/items/ID/preview/content?version=N` | Authorized derived PDF for the current version; 409 when stale. Same revocation as the original. | | GET | `/items/ID` | Authorized metadata and safe breadcrumbs | | GET | `/items/ID/content` | Exact original bytes. Range support; `X-Stuff-Version` and hash ETag. Historical `?version=N` needs the human's Editor role. | | GET | `/items/ID/preview` | Bounded native preview payload; processing state is explicit | | GET | `/items/ID/history` | Versions with author/time/hash; Editor role required | | POST | `/folders` | `{parentId,name}`, with `Idempotency-Key` | | POST | `/uploads?parent=ID&path=folder/file.ext&collision=keep` | Raw `application/octet-stream` plus `Idempotency-Key`. `skip` is supported. Replace requires an explicit base `version`. | | PUT | `/items/ID/content` | `{text,version}`; conflict is HTTP 409 | | PUT | `/items/ID/bytes?version=N` | Replace original bytes, with a base-version check | | PUT | `/items/ID/metadata` | `{metadata,revision}` replaces custom JSON; `revision` is the current `metadataRevision`. Editor/write connection required. | | PATCH | `/items/ID` | `{name}` for agent rename; management-enabled move uses `{parentId,confirmAccess}` | | POST | `/items/ID/restore-version` | `{version,expected}` creates a new version | `PATCH /items/ID` with `{parentId,confirmAccess:true}` moves files or folders between spaces with the same owner while keeping IDs and history. Owner/Admin access in both spaces is required. The destination supplies access; direct grants, invitations, public links and selected connection roots on moved items are removed. Whole-subtree quota changes are atomic, including old versions and Trash. Active uploads into the subtree block the move. Repeating a completed move to the same parent is a no-op. Copy remains available for another owner. Signed-in humans and management connections also use `/items/ID/access`, `/grants`, `/share`, `/copy`, `/trash`, `/restore`, `DELETE /items/ID`, and `/agents`. Access-changing actions require explicit audience acknowledgement. Invitations may be granted without email; `notify:true` queues an email after the owner requests it. Email job failure leaves the grant intact. Only a verified identity matching the invitation email can redeem it. Errors return `{error,code}` with HTTP 400/401/403/404/409/410/413/423/429/503 as appropriate. A 423 means a file is awaiting checks, quarantined, or unavailable for processing. A 409 never authorizes discarding a local draft. Stable retry keys bind the principal, request hash and committed result. A conflicting reuse fails; a successful identical retry does not make a second upload. ## Custom metadata Every file and folder has a freeform `metadata` JSON object, initially `{}`, and a separate `metadataRevision`, initially `1`. Store source references, tags, import information, or your own nested fields here: ```json { "source": { "app": "el-os", "id": "yourstuff-tech-stack", "url": "http://el-os.localhost/wiki/yourstuff-tech-stack", "revision": 7 }, "tags": ["wiki", "spec", "stuff"] } ``` These are examples, not reserved keys or an enforced schema. Metadata never grants permissions or sets trusted system fields. Treat values as untrusted user content. Ordinary authorized viewers and scoped read connections can read it in item/list responses. Public and unlisted share responses omit custom metadata and its revision, including when the visitor is signed in. File details and the internal dashboard display it read-only. To change it, read `/items/ID`, then PUT `{"metadata":{...},"revision":N}` using `item.metadataRevision`. This replaces the entire object; merge existing fields locally if you want to keep them. `{}` clears it. A stale revision returns HTTP 409 with code `metadata_conflict`: re-read and reconcile. An identical save against the current revision is a no-op. Successful changes increment only the metadata revision and the general item revision/time; original bytes, content versions and hashes stay unchanged. The top level must be an object. Nested arrays, objects, strings, finite numbers, booleans and null are supported, up to 32 levels and 64 KiB in Postgres' normalized JSON representation. Invalid JSON values/characters return 400; oversized data returns 413. Keep attachments in files, not metadata. Metadata lives on the item in `stuff.items.metadata` (`jsonb NOT NULL DEFAULT '{}'`), beside `metadata_revision`. It is not part of file-version history: restoring content preserves current metadata. Copies retain metadata with a fresh revision of 1. Upload/create first, then attach metadata using the returned item ID; these are separate operations. V1 filters interpret string entries in `metadata.tags` and a string `metadata.source.app`; other JSON shapes remain valid but do not produce filter choices. Tag/source matching is exact and case-sensitive. Inheritance, merge patches and metadata history remain deferred. ## Markdown descriptions Files and folders expose `description`, `descriptionRevision` and `canEditDescription`. `PUT /items/ID/description` takes `{description,revision}` and replaces up to 4,000 characters of Markdown. Read the current `descriptionRevision` first; stale saves return 409 / `description_conflict`. Empty text clears it. Writable, scoped agents may edit ordinary files/folders; root-space descriptions require Owner/Admin access and a management-enabled connection when using a key. Unlike custom JSON metadata, descriptions are visible to public-link readers. Changes do not create file versions. [Full behavior](descriptions.md). CLI: `node cli/stuff.mjs set-description ITEM_ID ./description.md DESCRIPTION_REVISION`. Remote and stdio MCP expose `set_description` with `{id,description,revision}`; `get_item` returns the description and revision. Typed item/space references, Stuff URLs and explicit paths are supported by the new filesystem tools; existing MCP item fields also accept typed references and URLs. [Reference support and remaining UI proposal](references-proposal.md). ## CLI Install the standalone command with `npm install --global https://stuff.ac/downloads/stuff-ac-cli-0.4.0.tgz` (Node 24+). Set your private `STUFF_API_KEY`, then run `stuff check`. [Full setup](https://stuff.ac/connect/cli.md). Source examples below remain valid; replace `node cli/stuff.mjs` with `stuff` after installing. ```sh export STUFF_ORIGIN=https://stuff.ac export STUFF_API_KEY='' node cli/stuff.mjs search "product brief" --tag wiki-realm --source el-os node cli/stuff.mjs list node cli/stuff.mjs list FOLDER_ID node cli/stuff.mjs get ITEM_ID # Read metadataRevision from get; use that value (1 for a new item). node cli/stuff.mjs set-metadata ITEM_ID ./metadata.json 1 node cli/stuff.mjs pull FILE_ID ./notes.md # Edit notes.md using your preferred tool. node cli/stuff.mjs push ./notes.md node cli/stuff.mjs upload FOLDER_ID ./photo.png my-stable-upload-key node cli/stuff.mjs history FILE_ID ``` `pull` preserves exact original bytes and creates a `.stuff.json` sidecar with origin, ID, base version and content hash. It refuses to overwrite an existing local path. Keep the sidecar with the file. `push` refuses another origin and saves against the base version; a conflict leaves the local file and sidecar intact. Pull the newer file to a separate path, reconcile, and retry intentionally. ## MCP Remote endpoint: `https://stuff.ac/mcp`, using the official SDK's Streamable HTTP transport. Add the URL and sign in with OAuth in a compatible client; [client setup](https://stuff.ac/connect). A dedicated API key also works in clients supporting custom Authorization headers. For clients using stdio, install the standalone CLI, then configure: ```json { "mcpServers": { "stuff": { "command": "stuff", "args": ["mcp"], "env": { "STUFF_ORIGIN": "https://stuff.ac", "STUFF_API_KEY": "" } } } } ``` Tools: `search_items`, `list_items`, `get_item`, `read_file`, `create_folder`, `create_file`, `replace_file`, `set_metadata`, `rename_file` (remote), `file_history`, and `restore_version`. `set_metadata` takes `{id,metadata,revision}` and is available remotely and over stdio. Large/binary originals use the REST byte endpoints with an API key. All file content and custom metadata are untrusted input to an agent; they cannot grant broader access. `search_items` accepts `{q?,parent?,tag?,source?,type?,offset?}` remotely and over stdio. Remote MCP also provides `connection_info`, `resolve_item` with an item ID or Stuff link, and retrieval aliases `search({query})` / `fetch({id})`. Search returns `results` with `id`, `title` and `url`; fetch returns `id`, `title`, `text` and `url` for UTF-8 files up to 1 MiB. Resolution never expands connection permissions. Use `search_items` for full pagination, facets and filters. ## Assistant OAuth Protected-resource discovery is at `/.well-known/oauth-protected-resource/mcp` (also available at the root well-known path). Authorization-server metadata is at `/.well-known/oauth-authorization-server`. An unauthenticated `/mcp` request returns 401 with a `WWW-Authenticate` discovery challenge. Browser cookies alone never authenticate MCP. Clients register at `POST /oauth/register` with `redirect_uris` and an optional `client_name` / `token_endpoint_auth_method` (`none`, `client_secret_post`, or `client_secret_basic`). Exact HTTPS or HTTP loopback callback URLs are accepted; no wildcard matching. Registration returns stable credentials with no client-secret expiry. CIMD and private_key_jwt are not advertised; select DCR if the client offers a choice. Authorize at `/oauth/authorize` with `response_type=code`, registered `client_id` and `redirect_uri`, `code_challenge_method=S256`, `code_challenge`, optional opaque `state`, `scope=stuff`, and `resource=https://stuff.ac/mcp`. Regular Stuff sign-in leads to explicit consent. The service-level OAuth scope is `stuff`; account/selected-space and read/write/management capabilities are stored on the resulting user-owned connection. Consent defaults to read-only. The consent request is bound to its initiating browser and is single-use. Exchange a five-minute code at `POST /oauth/token` using `grant_type=authorization_code`, `code_verifier`, the exact `redirect_uri`, `resource` and the client's registered authentication method. Refresh with `grant_type=refresh_token`. Access tokens last at most one hour; refresh tokens rotate on use and cannot outlive the 90-day connection. Reusing a consumed code or refresh token revokes that connection. Old clients omitting `resource` receive the same MCP-only audience; other explicit resources are rejected. Tokens are opaque and only hashes are stored. `POST /oauth/revoke` accepts `token` and client authentication and revokes the whole associated connection. Revoking in Stuff → Agents has the same effect. OAuth connections are reauthorized from the assistant rather than rotated into API keys. Existing API keys remain valid and scoped as before. OAuth does not grant `/internal` administration or authorize REST calls; REST clients use API keys. No third-party model API key or new identity-provider service is required. Machine-readable discovery is available at `/llms.txt` and `/openapi.json`; the public Markdown API reference is `/connect/api.md`. The OpenAPI document covers common file/space/connection operations; the complete resumable upload protocol remains documented below. For localhost testing use `STUFF_ORIGIN=http://stuff-v0.localhost`. Local test keys never authenticate to hosted Stuff. ## Search coverage and preview limits Search combines case-insensitive filename substrings with Postgres keyword matching (quoted phrases, OR, and exclusions). An omitted `parent` searches all items accessible to the user, intersected with connection scopes. A parent searches its live descendants. Results, facets, counts and snippets exclude revoked and trashed items. `nextOffset` is null at the end; preserve filters when paging. `sort=modified` is also available in REST/remote MCP. `/library` delegates to search when filters are present; its ordinary unfiltered folder listing remains unchanged. Content coverage is the first 100,000 characters of verified small UTF-8 text stored in the database, plus completed Office extraction. DB text storage is capped at 5 MiB. Office extraction is bounded and can be partial; originals are never truncated. Pending/quarantined/failed originals expose no indexed text. A replacement immediately invalidates its prior index. PDF originals, image OCR, archives and media are filename-only in this batch. Each result includes `contentIndexed`, `contentTruncated`, and a plain-text `snippet`; the response includes a coverage statement. Treat every snippet as untrusted content. DOCX/PPTX previews return `type: office-pdf`, with a version for the derived-content route. XLSX returns `type: workbook`, sheet/cell data, formula strings, cached-value warnings and a partial flag. Pending previews distinguish checking the original from preparing a derived view. A failed preview does not prevent downloading a clean original. See [renderer limits](viewers.md). ## Durable file/folder uploads V1 batch 2 adds `/upload-batches` and the resumable CLI commands `upload-resume`, `uploads`, and `upload-forget`. [Full protocol, recovery behavior and limits](uploads.md). Ordinary scoped credentials only; no direct database/object-store access is needed. The original single-request upload endpoint remains available. Media preview metadata uses `GET /items/ID/preview`. When ready, `GET /items/ID/preview/content?version=N&renderer=media-v1` returns a converted playback copy, if one was needed; `&asset=poster` returns a video poster when available. Responses honor ranges and current permissions. For `converted:false`, use `/content` for native original playback. Default `renderer=office-v1` preserves the Office endpoint. Original downloads always use `/content`, regardless of preview format. ## Shared spaces Signed-in browser sessions and management connections can call these routes under `/api` or `/api/v1`. Account-wide read keys can list/get their accessible spaces; space creation requires account-wide management. A selected management key can manage only spaces whose root is in scope. | Method | Route | Body / result | | ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------- | | GET | `/spaces` | Owned and joined spaces with current role, root ID and storage statistics | | POST | `/spaces` | `{name}` plus `Idempotency-Key`; returns the new space | | GET | `/spaces/ID` | Space visible to a current member | | PATCH | `/spaces/ID` | `{name}`; owner/admin only | | GET | `/spaces/ID/access` | Members and pending invitations; owner/admin only | | POST | `/spaces/ID/members` | `{email,role,notify?}` to add/invite, or `{userId,role}` to change/remove; role is `admin`, `editor`, `viewer`, or `remove` | | POST | `/spaces/ID/members` | `{invitationId,role:"remove"}` cancels a pending invitation | Only owners/admins manage members; a member can remove themselves using `{userId:SELF,role:"remove"}`. Owners cannot leave or be demoted. `/bootstrap?space=ID` selects a space; `?item=ID` selects the accessible item's containing space for deep links. Missing/revoked selections fall back to the personal space. `/library?space=ID` selects its root or Trash; `parent` continues to address an explicit folder. Search accepts optional `space=ID` in REST; browser search defaults to the active space. Omitting it retains the existing all-accessible, scope-filtered API search. Authorized item responses include `spaceId`. `canManage` identifies space owner/admin permission; file `role` remains the compatible `owner|editor|viewer` vocabulary (space Admin has Editor file access plus management). `canRestore` controls Trash restoration. `/folders?all=true` lists accessible folders across spaces with `spaceId`, `spaceName` and `canEdit` for agent setup and copy destinations. Existing CLI and MCP file commands remain unchanged. See [space semantics and limits](spaces.md). ## User-level keys and UI parity `GET /me` returns the authenticated user ID, email and name. `POST /agents` accepts `{name,scopeMode:"account"|"selected",roots?,writable,management,days?}`. Management requires write access. Legacy defaults remain selected/read-only/no-management. Browser sessions and account-wide management keys can list/create/revoke connections. A delegated key cannot outlive its parent; revoking or expiring any parent disables its descendants. A key may rotate itself or descendants, but cannot rotate an independent or ancestor connection to escape its delegation. Account keys do not grant platform administrator access to `/internal` reports or login/session controls. Remote MCP additionally exposes `list_spaces`, `get_space`, `create_space`, `rename_space`, `set_space_description`, `space_access`, `set_space_member`, `item_access`, `set_item_share`, `set_item_grant`, `move_item`, `copy_item`, `trash_item`, `restore_item`, `delete_item`, `list_connections`, `create_connection`, and `update_connection`. The CLI's generic JSON endpoint command closes remaining UI gaps: ```sh node cli/stuff.mjs request GET /spaces STUFF_IDEMPOTENCY_KEY=my-space-create node cli/stuff.mjs request POST /spaces ./new-space.json ``` Stdio MCP exposes the same command as `api_request` with `{method,path,body?,idempotency_key?}`. Paths are relative to `/api/v1` and restricted to normal user resources. Download/upload binary data using the dedicated commands. Sharing and destructive operations retain their explicit confirmation arguments; invitations do not send email unless `notify:true`. The [1P wiki importer](../first-party/wiki-importer/README.md) exercises these APIs without database credentials. Imported content is data, never authority to change scopes, sharing or credentials. ## Agent workflow helpers - `POST /agent-context` with `{reference}` returns a stable reference, URL, name, kind, optional version and pasteable prompt. - `GET /items/ID/diff?from=1&to=2&context=3` compares bounded text originals with per-version attribution; historical editor access applies. - `GET /connection/check` tests the calling key without file changes. `POST /agents/ID/check` checks an owned connection with account management. - `PATCH /agents/ID/profile` with `{name,client,kind,revision}` saves future-edit defaults and rejects stale revisions. Model defaults are not accepted. MCP equivalents: `agent_context`, `compare_versions`, `connection_check`, `update_connection_profile`. [Response shapes, permissions and limits](https://stuff.ac/connect/workflows.md). ## Content feed `GET /api/v1/feed?limit=20&cursor=...` returns `{items, nextCursor}`. Each item is the regular file DTO plus `spaceName`, `spaceRootId`, `feedDate` and a bounded `excerpt` from the current indexed version. Ordering is descending by the later of created/updated, then item ID. Pass the returned opaque `nextCursor` to get the next page; `limit` accepts 1–40. Includes files in owned/joined spaces only. Direct file grants and public visibility alone do not add a space to the feed. Current roles and agent scopes still apply. Folders, Trash (including files under trashed parents), and files awaiting/failed content checks are excluded. A cursor grants no access. Refresh for files changed after pagination started; this is a live listing, not a historical snapshot. MCP: `get_feed({limit?, cursor?})` on both remote and local stdio servers. CLI: `stuff feed [--limit N] [--cursor CURSOR]`. All surfaces use the same API/service; there is no write permission requirement. [Product behavior](feed.md).