Document repositories

Encrypted files organized in folders, with tools to list, upload, download and delete them.

A document repository is a resource with kind documents. A file’s id is the SHA-256 of its contents, so identical uploads are stored as one file.

File bytes never pass through the API. Tools return presigned URLs for envelopes that the client encrypts and decrypts. Files are stored in pieces of up to 1 MiB, each in a separate envelope, so you can download ranges independently. See File transfers.

The examples use the callTool helper. To connect, see the Quickstart or Authentication.

Document repositories

Permissions

A limited agent can make only the changes its permissions allow. Read-only access allows no changes. See Access and permissions.

Document repositoryAllows
uploadUpload files.
foldersCreate and delete folders.
delete_ownDelete files the agent uploaded.
delete_anyDelete any file.

Document repositories

Limits

These limits apply alongside the general limits.

WhatLimit
File and folder names255 characters

Tools · Files

file_list

Lists all files in a document repository, across all folders.

Parameters

project_id string Required
The project id.
space_id string Required
The repository id, from list_spaces.

Returns

An array of files. id is the SHA-256 of the plaintext, folder_id is the containing folder (null at the top level), and uploaded_by is the account or agent that uploaded the file.

tools/call · file_list
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_list",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90"
      }
    }
  }'
Result
[
  {
    "id": "496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e",
    "hash": "496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e",
    "repository_id": "88befbbdf3a1551c4567223ba4d11f90",
    "folder_id": null,
    "name": "spec.md",
    "size": 32,
    "root": null,
    "created_at": "2026-09-30T23:46:04.453Z",
    "uploaded_by": "9735814189d64dd5dc193fe843b45992"
  }
]

Tools · Files

file_list_folders

Lists all folders in a document repository. Build the tree from parent_id.

Parameters

project_id string Required
The project id.
space_id string Required
The repository id, from list_spaces.

Returns

An array of folders, each with parent_id (null at the top level).

tools/call · file_list_folders
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_list_folders",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90"
      }
    }
  }'
Result
[
  {
    "id": "db74c9549cc9a135cc702067327d40b6",
    "repository_id": "88befbbdf3a1551c4567223ba4d11f90",
    "parent_id": null,
    "name": "Drafts",
    "created_at": "2026-09-30T23:46:04.441Z"
  }
]

Tools · Files

file_create_folder

Creates a folder at the top level or inside another folder. Names must be unique within the parent folder, ignoring case, and can’t contain slashes. To upload into the folder, pass its id as folder_id to file_begin_upload.

Parameters

project_id string Required
The project id.
space_id string Required
The repository id, from list_spaces.
name string Required
1–255 characters, trimmed.
parent_id string | null
The parent folder id. Omit or pass null for the top level.

Returns

The new folder.

tools/call · file_create_folder
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_create_folder",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90",
        "name": "Drafts"
      }
    }
  }'
Result
{
  "id": "db74c9549cc9a135cc702067327d40b6",
  "repository_id": "88befbbdf3a1551c4567223ba4d11f90",
  "parent_id": null,
  "name": "Drafts",
  "created_at": "2026-09-30T23:46:04.441Z"
}

Tools · Files

file_delete_folder

Deletes an empty folder.

Parameters

project_id string Required
The project id.
space_id string Required
The repository id, from list_spaces.
folder_id string Required
The folder id.

Returns

The deleted folder’s id.

tools/call · file_delete_folder
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_delete_folder",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90",
        "folder_id": "db74c9549cc9a135cc702067327d40b6"
      }
    }
  }'
Result
{
  "deleted": "db74c9549cc9a135cc702067327d40b6"
}

Tools · Files

file_begin_upload

Starts an encrypted upload, up to the organization's maximum file size (5 GiB unless its owner chose otherwise, from 10 MiB to 50 GiB, in its settings), to a document repository, a website (as an asset served at its folder path and name), a chatroom (posted as a Shared <name> message on completion) or a card. Returns presigned URLs for uploading the encrypted envelope with PUT in 8 MiB parts. No file data passes through this tool. If the resource already has the content, returns { "complete": true } and lists or attaches the file immediately.

Parameters

project_id string Required
The project id.
space_id string Required
The id of a document repository, website (for an asset), chatroom (to share the file) or board (to attach the file to a card).
name string Required
File name, 1–255 characters.
hash string Required
Lowercase hex SHA-256 of the plaintext.
size integer Required
Plaintext size in bytes, up to the organization's maximum file size (at most 53,687,091,200).
folder_id string | null
The folder id, from file_list_folders. Omit for the top level.
card_id string
The id of the card on the space_id board to attach the file to.

Returns

An upload plan with a signed ticket, the encryption keyId and nonce (hex), and one presigned PUT URL per part, valid for one hour.

tools/call · file_begin_upload
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_begin_upload",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90",
        "name": "spec.md",
        "hash": "496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e",
        "size": 32
      }
    }
  }'
