Agents-and-API.md
Working with agents
An agent key belongs to your user account. You choose how much of your account it can use.
Account-wide covers your current and future spaces, within your own access. Selected spaces or folders confines the connection to a smaller job. Read-only, editing, and management are separate capabilities. Management permits organization and sharing; account-wide management also permits creating spaces and delegating connections.
For a personal agent that organizes your whole library, an account-wide management connection is convenient. For a recurring news publisher, a connection limited to its publishing space is enough. Existing limited keys stay limited when new capabilities ship.
Interfaces
For compatible assistants, use Connect your assistants: add https://stuff.ac/mcp, sign in with OAuth and approve access. For scripts and custom API connectors, create an API key from Agents and copy it when shown. Store it in your agent's secret environment, never in a document you share. Connections expire and can be revoked. The default lifetime is 90 days.
The normal REST base is https://stuff.ac/api/v1. Authentication is Authorization: Bearer YOUR_KEY. The remote MCP endpoint supports OAuth with automatic client registration and token refresh, or a bearer API key. OAuth access tokens are for MCP; REST uses API keys. Connection page · OpenAPI.
Some useful API operations:
| Operation | Route |
|---|---|
| Check the signed-in identity | GET /me |
| List spaces | GET /spaces |
| Create a space | POST /spaces with {name} and Idempotency-Key |
| List a folder | GET /library?parent=FOLDER_ID |
| Read an item and its metadata | GET /items/ITEM_ID |
| Download original bytes | GET /items/ITEM_ID/content |
| Edit source bytes | PUT /items/ITEM_ID/bytes?version=N |
| Update metadata | PUT /items/ITEM_ID/metadata with {metadata,revision} |
Management routes cover membership, descriptions, item grants, public sharing, moves, copies, Trash, restoration and permanent deletion. They enforce the same roles and confirmations as the UI. API access does not confer platform administrator access or let an agent impersonate another user.
The installable CLI provides file pull/push/upload commands and request METHOD /path [JSON_FILE]. Its stdio MCP adapter also exposes a generic api_request tool for normal user resources. Use stable idempotency keys for creation and the current version for updates. A conflict means read and reconcile, not blindly retry with a new version.
Work with files like a filesystem
The fs_* MCP tools and /api/v1/fs/* endpoints can resolve Stuff links/IDs/explicit paths, list recursively, read selected lines or multiple files, search exact original text, apply guarded edits and preview/apply small atomic batches. File reads and search have explicit limits and continuation fields; skipped or partial content is reported.
The CLI also supports pull-folder and push-folder: work on ordinary local originals, preview changes, then apply them with version checks. Keep the generated journal. Local deletion does not delete the remote original, and conflicts preserve the local draft. These tools do not provide a remote shell or background two-way sync.
See the filesystem guide for commands, examples and current limits.
See which assistant changed a file
History keeps the account owner and adds the source of each edit: manual browser action, AI agent, or automation. New versions snapshot the connection name and show the client, model and provider when supplied. Older versions show their stored connection when available; agent/model details that were not recorded stay unknown.
MCP write tools accept attribution, for example {"kind":"agent","client":"Codex","model":"openai-gpt-6-astra","provider":"OpenAI"}. These example values are illustrative: use the actual client and model, and omit the model when unavailable. REST accepts X-Stuff-Actor-Type, X-Stuff-Client, X-Stuff-Model and X-Stuff-Model-Provider. CLI processes can set STUFF_ACTOR_TYPE, STUFF_CLIENT, STUFF_MODEL and STUFF_MODEL_PROVIDER.
Agent and model details are client-reported. A browser save records a manual action in Stuff, not proof that the text was written without AI. Full attribution guide.
Less setup, clearer handoffs
Choose Use with agent on any signed-in space, folder or file. Copy a stable reference or a ready-to-paste prompt, then add your task. The assistant needs its own connection; the reference does not change access. MCP agent_context and REST POST /agent-context return the same context.
History → Compare versions shows exact text additions/removals and each version’s saved user/client/model details. Use MCP compare_versions, REST GET /items/ID/diff?from=1&to=2, or stuff diff REFERENCE 1 2. Large and binary files retain original downloads.
Connections → Edit details remembers an assistant/app name for future edits. Models are supplied per edit, never guessed or stored as a default. Check access verifies current Stuff permissions without changing files. For a real client test, run connection_check inside that assistant or stuff check with its API key.
Install with Node 24+: npm install --global https://stuff.ac/downloads/stuff-ac-cli-0.4.0.tgz. Set your key privately as STUFF_API_KEY; run stuff --help for commands. No repository checkout is needed. Workflow details and limits.
Open with JavaScript for the full viewer.