HTTP
Routes on api.contextdrive.io. One drive per call. Organization administration is a separate set.
Routes are under /v1. A drive route is /v1/drives/{drive}/…. The drive must be one this caller may enter. Organization administration does not fetch file bytes.
Shapes that repeat, including lists and problem documents, are on Call the API. The task in Drive is on the guides.
Caller and organization
| Method | Path | What it does |
|---|---|---|
GET | /v1/me | The caller and, when that user has been placed, the organization. |
POST | /v1/organizations | Creates the organization and the owner. Body: name, location, email, displayName. |
GET | /v1/organizations | Organizations this caller belongs to. |
GET | /v1/organizations/{organization} | One organization this caller belongs to. |
GET | /v1/organizations/{organization}/members | Active members. |
GET | /v1/organizations/{organization}/drives | Drives in the organization that this caller belongs to. |
POST | /v1/organizations/{organization}/drives | Creates a shared drive. Body: name. |
GET | /v1/organizations/{organization}/shared-drives | Shared drives. Owner only. Personal drives are absent. |
location is us_east, us_west, eu, or apac. v1 offers us_east.
Tag types and membership tags
| Method | Path | What it does |
|---|---|---|
GET | /v1/organizations/{organization}/tag-types | Types, including retired ones. Any member. |
POST | /v1/organizations/{organization}/tag-types | Creates a type. Owner. Body: name, description, optional values. |
PATCH | /v1/organizations/{organization}/tag-types/{tagType} | Replaces the name, description, and allowed values. Owner. A retired type cannot change. |
POST | /v1/organizations/{organization}/tag-types/{tagType}/retire | Retires a type. Owner. Stored tags still match. |
GET | /v1/organizations/{organization}/members/{user}/tags | Tags on one member. A member may list their own. Another member is owner-only. |
PUT | /v1/organizations/{organization}/members/{user}/tags | Replaces that member’s tags. Owner. |
Drives and members
| Method | Path | What it does |
|---|---|---|
GET | /v1/drives/{drive} | One drive this caller may enter. |
GET | /v1/drives/{drive}/audit | Allow and deny rows for this drive, newest first. A drive member. Each row has driveId, objectId, objectKind, and objectName from the decision. direction is desc or asc. Filters: action, principalId, decision, objectId, from, to. |
POST | /v1/drives/{drive}/members | Adds an organization member or changes their drive role. Body names the user and manager, editor, or viewer. Kind guest is rejected. |
DELETE | /v1/drives/{drive}/members/{user} | Removes a member. The caller is a manager of the drive. |
Directories
| Method | Path | What it does |
|---|---|---|
GET | /v1/drives/{drive}/directories/root | The root. It has no parent. |
GET | /v1/drives/{drive}/directories | Child directories the caller can see. Omit parentId to list the root’s children. |
GET | /v1/drives/{drive}/directories/{directory}/content | Visible child directories and visible ready or unavailable files, one list. An item is { "kind", "directory" } or { "kind", "file" }. |
POST | /v1/drives/{drive}/directories | Creates a child. Editor or manager. |
GET | /v1/drives/{drive}/directories/{directory} | One directory. |
PATCH | /v1/drives/{drive}/directories/{directory} | Renames, moves, or both. The root cannot change. |
DELETE | /v1/drives/{drive}/directories/{directory} | Deletes the directory and what is under it, when the latch allows. |
PATCH | /v1/drives/{drive}/directories/{directory}/deletion-protection | Turns the latch on or off. The root stays protected. |
GET | /v1/drives/{drive}/directories/{directory}/members | Drive members who can see the subtree. Manager. |
PUT | /v1/drives/{drive}/directories/{directory}/members | Replaces that list. An empty list adds no extra restriction. |
GET | /v1/drives/{drive}/directories/{directory}/tags | Tags on the directory. |
POST | /v1/drives/{drive}/directories/{directory}/tags | Applies one type-plus-value the caller holds. |
DELETE | /v1/drives/{drive}/directories/{directory}/tags/{tag} | Removes one tag. |
PUT | /v1/drives/{drive}/directories/{directory}/tag-match | Body { "tagMatch": "all" } or "any". |
Files
| Method | Path | What it does |
|---|---|---|
GET | /v1/drives/{drive}/files?directoryId= | ready and unavailable files in that directory. Each item includes indexStatus. |
POST | /v1/drives/{drive}/files | A pending file and an upload grant, or a transport zip when expand is true. |
GET | /v1/drives/{drive}/files/{file} | One file. A hidden file is not found. |
POST | /v1/drives/{drive}/files/{file}/commit | Body byteSize and sha256. |
POST | /v1/drives/{drive}/files/{file}/download | A short-lived URL for a ready file. |
POST | /v1/drives/{drive}/files/{file}/expand | Expands a ready zip. The zip stays. |
DELETE | /v1/drives/{drive}/files/{file} | Deletes, unless the file is held or protected. |
PATCH | /v1/drives/{drive}/files/{file}/deletion-protection | Turns the latch on or off. This is not the hold flag. |
GET | /v1/drives/{drive}/files/{file}/tags | Tags on the file. |
POST | /v1/drives/{drive}/files/{file}/tags | Applies one type-plus-value the caller holds. |
DELETE | /v1/drives/{drive}/files/{file}/tags/{tag} | Removes one tag. |
PUT | /v1/drives/{drive}/files/{file}/tag-match | all or any for this file’s own tags. |
One file sends directoryId, name, and mediaType. Leave expand absent or false. An optional byteSize binds the PUT content length. multipart: true asks for temporary credentials instead of a presigned PUT. The 201 body is the grant. For one file it includes the file. method is PUT for a signed URL, with url and headers. For several parts it includes a short-lived credential for that file. expiresAt is the end of the grant. The bytes go to that endpoint. Commit sends byteSize and sha256. The file becomes ready when the object exists and the size matches. indexStatus is unset until a build is claimed, then pending, ready, or failed.
A zip kept as one file is that same call. Several files are one zip, with expand: true. Omit name and mediaType. The grant writes one object. That id is an upload id, not a file id.
Expand uploads use /v1/drives/{drive}/files/uploads/{id} for get, …/commit, and delete. Delete refuses an upload that is expanding or finished. After commit, server places the entries in directoryId. A bare name is a file there. A path creates only the missing directories. Those directories start with deletion protection off. Poll until status is ready or failed. Values are pending, accepted, expanding, ready, and failed.
POST …/files/{file}/expand expands a ready zip and leaves the zip. A second request while the job is accepted or expanding returns the same job. POST …/download returns { "url", "expiresAt" }. The saved name is the name on the file row.
status is pending, ready, deleting, deleted, or unavailable. Listings show ready and unavailable.
Notes
A file response and a directory response leave notes out. A note on a list leaves attachments out. GET of one note includes them.
| Method | Path | What it does |
|---|---|---|
GET | /v1/drives/{drive}/files/{file}/notes | Notes on the file, oldest first. |
POST | /v1/drives/{drive}/files/{file}/notes | Adds one. Editor. Body { "body" }. |
GET | /v1/drives/{drive}/directories/{directory}/notes | Notes on the directory, oldest first. |
POST | /v1/drives/{drive}/directories/{directory}/notes | Adds one, including on the root. Editor. Body { "body" }. |
GET | /v1/drives/{drive}/notes/{note} | One note and its attachments. |
PUT | /v1/drives/{drive}/notes/{note} | Replaces the body. Editor. |
DELETE | /v1/drives/{drive}/notes/{note} | Deletes the note and its attachments. Editor. |
POST | /v1/drives/{drive}/notes/{note}/attachments | Starts an upload. Body name, mediaType, optional byteSize, optional multipart. |
POST | /v1/drives/{drive}/notes/{note}/attachments/{attachment}/commit | Body byteSize and sha256. |
POST | /v1/drives/{drive}/notes/{note}/attachments/{attachment}/download | A short-lived URL. |
DELETE | /v1/drives/{drive}/notes/{note}/attachments/{attachment} | Removes that attachment. The note stays. |
Search, SQL, and shortcuts
| Method | Path | What it does |
|---|---|---|
POST | /v1/drives/{drive}/search | Exact vector search. A hit is a visible file, including its notes, or a note on a visible directory. Optional directoryId is that directory only. |
POST | /v1/drives/{drive}/query | One read statement over one directory or one file. |
POST | /v1/drives/{drive}/query/draft | Writes one statement from a question, then runs it. |
GET | /v1/drives/{drive}/queries | Stored queries for one directory or one file. |
POST | /v1/drives/{drive}/queries | Saves a named statement. shared is false when omitted. |
GET | /v1/drives/{drive}/queries/{query} | One stored query the caller may run. |
PATCH | /v1/drives/{drive}/queries/{query} | Changes the name, the statement, or shared. Only the user who saved it. |
DELETE | /v1/drives/{drive}/queries/{query} | Deletes it. Only the user who saved it. |
POST | /v1/drives/{drive}/queries/{query}/run | Runs it. The rows are computed now. |
GET | /v1/drives/{drive}/shortcuts | This caller’s shortcuts, oldest first. |
POST | /v1/drives/{drive}/shortcuts | Bookmarks a directory or a file. Name exactly one of the two ids. |
GET | /v1/drives/{drive}/shortcuts/{shortcut} | Opens one shortcut. The allow is the target’s allow. |
DELETE | /v1/drives/{drive}/shortcuts/{shortcut} | Removes it. |
Search sends { "query" } and an optional directoryId. A hit is fileId, directoryId, path, span, text, and score. Exactly one of fileId and directoryId is set. A note’s span starts with the note id. A passage from an attachment names that attachment as well. limit and offset window the capped set. total is the size of that set.
Query sends one SELECT or one WITH, and either directoryId or fileId. How the relations are named, and how the page is read, is on SQL. Draft sends question and adds statement to that result. POST /v1/drives/{drive}/queries/{query}/run returns the same fields.
A stored query names the statement and exactly one of fileId and directoryId. shared is false when omitted.
A later feature is another route under /v1/drives/{drive}/{feature} and another screen in Drive. It does not get a new host or a new permission function.