Files API & CLI
Upload, download, list, and attach files, versioned artifacts, and sessions over the CLI, HTTP API, TypeScript SDK, or MCP.
Use the same server-enforced resource operations across the twin CLI, the
REST API, the TypeScript SDK, and MCP to create versioned Markdown
documents and CSV sheets, upload and download binary files, and attach or detach
files, artifacts, and sessions across Channels and Data Set records.
For creating and organising pages, sheets, documents, and uploads in the web app, see Add pages, sheets, documents & files.
Use the CLI
Install and sign in to the CLI, then use the same commands from your terminal or a local coding assistant:
twin login
# Create a document or sheet directly from local content.
twin artifacts --kind markdown --title "Project brief" \
--file brief.md --channel operations --assert-org <org> --allow-write
twin artifacts --kind csv --title "Delivery plan" \
--file plan.csv --channel operations --assert-org <org> --allow-write
# Upload original bytes and place the file in the Channel.
twin files --upload proposal.pdf --channel operations --assert-org <org> --allow-write
# Find existing content and download an uploaded file.
twin files --q proposal --json
twin artifacts --channel operations --json
twin sessions --json
twin files --file FILE_ID --download proposal-copy.pdf
# Attach existing resources without copying them.
twin files --file FILE_ID --attach --channel operations --assert-org <org> --allow-write
twin artifacts --artifact ARTIFACT_ID --attach --channel operations --assert-org <org> --allow-write
twin sessions --session SESSION_ID --attach --channel operations --assert-org <org> --allow-write
# Remove one attachment without deleting the original.
twin files --file FILE_ID --detach --channel operations --assert-org <org> --allow-write
twin artifacts --artifact ARTIFACT_ID --detach --channel operations --assert-org <org> --allow-write
twin sessions --session SESSION_ID --detach --channel operations --assert-org <org> --allow-writeFile attachment also accepts --session SESSION_ID or --record RECORD_ID
instead of --channel. Artifact attachment accepts --record RECORD_ID. You
set a Session field through the record API, while session attachment targets
Channels.
Detaching an artifact from a Channel also works when the Channel's own work or a session in that Channel created it: it leaves the Channel's lists, while its versions, sessions, and tasks stay intact. Attach it again to bring it back.
Run twin help files, twin help artifacts, or twin help sessions to see
every option. Writes require --allow-write, and downloading to an existing
local path fails instead of overwriting it.
Use the HTTP API
Public clients talk to the Twin gateway using an OAuth bearer token or signed
subject token. Reads need twin.read; changes need twin.write along with the
user's normal resource permissions.
The upload endpoint accepts standard multipart file bytes, up to 50 MiB (or a lower limit if your organisation sets one). Let your HTTP client generate the multipart boundary:
curl "$TWIN_GATEWAY/api/twin/files" \
-H "Authorization: Bearer $TWIN_ACCESS_TOKEN" \
-F "file=@proposal.pdf" \
-F "channelId=CHANNEL_ID"The response returns file.id. Use that ID to read metadata at
GET /api/twin/files/FILE_ID, download bytes at
GET /api/twin/files/FILE_ID/content, or attach the file elsewhere:
POST /api/twin/files/FILE_ID/links
Content-Type: application/json
Authorization: Bearer <access-token>
{"targetType":"record","targetId":"RECORD_ID"}Send DELETE to the same path with the same body to detach it. Artifact links
use /api/twin/artifacts/ARTIFACT_ID/links and accept channel or record.
Session sharing uses /api/twin/sessions/SESSION_ID/channels with
{"channelId":"CHANNEL_ID"}. Artifact and session attachment responses return
attached, and removal responses return detached (false means it was
already in that state). File attachment and removal return the updated file
with its current links.
Record attachment IDs
The record attachment API expects stored workspace record IDs. A source-system row ID on its own won't identify a workspace attachment target. For records synced from a connected source, place new content in the known Channel and store its ID in the editable record field.
Use the TypeScript SDK
The handwritten TypeScript SDK exposes the same operations:
import { SDK } from "@mercury-labs/mlx-agent-sdk";
const sdk = new SDK({
serverURL: process.env.TWIN_GATEWAY,
bearerToken: process.env.TWIN_ACCESS_TOKEN,
});
const { file } = await sdk.twin.uploadTwinFile({
file: new File(["Draft brief"], "brief.txt", { type: "text/plain" }),
channelId: "CHANNEL_ID",
});
await sdk.twin.attachTwinFile({
fileId: file.id, targetType: "record", targetId: "RECORD_ID",
});
await sdk.twin.attachTwinArtifact({
artifactId: "ARTIFACT_ID", targetType: "channel", targetId: "CHANNEL_ID",
});
await sdk.twin.attachTwinSession({ sessionId: "SESSION_ID", channelId: "CHANNEL_ID" });Create documents and sheets with sdk.twin.createTwinArtifact, passing kind: "markdown" or kind: "csv", title, content, an idempotencyKey, and an
optional channelId. When updating an artifact, pass its expectedVersionId
so you don't overwrite someone else's newer version.
Use MCP
Connected MCP clients have the same resource operations:
| Action | MCP tools |
|---|---|
| Find or inspect files | twin_files_list, twin_file_get |
| Upload a small file | twin_inline_file_upload |
| Prepare a larger upload | twin_file_upload_prepare |
| Read a file | twin_file_content_get |
| Attach or detach a file | twin_file_attach, twin_file_detach |
| Create or edit an artifact | twin_artifact_create (paused on MCP for now: it still records a Twin session), twin_artifact_update, twin_artifact_cell_update |
| Attach or detach an artifact | twin_artifact_attach, twin_artifact_detach |
| Share or unshare a session | twin_session_attach, twin_session_detach |
twin_inline_file_upload takes a filename, content type, and base64 content up
to 32 KiB decoded. It uploads the file and returns the saved file. For example:
{"fileName":"note.txt","contentType":"text/plain","contentBase64":"SGVsbG8=","sessionId":"SESSION_ID"}Over MCP, an upload or prepared upload that names a channel is refused, because
adding a new file to a channel triggers that channel's upload workflows, which
can run as a Twin session. Instead, upload without a channelId, then call
twin_file_attach to add the file to the channel without starting those
workflows. If you want them to run, add the file in the Twin app. The API, CLI,
and SDKs still upload straight into a channel as before.
For a larger file, call twin_file_upload_prepare with its placement, such as
{"sessionId":"SESSION_ID"}. It returns uploadUrl, method, fileField,
fields, maxBytes, and authentication instructions. That response returns
uploaded: false because preparing doesn't upload the file itself: your client
still needs to send the multipart request with the same authenticated authority
and check the upload response. If an MCP client can't send authenticated HTTP
uploads, use the CLI or another HTTP client for files over 32 KiB.
Access rules for attachments
| Resource | What attaching it to a Channel does |
|---|---|
| File | Grants access through the destination. Only its creator or an organisation admin can change its attachments. |
| Artifact | Adds a link to the same artifact and its versions. Its original access rules stay in place. |
| Session | Explicitly lets current Channel readers view the conversation. Only the session owner or an organisation admin can share it. |
Sharing a session doesn't transfer ownership, let others send messages or start runs, or share its task, artifacts, or files. Those keep their own access rules. Removing the explicit session attachment revokes that shared access, while independent access and existing Channel activity stay as they are. An agent simply reading or writing in a Channel doesn't create a session-sharing grant.