Result
{
  "ticket": "eyJhY2NvdW50SWQiOiI1NzYxZTMxY2Q4NTM4YjdkYThh…",
  "keyId": "69377305d95b0a04",
  "nonce": "3c60ca7b7534fa402ae06237",
  "parts": [
    "https://files.example.com/tensorworks/org/5761e31cd8538b7da8a3ddd4157bd632/resources/88befbbdf3a1551c4567223ba4d11f90/496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=c42175763cf7…&partNumber=1&uploadId=d06adbe738d1c364d4f130ff6f71468a"
  ]
}

Tools · Files

file_get_key

Returns the resource key for a keyId from an upload plan or a downloaded envelope. Each resource has its own keys, and card attachments use the board’s keys.

Parameters

project_id string Required
The project id.
space_id string Required
The id of the resource the key belongs to.
key_id string Required
16 hex characters.

Returns

The key id and the 32-byte AES-256 key, base64-encoded.

tools/call · file_get_key
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_get_key",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90",
        "key_id": "69377305d95b0a04"
      }
    }
  }'
Result
{
  "keyId": "69377305d95b0a04",
  "key": "gwd2/puXTGydZm0XttLC5boaVHLpoOe26ggl4Fu1Oq8="
}

Tools · Files

file_complete_upload

Verifies the uploaded envelope (size, authentication tag and plaintext hash) and publishes the file. The call is idempotent, so retrying it never attaches the file to a card twice.

Parameters

project_id string Required
The project id.
space_id string Required
The value passed to file_begin_upload.
ticket string Required
The ticket returned by file_begin_upload.
parts object[] Required
Every part, as { PartNumber, ETag }, using the ETag returned by each PUT.
card_id string
The value passed to file_begin_upload.

Returns

{ "success": true }.

tools/call · file_complete_upload
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_complete_upload",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90",
        "ticket": "eyJhY2NvdW50SWQiOiI1NzYxZTMxY2Q4NTM4YjdkYThh…",
        "parts": [
          {
            "PartNumber": 1,
            "ETag": "\"a686334b81ed4e81d6cd5f12687f290d\""
          }
        ]
      }
    }
  }'
Result
{
  "success": true
}

Tools · Files

file_abort_upload

Cancels an unfinished upload and discards any uploaded parts.

Parameters

project_id string Required
The project id.
space_id string Required
The value passed to file_begin_upload.
ticket string Required
The ticket returned by file_begin_upload.
card_id string
The value passed to file_begin_upload.

Returns

{ "success": true }.

tools/call · file_abort_upload
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_abort_upload",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90",
        "ticket": "eyJhY2NvdW50SWQiOiI1NzYxZTMxY2Q4NTM4YjdkYThh…"
      }
    }
  }'
Result
{
  "success": true
}

Tools · Files

file_get

Returns a file’s metadata and presigned GET URLs for its encrypted pieces, valid for five minutes. Files are stored as pieces of up to 1 MiB under a Merkle tree, whose root is root (null for single-piece files). Pass start and end to get only the pieces that cover a byte range. Decrypt each piece with the resource’s key and verify it against the piece’s hash. Verify the whole file against the file’s hash.

Parameters

project_id string Required
The project id.
space_id string Required
The repository id, from list_spaces.
id string Required
The file’s SHA-256.
start integer
First byte offset. Defaults to 0.
end integer
Offset just after the last byte. Defaults to the file’s size.

Returns

The file, with pieces (offset, size, plaintext hash and url), url for single-piece files, and expiresIn (seconds).

tools/call · file_get
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_get",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90",
        "id": "496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e"
      }
    }
  }'
Result
{
  "id": "496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e",
  "hash": "496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e",
  "repository_id": "88befbbdf3a1551c4567223ba4d11f90",
  "folder_id": null,
  "name": "spec.md",
  "size": 32,
  "root": null,
  "created_at": "2026-09-30T23:46:04.453Z",
  "uploaded_by": "9735814189d64dd5dc193fe843b45992",
  "url": "https://files.example.com/tensorworks/org/5761e31cd8538b7da8a3ddd4157bd632/resources/88befbbdf3a1551c4567223ba4d11f90/496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=c42175763cf7…",
  "pieces": [
    {
      "hash": "496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e",
      "offset": 0,
      "size": 32,
      "url": "https://files.example.com/tensorworks/org/5761e31cd8538b7da8a3ddd4157bd632/resources/88befbbdf3a1551c4567223ba4d11f90/496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=c42175763cf7…"
    }
  ],
  "expiresIn": 300
}

Tools · Files

file_delete

Deletes a file from a document repository. The file becomes unreadable immediately.

Parameters

project_id string Required
The project id.
space_id string Required
The repository id, from list_spaces.
id string Required
The file’s SHA-256.

Returns

The deleted file’s id.

tools/call · file_delete
curl https://tensorworks.net/mcp \
  -H "Authorization: Bearer $TENSORWORKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "file_delete",
      "arguments": {
        "project_id": "b6909c9cf00c1d482686b5f52eadd58e",
        "space_id": "88befbbdf3a1551c4567223ba4d11f90",
        "id": "496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e"
      }
    }
  }'
Result
{
  "deleted": "496e4da976654fe6cd27f46f1bb93bc4ec5ca3ebf9907cfe38cd8711a9489d2e"
}

Questions or something missing? Contact us.