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

MethodPathWhat it does
GET/v1/meThe caller and, when that user has been placed, the organization.
POST/v1/organizationsCreates the organization and the owner. Body: name, location, email, displayName.
GET/v1/organizationsOrganizations this caller belongs to.
GET/v1/organizations/{organization}One organization this caller belongs to.
GET/v1/organizations/{organization}/membersActive members.
GET/v1/organizations/{organization}/drivesDrives in the organization that this caller belongs to.
POST/v1/organizations/{organization}/drivesCreates a shared drive. Body: name.
GET/v1/organizations/{organization}/shared-drivesShared 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

MethodPathWhat it does
GET/v1/organizations/{organization}/tag-typesTypes, including retired ones. Any member.
POST/v1/organizations/{organization}/tag-typesCreates 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}/retireRetires a type. Owner. Stored tags still match.
GET/v1/organizations/{organization}/members/{user}/tagsTags on one member. A member may list their own. Another member is owner-only.
PUT/v1/organizations/{organization}/members/{user}/tagsReplaces that member’s tags. Owner.

Drives and members

MethodPathWhat it does
GET/v1/drives/{drive}One drive this caller may enter.
GET/v1/drives/{drive}/auditAllow 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}/membersAdds 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

MethodPathWhat it does
GET/v1/drives/{drive}/directories/rootThe root. It has no parent.
GET/v1/drives/{drive}/directoriesChild directories the caller can see. Omit parentId to list the root’s children.
GET/v1/drives/{drive}/directories/{directory}/contentVisible child directories and visible ready or unavailable files, one list. An item is { "kind", "directory" } or { "kind", "file" }.
POST/v1/drives/{drive}/directoriesCreates 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-protectionTurns the latch on or off. The root stays protected.
GET/v1/drives/{drive}/directories/{directory}/membersDrive members who can see the subtree. Manager.
PUT/v1/drives/{drive}/directories/{directory}/membersReplaces that list. An empty list adds no extra restriction.
GET/v1/drives/{drive}/directories/{directory}/tagsTags on the directory.
POST/v1/drives/{drive}/directories/{directory}/tagsApplies 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-matchBody { "tagMatch": "all" } or "any".

Files

MethodPathWhat it does
GET/v1/drives/{drive}/files?directoryId=ready and unavailable files in that directory. Each item includes indexStatus.
POST/v1/drives/{drive}/filesA 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}/commitBody byteSize and sha256.
POST/v1/drives/{drive}/files/{file}/downloadA short-lived URL for a ready file.
POST/v1/drives/{drive}/files/{file}/expandExpands 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-protectionTurns the latch on or off. This is not the hold flag.
GET/v1/drives/{drive}/files/{file}/tagsTags on the file.
POST/v1/drives/{drive}/files/{file}/tagsApplies 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-matchall 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.

MethodPathWhat it does
GET/v1/drives/{drive}/files/{file}/notesNotes on the file, oldest first.
POST/v1/drives/{drive}/files/{file}/notesAdds one. Editor. Body { "body" }.
GET/v1/drives/{drive}/directories/{directory}/notesNotes on the directory, oldest first.
POST/v1/drives/{drive}/directories/{directory}/notesAdds 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}/attachmentsStarts an upload. Body name, mediaType, optional byteSize, optional multipart.
POST/v1/drives/{drive}/notes/{note}/attachments/{attachment}/commitBody byteSize and sha256.
POST/v1/drives/{drive}/notes/{note}/attachments/{attachment}/downloadA short-lived URL.
DELETE/v1/drives/{drive}/notes/{note}/attachments/{attachment}Removes that attachment. The note stays.

Search, SQL, and shortcuts

MethodPathWhat it does
POST/v1/drives/{drive}/searchExact 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}/queryOne read statement over one directory or one file.
POST/v1/drives/{drive}/query/draftWrites one statement from a question, then runs it.
GET/v1/drives/{drive}/queriesStored queries for one directory or one file.
POST/v1/drives/{drive}/queriesSaves 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}/runRuns it. The rows are computed now.
GET/v1/drives/{drive}/shortcutsThis caller’s shortcuts, oldest first.
POST/v1/drives/{drive}/shortcutsBookmarks 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.