> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revilico.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# RevDrive

> Browse and read RevDrive files through the Revilico REST API or MCP server, upload and save files to Drive, organize them, and use Drive files as run inputs.

The API reaches [RevDrive](https://docs.revilico.bio/docs/revdrive.md), the same files and folders you see in the web app: your own Drive and the shared drives you belong to. You can browse and read them, upload new files, save run outputs to Drive, and use Drive files as run inputs.

## Drives and ids

There are two kinds of drive:

* **Your Drive** is personal. It holds your own files and folders, plus what others have shared with you and the folders of projects you are in.
* **Shared drives** belong to a team. What you can do in one depends on your role in it.

Ids say which kind of drive an item is in:

| Prefix | What |
| - | - |
| `dfile_` | A file in a personal Drive |
| `dfld_` | A folder in a personal Drive |
| `drive_` | A shared drive |
| `sdfile_` | A file in a shared drive |
| `sdfld_` | A folder in a shared drive |

Every item has `permission`, your access to it, and `canEdit`, whether you can rename, move or add to it:

* **Your Drive:** `owner`, `admin`, `editor`, `commenter` or `viewer`, from a share, a folder above it or a project. Owners, admins and editors can change things.
* **Shared drives:** your role. Managers and contributors can add and change files; commenters and viewers can only read.

Items in the trash are never listed or returned.

## Browse

`GET /v1/drive/items` lists the root of your Drive. Folders come first, then files, each by name.

```bash theme={null}
curl https://public-api.revilico.bio/v1/drive/items \
  -H "Authorization: Bearer $REVILICO_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "dfld_a81c…",
      "type": "folder",
      "name": "screening",
      "driveId": null,
      "parentId": null,
      "format": null,
      "sizeBytes": null,
      "permission": "owner",
      "canEdit": true,
      …
    },
    {
      "id": "dfile_3d9e…",
      "type": "file",
      "name": "round3.sdf",
      "format": "sdf",
      "sizeBytes": 482113,
      …
    }
  ],
  "nextCursor": null
}
```

Narrow the list with these query parameters:

| Parameter | Lists |
| - | - |
| `folderId` | One folder: `dfld_…` in your Drive, `sdfld_…` in a shared drive |
| `driveId` | A shared drive's root (`drive_…`) |
| `q` | Items whose name contains this, ignoring case. Without a folder it searches the whole drive. |
| `type` | Only `folder` or only `file` |
| `format` | Only files with this extension, such as `sdf` |
| `sharedWithMe=true` | Everything others shared with you directly, wherever it is in their Drive. Not with `folderId` or `driveId`. |

`GET /v1/drive/shared-drives` lists the shared drives you are a member of, with your role.

## Read a file

`GET /v1/drive/files/{driveFileId}` returns a file's metadata. `GET /v1/drive/files/{driveFileId}/content` returns a pre-signed download URL, valid for 15 minutes, and for text files the start of the content inline:

```bash theme={null}
curl "https://public-api.revilico.bio/v1/drive/files/dfile_5f10…/content?rows=20" \
  -H "Authorization: Bearer $REVILICO_API_KEY"
```

```json theme={null}
{
  "id": "dfile_5f10…",
  "name": "hits.csv",
  "format": "csv",
  "sizeBytes": 18233,
  "url": "https://…",
  "expiresAt": "2026-10-27T11:15:00.000Z",
  "content": "smiles,score\nCCO…,-9.8\n…",
  "truncated": true,
  "rows": 20
}
```

* Text files include CSV, TSV, SDF, PDB, XYZ and FASTA. Other files have `content: null`; download them from `url`.
* `content` holds whole lines, up to `maxBytes` (256 KB by default, up to 1 MB).
* For CSV and TSV, `rows` caps the data rows after the header (200 by default, up to 10,000).
* `truncated` says the file goes on; download the rest from `url`.

## Use a Drive file as a run input

Pass a Drive file id where a run takes a file id, the same way as an upload's `file_…` id:

```bash theme={null}
curl https://public-api.revilico.bio/v1/engines/revorbitals/runs \
  -H "Authorization: Bearer $REVILICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Round 3 orbitals",
    "parameters": { "solvent": "water" },
    "inputs": { "molecules": "dfile_5f10…" }
  }'
```

* Any file you can read works: `dfile_…` from your Drive or shared with you, or `sdfile_…` from a shared drive.
* The key needs `data:read` as well as `runs:write`.
* The engine's input formats and size limits apply as for uploads. `GET /v1/engines/{engine}` lists them.
* The run gets its own copy of the file when it starts. Changing, moving or trashing the Drive file afterwards doesn't change the run.

## Upload a file

Uploading into Drive takes three requests: reserve the file, `PUT` the bytes, then complete it.

```bash curl theme={null}
# 1. Reserve the file
curl https://public-api.revilico.bio/v1/drive/files \
  -H "Authorization: Bearer $REVILICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ligands.sdf", "sizeBytes": 48211, "contentType": "chemical/x-mdl-sdfile", "folderId": "dfld_a81c…" }'

# 2. PUT the bytes to upload.url with upload.headers
curl -X PUT "<upload.url>" \
  -H "Content-Type: chemical/x-mdl-sdfile" \
  -H "Content-Length: 48211" \
  --data-binary @ligands.sdf

# 3. Add it to Drive
curl -X POST https://public-api.revilico.bio/v1/drive/files/dfile_c40b…/complete \
  -H "Authorization: Bearer $REVILICO_API_KEY"
```

```python Python theme={null}
from pathlib import Path

path = Path("ligands.sdf")
reserved = session.post(
    f"{API}/drive/files",
    json={"name": path.name, "sizeBytes": path.stat().st_size, "folderId": "dfld_a81c…"},
).json()
requests.put(
    reserved["upload"]["url"], data=path.read_bytes(), headers=reserved["upload"]["headers"]
).raise_for_status()
drive_file = session.post(f"{API}/drive/files/{reserved['id']}/complete").json()
```

* The first response has the file's id, its final `name` and the `upload` to make. Send the `PUT` before `upload.expiresAt`.
* Complete checks the bytes are in place and the size matches. Until the `PUT` has finished it answers `409 CONFLICT`. Calling it again returns the file.
* Leave out `folderId` for the root. For a shared drive, give an `sdfld_…` folder or a `driveId`.
* If a file with that name is already there, it is renamed `name (1)`, `name (2)` and so on. Send `"onConflict": "error"` to get `409 CONFLICT` instead.

## Save an upload or a run output to Drive

`POST /v1/drive/import` copies an upload or a run's output into Drive as a new file, so it shows in the web app:

```bash theme={null}
curl https://public-api.revilico.bio/v1/drive/import \
  -H "Authorization: Bearer $REVILICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "run_3f2b…", "outputId": "results", "folderId": "dfld_a81c…" }'
```

| `from` | With |
| - | - |
| `file_…`, an upload | Nothing else |
| `run_…` | `outputId` from `GET /v1/runs/{runId}/outputs`, and optionally its `format`; or `path` from `GET /v1/runs/{runId}/files` |

`name` renames the copy, and `onConflict` works as for uploads. The copy is independent of the original.

## Organize

* **Create a folder:** `POST /v1/drive/folders` with a `name`, and a `parentId` or `driveId`. Names must be unique in their folder; a duplicate answers `409 CONFLICT`.
* **Rename or move:** `PATCH /v1/drive/items/{itemId}` with a new `name`, a `parentId` to move it into (`null` for the root), or both. You need edit access to the item and the destination. Items move only within the same drive: not between your Drive and a shared drive. Items linked to a project stay in that project.
* **Trash:** `DELETE /v1/drive/items/{itemId}` moves a file or folder, with everything in it, to the trash. Restore it from the web app's Trash. In your Drive it needs edit access. In a shared drive, managers can trash anything and contributors only files they added.

```bash theme={null}
curl -X PATCH https://public-api.revilico.bio/v1/drive/items/dfile_3d9e… \
  -H "Authorization: Bearer $REVILICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "round3-hits.sdf", "parentId": "dfld_e02f…" }'
```

There is no permanent delete in the API.

## Limits

| | Limit |
| - | - |
| Upload into Drive | 1 GB per file |
| Save an upload or run output to Drive | 5 GB per file |
| Text saved with the `save_to_drive` tool | 1 MB |
| Inline content | 1 MB, and 10,000 CSV or TSV rows |
| Names | 255 characters, without `/` or `\` |
| Page size (`limit`) | 50 by default, up to 200 |

## Not in this version

* Sharing Drive items, and managing shared-drive members.
* Restoring from the trash, and deleting permanently. Use the web app.
* Moving items between your Drive and a shared drive.
* Format conversions (RevScan) and editing (RevEdit).

## Scopes

| Action | Scope |
| - | - |
| Browse and read Drive and shared drives | `data:read` |
| Upload, save to Drive, create folders, rename, move and trash | `files:write` |
| Use a Drive file as a run input | `runs:write` and `data:read` |

## MCP tools

| Tool | Does |
| - | - |
| `list_drive` | Browses your Drive, a folder or a shared drive, and searches by name |
| `list_shared_drives` | Lists your shared drives and your role in each |
| `get_drive_file` | Describes a file |
| `read_drive_file` | Reads the start of a text file, with a download URL |
| `save_to_drive` | Saves an upload, a run output or file, or text into Drive |
| `create_drive_folder` | Creates a folder |
| `move_drive_item` | Renames or moves a file or folder |
| `trash_drive_item` | Moves a file or folder to the trash |

`create_run` accepts Drive file ids in `inputs`. For example: "Dock the ligands in screening/round3.sdf into my KRAS structure with RevScreen, then save the top hits to the same folder." See the [tools reference](https://docs.revilico.bio/developers/mcp/tools.md#drive) for each tool's arguments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.