TwinDocs
Develop with your Twin

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-write

File 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:

ActionMCP tools
Find or inspect filestwin_files_list, twin_file_get
Upload a small filetwin_inline_file_upload
Prepare a larger uploadtwin_file_upload_prepare
Read a filetwin_file_content_get
Attach or detach a filetwin_file_attach, twin_file_detach
Create or edit an artifacttwin_artifact_create (paused on MCP for now: it still records a Twin session), twin_artifact_update, twin_artifact_cell_update
Attach or detach an artifacttwin_artifact_attach, twin_artifact_detach
Share or unshare a sessiontwin_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

ResourceWhat attaching it to a Channel does
FileGrants access through the destination. Only its creator or an organisation admin can change its attachments.
ArtifactAdds a link to the same artifact and its versions. Its original access rules stay in place.
SessionExplicitly 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.

On this page