Skip to main content

AutessaDB Drive API

Programmatic access to an AutessaDB Drive: list and find files, grep their text and run ranked search over it (meaning-based when semantic search is on), read exact pages and lines, upload whole folders, and share files and folders with people, teams, your company, or a link.

Every request is a POST with a JSON body to https://api.autessa.com/clients/autessadb-drive/<operation>, with the Drive's ID in the resourceId query parameter and your API key in the Authorization header (no Bearer prefix). The body's tableId must match resourceId.

Permissions​

Two layers apply to every call:

  1. The API key's permission on the Drive, as for any table: READ for browsing, searching, reading, and downloading; WRITE for uploads, folders, moves, trash and restore, versions, sharing, and links; DELETE for permanent deletion.
  2. Sharing inside the Drive. Requests run under the key's acting identity and only reach the files and folders that identity can open, with the role it has on each (Owner, Editor, or Viewer). Items it cannot open behave as if they do not exist. See Sharing.

Paths​

Paths are absolute and start with /, for example /Shared/Legal/Contracts/acme-msa.pdf. Backslashes are treated as /, repeated slashes are collapsed, and . and .. segments are rejected. Names are compared without regard to case, are at most 255 bytes, and paths are at most 64 levels deep. The Drive's root is /; a new Drive is empty, and every folder in it is one someone created.

Calls that take an item accept either path or nodeId; calls that take several items accept paths or nodeIds. An item's nodeId never changes, even when it is moved or renamed.

The item object​

Listings, searches, and most write calls return items in this shape:

  • Name
    nodeId
    Type
    string
    Description

    The item's ID (a decimal string).

  • Name
    path
    Type
    string
    Description

    Current absolute path.

  • Name
    name
    Type
    string
    Description

    The last segment of the path.

  • Name
    nodeType
    Type
    string
    Description

    FILE or FOLDER.

  • Name
    parentId
    Type
    string
    Description

    ID of the containing folder, or null at the top level.

  • Name
    sizeBytes
    Type
    integer
    Description

    File size. Files only.

  • Name
    mimeType
    Type
    string
    Description

    File type. Files only.

  • Name
    version
    Type
    integer
    Description

    Current version number, starting at 1. Files only.

  • Name
    contentUpdatedAt
    Type
    string
    Description

    When the file's content last changed (ISO-8601 UTC). Files only.

  • Name
    updatedAt
    Type
    string
    Description

    When the item last changed, including renames and moves.

  • Name
    ownerUserId
    Type
    string
    Description

    The owner's user ID.

  • Name
    ownerName
    Type
    string
    Description

    The owner's name.

  • Name
    extractionStatus
    Type
    string
    Description

    Files only: PENDING or EXTRACTING while text is being extracted, EXTRACTED when it is searchable, FAILED, UNSUPPORTED (no extractable text), or TOO_LARGE (only the first part is searchable).

  • Name
    trashedAt
    Type
    string
    Description

    When the item was trashed. Present only when listing with includeTrashed.

  • Name
    customColumns
    Type
    object
    Description

    Values of any custom columns you added to the Drive, as a map of column name to typed column value (the same shape as AutessaDB rows).

Paging and truncation​

Nothing is dropped silently. Every listing and search response says whether it is complete:

  • truncated is false when you have everything, or a string naming the cap that stopped it: "limit" (page full), "max_entries" (tree size), "max_matches_per_file" (grep per-file cap), or "timeout" (grep time budget).
  • nextCursor continues from where the response stopped. Send it back as cursor with the same other arguments; a cursor replayed with different arguments is rejected with INVALID_CURSOR.

Uploading files​

Uploads take three steps, so file bytes go straight to storage and large files can be sent in parallel parts:

  1. Start uploads with the paths and sizes. Storage is reserved and each file gets an upload link.
  2. PUT each file's bytes to its url with the returned headers, or for multipart uploads, PUT each part to its part link and then complete it.
  3. Commit the finished uploads. Files appear in the Drive and processing starts.

The CLI wraps all three steps in autessa autessadb drive push and upload.

List a folder​

POST/ls

Lists the direct children of a folder: folders first, then files, each group sorted by the chosen order. Only items the caller can open are returned. Omit both path and nodeId to list the top level of the Drive (or of the folder an agent tool is scoped to).

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the item, e.g. /Contracts/acme-msa.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID. Takes precedence over path when both are sent.

  • Name
    sort
    Type
    string
    Description

    name (default), modified, or size. Folders always come first.

  • Name
    includeTrashed
    Type
    boolean
    Description

    Include items in the trash. Default false.

  • Name
    limit
    Type
    integer
    Description

    Maximum entries to return. Default 200, maximum 1000.

  • Name
    cursor
    Type
    string
    Description

    The nextCursor from the previous page. Send the same other arguments as the first call.

Response​

  • Name
    driveRole
    Type
    string
    Description

    Your Drive membership: OWNER (the Drive's owner or a Drive admin), EDITOR or VIEWER (a member: the Drive itself is shared with you), or NONE (only items inside it are shared with you). Membership does not show any item by itself: members see what they own and what is shared with them. OWNER and EDITOR can add items at the top level.

  • Name
    folder
    Type
    object
    Description

    The folder being listed, or null for the top level.

  • Name
    items
    Type
    array<object>
    Description

    The folder's children. See The item object.

  • Name
    nextCursor
    Type
    string
    Description

    Cursor for the next page, or null when there is nothing more.

  • Name
    truncated
    Type
    boolean | string
    Description

    false when the response is complete; otherwise the reason it stopped early. See Paging and truncation.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/ls?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "path": "/Shared/Legal/Contracts",
    "limit": 2
  }'
Response
{
  "folder": {
    "nodeId": "4170",
    "path": "/Shared/Legal/Contracts",
    "name": "Contracts",
    "nodeType": "FOLDER",
    "parentId": "4101",
    "updatedAt": "2026-09-21T09:12:40Z",
    "owner": {
      "userId": "u8Kd2LmQ4x",
      "name": "Dana Ortiz"
    }
  },
  "items": [
    {
      "nodeId": "4190",
      "path": "/Shared/Legal/Contracts/Archive",
      "name": "Archive",
      "nodeType": "FOLDER",
      "parentId": "4170",
      "updatedAt": "2026-09-21T09:12:40Z",
      "owner": {
        "userId": "u8Kd2LmQ4x",
        "name": "Dana Ortiz"
      }
    },
    {
      "nodeId": "4182",
      "path": "/Shared/Legal/Contracts/acme-msa.pdf",
      "name": "acme-msa.pdf",
      "nodeType": "FILE",
      "parentId": "4170",
      "sizeBytes": 482113,
      "mimeType": "application/pdf",
      "version": 2,
      "contentUpdatedAt": "2026-09-28T17:04:11Z",
      "updatedAt": "2026-09-28T17:04:11Z",
      "owner": {
        "userId": "u8Kd2LmQ4x",
        "name": "Dana Ortiz"
      },
      "extractionStatus": "EXTRACTED"
    }
  ],
  "nextCursor": "eyJrIjpbImFjbWUtbXNhLnBkZiIsNDE4Ml19",
  "truncated": "limit"
}

Get a folder tree​

POST/tree

Returns a folder and its descendants down to a depth, as a flat list in path order. Useful for getting an overview of a folder in one call.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Folder to start from. Defaults to the top level.

  • Name
    maxDepth
    Type
    integer
    Description

    Levels below path to include. Default 3, maximum 20.

  • Name
    maxEntries
    Type
    integer
    Description

    Maximum entries to return. Default 500, maximum 5000.

Response​

  • Name
    root
    Type
    string
    Description

    The starting path.

  • Name
    entries
    Type
    array<object>
    Description

    One entry per item: nodeId, path, nodeType, depth (relative to root), and for files sizeBytes.

  • Name
    truncated
    Type
    boolean | string
    Description

    "max_entries" if more items exist than were returned.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/tree?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "path": "/Shared/Legal",
    "maxDepth": 2
  }'
Response
{
  "root": "/Shared/Legal",
  "entries": [
    {
      "nodeId": "4170",
      "path": "/Shared/Legal/Contracts",
      "nodeType": "FOLDER",
      "depth": 1
    },
    {
      "nodeId": "4182",
      "path": "/Shared/Legal/Contracts/acme-msa.pdf",
      "nodeType": "FILE",
      "depth": 2,
      "sizeBytes": 482113
    },
    {
      "nodeId": "4175",
      "path": "/Shared/Legal/Policies",
      "nodeType": "FOLDER",
      "depth": 1
    }
  ],
  "truncated": false
}

Find items​

POST/find

Finds files and folders by name, pattern, type, date, or size anywhere under a folder. Glob patterns support *, ** (any number of folders), ?, character classes like [0-9], and alternatives like {pdf,docx}. A pattern with no / (such as *.pdf) matches the name at any depth.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Folder to search under. Defaults to everything the caller can see.

  • Name
    glob
    Type
    string
    Description

    Glob pattern matched against paths, e.g. **/2026/*.pdf or invoice-*.

  • Name
    nameRegex
    Type
    string
    Description

    Regular expression matched against names.

  • Name
    type
    Type
    string
    Description

    FILE or FOLDER.

  • Name
    mime
    Type
    string
    Description

    Exact MIME type, or a prefix ending in /, e.g. image/.

  • Name
    modifiedAfter
    Type
    string
    Description

    ISO-8601 UTC timestamp. Only items modified at or after it.

  • Name
    modifiedBefore
    Type
    string
    Description

    ISO-8601 UTC timestamp. Only items modified before it.

  • Name
    sizeGt
    Type
    integer
    Description

    Minimum file size in bytes.

  • Name
    sizeLt
    Type
    integer
    Description

    Maximum file size in bytes.

  • Name
    limit
    Type
    integer
    Description

    Maximum entries to return. Default 200, maximum 1000.

  • Name
    cursor
    Type
    string
    Description

    The nextCursor from the previous page. Send the same other arguments as the first call.

Response​

  • Name
    items
    Type
    array<object>
    Description

    Matching items in path order. See The item object.

  • Name
    nextCursor
    Type
    string
    Description

    Cursor for the next page, or null when there is nothing more.

  • Name
    truncated
    Type
    boolean | string
    Description

    false when the response is complete; otherwise the reason it stopped early. See Paging and truncation.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/find?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "path": "/Shared/Legal",
    "glob": "*.pdf",
    "modifiedAfter": "2026-09-01T00:00:00Z"
  }'
Response
{
  "items": [
    {
      "nodeId": "4182",
      "path": "/Shared/Legal/Contracts/acme-msa.pdf",
      "name": "acme-msa.pdf",
      "nodeType": "FILE",
      "parentId": "4170",
      "sizeBytes": 482113,
      "mimeType": "application/pdf",
      "version": 2,
      "contentUpdatedAt": "2026-09-28T17:04:11Z",
      "updatedAt": "2026-09-28T17:04:11Z",
      "owner": {
        "userId": "u8Kd2LmQ4x",
        "name": "Dana Ortiz"
      },
      "extractionStatus": "EXTRACTED"
    }
  ],
  "nextCursor": null,
  "truncated": false
}

Get item details​

POST/stat

Returns one item with its processing status, page and line counts, recent versions, and the caller's role on it. Callers who can manage sharing on the item also get its shares.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the item, e.g. /Contracts/acme-msa.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID. Takes precedence over path when both are sent.

Response​

The item's own fields (nodeId, path, name, nodeType, sizeBytes, version, …) at the top level, as in The item object, plus:

  • Name
    effectiveRole
    Type
    string
    Description

    The caller's effective role: OWNER, EDITOR, or VIEWER.

  • Name
    extraction
    Type
    object
    Description

    For files: status, indexStatus, textKind (NATIVE for text files with real line numbers, PAGED for documents extracted page by page), pageCount, lineCount, ocrNeededPages (scanned pages OCR was unsure of), ocrStatus (DONE when scanned pages were read by OCR, otherwise NONE), and ocr: engine, pagesOcr (pages read by OCR), pagesLowConfidence and lowConfidencePages (pages read with low confidence; their text is kept as read and is searchable), and pagesUnreadable and unreadablePages (pages with no searchable text).

  • Name
    versionsCount
    Type
    integer
    Description

    How many previous versions the file has. List them with List versions.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/stat?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "path": "/Shared/Legal/Contracts/acme-msa.pdf"
  }'
Response
{
  "nodeId": "4182",
  "path": "/Shared/Legal/Contracts/acme-msa.pdf",
  "name": "acme-msa.pdf",
  "parentId": "4170",
  "nodeType": "FILE",
  "depth": 4,
  "sizeBytes": 482113,
  "mimeType": "application/pdf",
  "version": 2,
  "contentUpdatedAt": "2026-09-28T17:04:11Z",
  "ownerUserId": "u8Kd2LmQ4x",
  "ownerName": "Dana Ortiz",
  "updatedAt": "2026-09-28T17:04:11Z",
  "extractionStatus": "EXTRACTED",
  "extraction": {
    "status": "EXTRACTED",
    "indexStatus": "NONE",
    "textKind": "PAGED",
    "pageCount": 14,
    "lineCount": 612,
    "ocrNeededPages": [9],
    "ocrStatus": "DONE",
    "ocr": {
      "engine": "tesseract",
      "pagesOcr": 3,
      "pagesLowConfidence": 1,
      "pagesUnreadable": 0,
      "lowConfidencePages": [9],
      "unreadablePages": []
    }
  },
  "versionsCount": 1,
  "effectiveRole": "EDITOR"
}

Search exact text​

POST/grep

Finds lines that contain a string or match a regular expression, across every searchable file under a folder. Matching is per line. Each match carries its page and line, so you can read around it or cite it. Files that are not searchable yet are counted in stats.filesUnsearchable rather than silently skipped.

Regular expressions support character classes, \d, \w, \s, alternation, anchors, and quantifiers. A regular expression must contain at least 3 literal characters unless the search is scoped to 2,000 files or fewer.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    pattern
    Type
    string
    Description

    Text or regular expression to find. Up to 1,000 characters.

  • Name
    regex
    Type
    boolean
    Description

    Treat pattern as a regular expression. Default false (literal text).

  • Name
    caseInsensitive
    Type
    boolean
    Description

    Ignore case. Default false.

  • Name
    path
    Type
    string
    Description

    Folder or file to search. Defaults to everything the caller can see.

  • Name
    glob
    Type
    string
    Description

    Only search files whose path matches this glob, e.g. *.pdf.

  • Name
    outputMode
    Type
    string
    Description

    matches (default) returns each matching line; files returns only the files with a match; count returns the match count per file.

  • Name
    context
    Type
    integer
    Description

    Lines of context before and after each match, 0 to 10. Default 0.

  • Name
    maxMatchesPerFile
    Type
    integer
    Description

    Maximum matches returned per file. Default 20.

  • Name
    timeoutMs
    Type
    integer
    Description

    Time budget in milliseconds. Default 5000, maximum 15000.

  • Name
    limit
    Type
    integer
    Description

    Maximum entries to return. Default 100, maximum 1000.

  • Name
    cursor
    Type
    string
    Description

    The nextCursor from the previous page. Send the same other arguments as the first call.

Response​

  • Name
    matches
    Type
    array<object>
    Description

    In matches mode: nodeId, path, version, page and pageLine (for paged documents), line, text, submatches (character start/end of each hit in text), and before/after context lines.

  • Name
    files
    Type
    array<object>
    Description

    In files mode: files, each with nodeId, path and matchCount; in count mode: count with files and matches.

  • Name
    stats
    Type
    object
    Description

    filesUnsearchable: counts of files in scope that could not be searched, by reason (pending, failed, unsupported, tooLarge), with samplePaths.

  • Name
    nextCursor
    Type
    string
    Description

    Cursor for the next page, or null when there is nothing more.

  • Name
    truncated
    Type
    boolean | string
    Description

    false when the response is complete; otherwise the reason it stopped early. See Paging and truncation.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/grep?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "pattern": "termination for convenience",
    "caseInsensitive": true,
    "path": "/Shared/Legal",
    "context": 1
  }'
Response
{
  "matches": [
    {
      "nodeId": "4182",
      "path": "/Shared/Legal/Contracts/acme-msa.pdf",
      "version": 2,
      "page": 4,
      "pageLine": 12,
      "line": 171,
      "text": "12.2 Termination for Convenience. Either party may terminate this Agreement",
      "submatches": [
        {
          "start": 5,
          "end": 32
        }
      ],
      "before": [
        "12.1 Term. This Agreement begins on the Effective Date."
      ],
      "after": [
        "upon sixty (60) days written notice to the other party."
      ]
    }
  ],
  "stats": {
    "filesUnsearchable": {
      "pending": 1,
      "failed": 0,
      "unsupported": 0,
      "tooLarge": 0,
      "samplePaths": [
        "/Shared/Legal/Contracts/globex-sow.docx"
      ]
    }
  },
  "nextCursor": null,
  "truncated": false
}

Read a file​

POST/read

Returns a file's extracted text for a page range or a line range. Use it to read around a match before quoting. A single call returns at most 20 pages or 2,000 lines, and at most maxChars characters; when the range is cut short, nextRange tells you where to continue.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the item, e.g. /Contracts/acme-msa.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID. Takes precedence over path when both are sent.

  • Name
    pages
    Type
    string
    Description

    Page range for paged documents, e.g. "4" or "3-5".

  • Name
    lines
    Type
    string
    Description

    Line range, e.g. "100-250". Send pages or lines; with neither, reading starts at the beginning.

  • Name
    maxChars
    Type
    integer
    Description

    Maximum characters to return. Default 20,000, maximum 100,000.

Response​

  • Name
    path
    Type
    string
    Description

    The file's current path.

  • Name
    version
    Type
    integer
    Description

    The version that was read.

  • Name
    kind
    Type
    string
    Description

    NATIVE or PAGED.

  • Name
    lines
    Type
    array<object>
    Description

    The lines read: line, text, and for paged documents page and pageLine. Empty lines are included with empty text.

  • Name
    nextRange
    Type
    string
    Description

    The range to request next, or null at the end of the file.

  • Name
    truncated
    Type
    boolean | string
    Description

    "limit" when the range was cut short by maxChars or the per-call caps.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/read?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "path": "/Shared/Legal/Contracts/acme-msa.pdf",
    "pages": "4"
  }'
Response
{
  "path": "/Shared/Legal/Contracts/acme-msa.pdf",
  "version": 2,
  "kind": "PAGED",
  "lines": [
    {
      "line": 160,
      "page": 4,
      "pageLine": 1,
      "text": "12. TERM AND TERMINATION"
    },
    {
      "line": 171,
      "page": 4,
      "pageLine": 12,
      "text": "12.2 Termination for Convenience. Either party may terminate this Agreement"
    }
  ],
  "nextRange": "5",
  "truncated": false
}

Search file contents​

POST/search

Ranked keyword search over file contents; meaning-based when the Drive's Semantic search setting is on. Each result is a passage with its page and line range and a snippet.

  • Semantic search off (the default): files that contain more of the query's words rank first, then files with more matches, earlier pages, and matching names. Common words are ignored. Snippets mark the matched words as **word**, results have source: "keyword", and stats.mode is keyword. Every mode behaves this way.
  • Semantic search on: hybrid (the default) combines meaning-based and keyword ranking, which works well for both questions and specific terms. Semantic search usage counts toward your company's search limits.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    query
    Type
    string
    Description

    What to look for, in plain language or keywords.

  • Name
    mode
    Type
    string
    Description

    hybrid (default), semantic (meaning only), lexical (keywords only), or keyword. Applies when semantic search is on; otherwise every mode is a ranked keyword search.

  • Name
    path
    Type
    string
    Description

    Folder or file to search. Defaults to everything the caller can see.

  • Name
    glob
    Type
    string
    Description

    Only search files whose path matches this glob.

  • Name
    topK
    Type
    integer
    Description

    Number of results. Default 10, maximum 50.

Response​

  • Name
    results
    Type
    array<object>
    Description

    Best passages first: nodeId, path, score, page (for paged documents), lineStart, lineEnd, snippet, and source (keyword, or with semantic search on hybrid, dense, or bm25).

  • Name
    stats
    Type
    object
    Description

    How the search ran, including mode (keyword when semantic search is off).

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/search?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "query": "can either side end the contract early?",
    "path": "/Shared/Legal/Contracts",
    "topK": 3
  }'
Response
{
  "results": [
    {
      "nodeId": "4182",
      "path": "/Shared/Legal/Contracts/acme-msa.pdf",
      "score": 0.83,
      "page": 4,
      "lineStart": 168,
      "lineEnd": 179,
      "snippet": "12.2 Termination for Convenience. Either party may terminate this Agreement upon sixty (60) days written notice...",
      "source": "hybrid"
    }
  ],
  "stats": {
    "mode": "hybrid"
  }
}
POST/download-url

Returns a short-lived link to download a file's content, or one of its previous versions.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the item, e.g. /Contracts/acme-msa.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID. Takes precedence over path when both are sent.

  • Name
    version
    Type
    integer
    Description

    A previous version to download. Defaults to the current version.

Response​

  • Name
    url
    Type
    string
    Description

    The download link.

  • Name
    expiresAt
    Type
    string
    Description

    When the link stops working (ISO-8601 UTC).

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/download-url?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "nodeId": "4182"
  }'
Response
{
  "url": "https://files.autessa.com/d/9f3c1a7e...",
  "expiresAt": "2026-10-02T15:10:00Z"
}

Fetch a file​

POST/fetch

Returns a 10-minute download link for a file, or one of its previous versions, together with the file's name, type, size and version. Same as /download-url, which stays available, plus the file's details.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the file, e.g. /Reports/q1.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The file's ID.

  • Name
    version
    Type
    integer
    Description

    A previous version. Defaults to the current version.

Response​

  • Name
    url
    Type
    string
    Description

    The download link, valid for 10 minutes.

  • Name
    expiresAt
    Type
    string
    Description

    When the link stops working (ISO-8601 UTC).

  • Name
    nodeId
    Type
    string
    Description

    The file's ID.

  • Name
    path
    Type
    string
    Description

    The file's path.

  • Name
    name
    Type
    string
    Description

    The file's name.

  • Name
    mime
    Type
    string
    Description

    MIME type of the version served.

  • Name
    sizeBytes
    Type
    integer
    Description

    Size of the version served.

  • Name
    version
    Type
    integer
    Description

    The version served.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/fetch?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tableId": "V1StGXR8Z5", "path": "/Reports/q1.pdf"}'
Response
{
  "url": "https://files.autessa.com/d/9f3c1a7e...",
  "expiresAt": "2026-10-03T15:10:00Z",
  "nodeId": "4182",
  "path": "/Reports/q1.pdf",
  "name": "q1.pdf",
  "mime": "application/pdf",
  "sizeBytes": 248112,
  "version": 2
}

Get processing status​

POST/status

Summarizes how many files in the Drive are searchable, still processing, or not searchable. Use it after a large upload to wait until everything is searchable.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

Response​

  • Name
    extraction
    Type
    object
    Description

    File counts by text status (PENDING, EXTRACTING, EXTRACTED, FAILED, UNSUPPORTED, TOO_LARGE).

  • Name
    index
    Type
    object
    Description

    File counts by semantic-search index status (used only while the Drive's semantic search is on).

  • Name
    files
    Type
    integer
    Description

    Files in the Drive.

  • Name
    folders
    Type
    integer
    Description

    Folders in the Drive.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/status?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5"
  }'
Response
{
  "extraction": {
    "PENDING": 0,
    "EXTRACTING": 2,
    "EXTRACTED": 318,
    "FAILED": 1,
    "UNSUPPORTED": 4,
    "TOO_LARGE": 0
  },
  "index": {
    "NONE": 325
  },
  "files": 325,
  "folders": 41
}

Get storage usage​

POST/usage

Returns your company's Drive storage and processing usage against its limits.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

Response​

  • Name
    bytesUsed
    Type
    integer
    Description

    Bytes stored, including previous versions and trash.

  • Name
    bytesLimit
    Type
    integer
    Description

    Storage allowance in bytes.

  • Name
    filesCount
    Type
    integer
    Description

    Files in the Drive.

  • Name
    maxFileBytes
    Type
    integer
    Description

    Largest file you can upload, in bytes.

  • Name
    extractedPagesThisMonth
    Type
    integer
    Description

    Pages extracted this calendar month.

  • Name
    extractedPagesLimit
    Type
    integer
    Description

    Monthly page allowance, or null if unlimited.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/usage?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5"
  }'
Response
{
  "bytesUsed": 18253611008,
  "bytesLimit": 53687091200,
  "filesCount": 12408,
  "maxFileBytes": 5368709120,
  "extractedPagesThisMonth": 4120,
  "extractedPagesLimit": 50000
}

Write a file​

POST/write

Writes text to a file: creates it, replaces its content, or appends to its end. Missing folders are created. A replaced file keeps its previous content in its version history, and the new text is searchable with grep as soon as the call returns. Text files only (by extension or MIME type), up to 5 MB; upload anything else with uploads.

Permission: WRITE, and Editor on the file (or on its folder for a new file)

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the file, e.g. /Shared/notes/memory.md.

  • Name
    content
    Type
    string
    Description

    The text, UTF-8. Absent or empty writes an empty file.

  • Name
    mode
    Type
    string
    Description

    overwrite (default) replaces the file, creating it when missing. create fails with NAME_CONFLICT when the file exists. append adds content to the end, starting a new line when the file does not end with one, and creates the file when missing.

  • Name
    mime
    Type
    string
    Description

    MIME type. Default: the existing file's, else inferred from the extension (.md text/markdown, .json application/json, .csv text/csv), else text/plain.

  • Name
    expectedVersion
    Type
    integer
    Description

    Only write when the file is still at this version (0: it must not exist yet). Otherwise the call fails with VERSION_CONFLICT, and error.details.currentVersion holds the current version.

Response​

  • Name
    node
    Type
    object
    Description

    The file after the write (see The item object).

  • Name
    version
    Type
    integer
    Description

    The file's version after the write (1 for a new file).

  • Name
    bytes
    Type
    integer
    Description

    Size of the file after the write.

  • Name
    created
    Type
    boolean
    Description

    true when the write created the file.

  • Name
    mode
    Type
    string
    Description

    The mode applied.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/write?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tableId": "V1StGXR8Z5", "path": "/Shared/notes/memory.md", "content": "- Acme prefers Net 45", "mode": "append"}'
Response
{
  "node": { "nodeId": "5120", "path": "/Shared/notes/memory.md", "version": 4, "mimeType": "text/markdown" },
  "version": 4,
  "bytes": 112,
  "created": false,
  "mode": "append"
}

Edit a file​

POST/edit

Replaces an exact piece of text in a text file, like an editor's find-and-replace. oldText must occur exactly once unless replaceAll is true. The change is saved as a new version. Files with Windows line endings also match an oldText written with plain line breaks. Text files up to 5 MB.

Permission: WRITE, and Editor on the file

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the file. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The file's ID.

  • Name
    oldText
    Type
    string
    Description

    The exact text to replace, including spaces and line breaks.

  • Name
    newText
    Type
    string
    Description

    The replacement. An empty string deletes oldText.

  • Name
    replaceAll
    Type
    boolean
    Description

    Replace every occurrence instead of requiring exactly one. Default false.

  • Name
    expectedVersion
    Type
    integer
    Description

    Only edit when the file is still at this version; otherwise VERSION_CONFLICT.

Response​

  • Name
    node
    Type
    object
    Description

    The file after the edit.

  • Name
    version
    Type
    integer
    Description

    The file's new version.

  • Name
    replacements
    Type
    integer
    Description

    How many places were changed.

  • Name
    bytes
    Type
    integer
    Description

    Size of the file after the edit.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/edit?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tableId": "V1StGXR8Z5", "path": "/Shared/notes/plan.md", "oldText": "Status: draft", "newText": "Status: approved"}'
Response
{
  "node": { "nodeId": "5121", "path": "/Shared/notes/plan.md", "version": 3 },
  "version": 3,
  "replacements": 1,
  "bytes": 2048
}

Create folders​

POST/mkdir

Creates one or more folders, along with any missing parent folders. Existing folders are left as they are, so the call is safe to repeat.

Permission: WRITE, and Editor on the parent folder

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    paths
    Type
    array<string>
    Description

    Folders to create (up to 1,000), e.g. ["/Shared/Reports/2026"].

  • Name
    parents
    Type
    boolean
    Description

    Create missing parent folders too. Default true.

Response​

  • Name
    folders
    Type
    array<object>
    Description

    Every requested folder, existing or new. See The item object.

  • Name
    created
    Type
    array<object>
    Description

    The folders this call created.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/mkdir?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "paths": [
      "/Shared/Legal/Contracts/2026/Q4",
      "/Shared/Legal/Contracts/2026/Q3"
    ]
  }'
Response
{
  "created": [
    {
      "nodeId": "4201",
      "paths": ["/Shared/Legal/Contracts/2026"],
      "name": "2026",
      "nodeType": "FOLDER",
      "parentId": "4101",
      "updatedAt": "2026-09-21T09:12:40Z",
      "owner": {
        "userId": "u8Kd2LmQ4x",
        "name": "Dana Ortiz"
      }
    },
    {
      "nodeId": "4202",
      "paths": ["/Shared/Legal/Contracts/2026/Q4"],
      "name": "Q4",
      "nodeType": "FOLDER",
      "parentId": "4201",
      "updatedAt": "2026-09-21T09:12:40Z",
      "owner": {
        "userId": "u8Kd2LmQ4x",
        "name": "Dana Ortiz"
      }
    },
    {
      "nodeId": "4203",
      "paths": ["/Shared/Legal/Contracts/2026/Q3"],
      "name": "Q3",
      "nodeType": "FOLDER",
      "parentId": "4201",
      "updatedAt": "2026-09-21T09:12:40Z",
      "owner": {
        "userId": "u8Kd2LmQ4x",
        "name": "Dana Ortiz"
      }
    }
  ]
}

Move or rename​

POST/move

Moves an item into another folder, renames it, or both. Moving a folder moves everything inside it.

Because access follows folders, a move can change who sees the item. If it would, and confirm is not true, nothing moves and the response lists who would gain and lose access; repeat the call with confirm: true to go ahead. A folder that contains items the caller cannot see cannot be moved by that caller.

Permission: WRITE, Editor on the item, and Editor on the destination folder

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    paths
    Type
    array<string>
    Description

    Paths of the items to move, e.g. ["/Inbox/acme-msa.pdf"]. Send paths, nodeIds, or both. With one item named by path and a destinationPath that does not exist yet (inside an existing folder), the item is moved there under that name, like mv a b.

  • Name
    nodeIds
    Type
    array<string>
    Description

    IDs of the items to move.

  • Name
    destinationPath
    Type
    string
    Description

    The folder to move into.

  • Name
    newName
    Type
    string
    Description

    New name, when moving a single item.

  • Name
    confirm
    Type
    boolean
    Description

    Proceed even if the move changes who has access. Default false.

Response​

  • Name
    moved
    Type
    array<object>
    Description

    The moved items at their new paths, when the move happened.

  • Name
    requiresConfirmation
    Type
    boolean
    Description

    true when nothing moved because access would change.

  • Name
    accessChanges
    Type
    object
    Description

    gaining and losing: the people, teams, and company-wide shares that would gain or lose access, each with their role and the folder it comes from.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/move?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "paths": ["/Drafts/globex-sow.docx"],
    "destinationPath": "/Shared/Legal/Contracts"
  }'
Response (confirmation needed)
{
  "requiresConfirmation": true,
  "accessChanges": {
    "gaining": [
      {
        "principal": {
          "type": "TEAM",
          "teamId": "3b1f6a2e-7c41-4d55-9a0e-58c2b7f1d903",
          "name": "Legal"
        },
        "role": "EDITOR"
      }
    ],
    "losing": []
  }
}

Move to trash​

POST/trash

Moves items to the trash. A trashed folder takes everything inside it along. Trashed items keep their shares, are hidden from listings and search, and can be restored until the trash retention period ends.

Permission: WRITE, and Editor on each item

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    paths
    Type
    array<string>
    Description

    Paths of the items to trash. Send paths, nodeIds, or both.

  • Name
    nodeIds
    Type
    array<string>
    Description

    IDs of the items to trash.

  • Name
    permanent
    Type
    boolean
    Description

    Delete the items for good right after trashing them; they cannot be restored. Needs the key's DELETE permission. Default false.

Response​

  • Name
    trashed
    Type
    integer
    Description

    How many items were trashed.

  • Name
    items
    Type
    array<object>
    Description

    The trashed items.

  • Name
    purged
    Type
    integer
    Description

    With permanent: rows deleted for good, including everything inside folders.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/trash?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "nodeIds": [
      "4182",
      "4190"
    ]
  }'
Response
{
  "trashed": 2,
  "items": [
    { "nodeId": "4182", "path": "/Shared/Legal/Contracts/acme-msa.pdf", "nodeType": "FILE" },
    { "nodeId": "4190", "path": "/Shared/Legal/Contracts/Archive", "nodeType": "FOLDER" }
  ]
}

Restore from trash​

POST/restore

Restores trashed items to their original paths. If something now occupies a path, the restored item gets a numbered name. Missing parent folders are recreated.

Permission: WRITE, and Editor on each item

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    nodeIds
    Type
    array<string>
    Description

    Trashed items to restore.

Response​

  • Name
    restored
    Type
    array<object>
    Description

    One entry per item: nodeId and path (the final path, which differs from the original if it was renamed).

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/restore?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "nodeIds": [
      "4190"
    ]
  }'
Response
{
  "restored": [
    {
      "nodeId": "4190",
      "path": "/Shared/Legal/Contracts/Archive"
    }
  ]
}

Delete permanently​

POST/purge

Permanently deletes trashed items, their versions, and their shares and links. This cannot be undone. To empty the trash, call /empty-trash (no other arguments).

Permission: DELETE, and Owner on each item (or Drive manager)

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    nodeIds
    Type
    array<string>
    Description

    Trashed items to delete.

Response​

  • Name
    purged
    Type
    integer
    Description

    Items permanently deleted, including folder contents.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/purge?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "nodeIds": [
      "4182"
    ]
  }'
Response
{
  "purgedCount": 1,
  "bytesFreed": 962033
}

Start uploads​

POST/uploads/create

Registers up to 1,000 files to upload and returns where to send each one. Paths, permissions, file size, and storage are checked up front, and storage is reserved, so a file that cannot be stored is refused before you send it. Files up to 100 MB use one PUT to url; larger files use multipart upload with part links. Then commit the finished uploads.

Permission: WRITE, and Editor on each destination folder

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    basePath
    Type
    string
    Description

    Folder that relative files[].path values are resolved against. Missing folders are created on commit.

  • Name
    conflict
    Type
    string
    Description

    What to do when a file already exists at a path: FAIL (default), RENAME (keep both, adding a number), or NEW_VERSION (replace, keeping the old content as a version).

  • Name
    files
    Type
    array<object>
    Description

    Files to upload: path (absolute, or relative to basePath), size in bytes, and optionally mimeType and sha256 (hex). When sha256 is sent, the upload is rejected if the content does not match.

Response​

  • Name
    uploads
    Type
    array<object>
    Description

    One entry per accepted file: uploadId, path, method (SINGLE or MULTIPART), and expiresAt. SINGLE entries carry url and headers to send with the PUT; MULTIPART entries carry partSize and partCount.

  • Name
    errors
    Type
    array<object>
    Description

    Files that were refused: path, errorCode, and message.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/uploads/create?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "basePath": "/Shared/Legal/Contracts/2026/Q4",
    "conflict": "RENAME",
    "files": [
      {
        "path": "initech-msa.pdf",
        "size": 913442,
        "mimeType": "application/pdf"
      }
    ]
  }'
Response
{
  "uploads": [
    {
      "uploadId": "5d0a7c2e-1b9f-4e3a-8f61-0c2d9b7a4e15",
      "path": "/Shared/Legal/Contracts/2026/Q4/initech-msa.pdf",
      "method": "SINGLE",
      "url": "https://uploads.autessa.com/u/5d0a7c2e...",
      "headers": {
        "Content-Type": "application/pdf"
      },
      "expiresAt": "2026-10-02T16:00:00Z"
    }
  ],
  "errors": []
}
POST/uploads/part-urls

For a multipart upload, returns links to PUT each part to. Every part except the last must be exactly partSize bytes. Keep the ETag response header from each part for completion.

Permission: WRITE

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    uploadId
    Type
    string
    Description

    The multipart upload.

  • Name
    partNumbers
    Type
    array<integer>
    Description

    Part numbers to get links for, starting at 1.

Response​

  • Name
    partUrls
    Type
    object
    Description

    Map of part number to upload link.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/uploads/part-urls?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "uploadId": "8e4b2f10-6a3d-4c7e-b5a9-2f1e0d8c7b64",
    "partNumbers": [
      1,
      2,
      3
    ]
  }'
Response
{
  "partUrls": {
    "1": "https://uploads.autessa.com/u/8e4b2f10.../1",
    "2": "https://uploads.autessa.com/u/8e4b2f10.../2",
    "3": "https://uploads.autessa.com/u/8e4b2f10.../3"
  }
}

Complete a multipart upload​

POST/uploads/complete-multipart

Assembles the uploaded parts of a multipart upload. Then commit it like any other upload.

Permission: WRITE

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    uploadId
    Type
    string
    Description

    The multipart upload.

  • Name
    parts
    Type
    array<object>
    Description

    Every part: partNumber and the etag returned when it was uploaded.

Response​

  • Name
    uploadId
    Type
    string
    Description

    The upload, now ready to commit.

  • Name
    status
    Type
    string
    Description

    UPLOADED.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/uploads/complete-multipart?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "uploadId": "8e4b2f10-6a3d-4c7e-b5a9-2f1e0d8c7b64",
    "parts": [
      {
        "partNumber": 1,
        "etag": "\"a54357aff0632cce46d942af68356b38\""
      },
      {
        "partNumber": 2,
        "etag": "\"0c78aef83f66abc1fa1e8477f296d394\""
      },
      {
        "partNumber": 3,
        "etag": "\"acbd18db4cc2f85cedef654fccc4a4d8\""
      }
    ]
  }'
Response
{
  "uploadId": "8e4b2f10-6a3d-4c7e-b5a9-2f1e0d8c7b64",
  "status": "UPLOADED"
}

Commit uploads​

POST/uploads/commit

Turns finished uploads into Drive files, creating missing folders and applying the conflict rule chosen at start. Up to 100 uploads per call; each succeeds or fails on its own. Committed files appear immediately and become searchable once processing finishes. Insert or update triggers on the Drive fire for each file.

Permission: WRITE

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    uploadIds
    Type
    array<string>
    Description

    Uploads to commit, up to 100.

Response​

  • Name
    results
    Type
    array<object>
    Description

    One entry per upload: uploadId, status (COMMITTED or FAILED), node when committed, and errorCode/message when not.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/uploads/commit?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "uploadIds": [
      "5d0a7c2e-1b9f-4e3a-8f61-0c2d9b7a4e15"
    ]
  }'
Response
{
  "results": [
    {
      "uploadId": "5d0a7c2e-1b9f-4e3a-8f61-0c2d9b7a4e15",
      "status": "COMMITTED",
      "node": {
        "nodeId": "4210",
        "path": "/Shared/Legal/Contracts/2026/Q4/initech-msa.pdf",
        "name": "initech-msa.pdf",
        "nodeType": "FILE",
        "parentId": "4202",
        "sizeBytes": 913442,
        "mimeType": "application/pdf",
        "version": 1,
        "contentUpdatedAt": "2026-09-28T17:04:11Z",
        "updatedAt": "2026-09-28T17:04:11Z",
        "owner": {
          "userId": "u8Kd2LmQ4x",
          "name": "Dana Ortiz"
        },
        "extractionStatus": "PENDING"
      }
    }
  ]
}

Cancel uploads​

POST/uploads/abort

Cancels uploads that have not been committed and releases their reserved storage. Uploads that are never committed expire on their own.

Permission: WRITE

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    uploadIds
    Type
    array<string>
    Description

    Uploads to cancel.

Response​

  • Name
    aborted
    Type
    array<string>
    Description

    The uploads that were cancelled.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/uploads/abort?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "uploadIds": [
      "8e4b2f10-6a3d-4c7e-b5a9-2f1e0d8c7b64"
    ]
  }'
Response
{
  "aborted": [
    "8e4b2f10-6a3d-4c7e-b5a9-2f1e0d8c7b64"
  ]
}

List versions​

POST/versions/list

Lists a file's versions, newest first. The current content is the highest version.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the item, e.g. /Contracts/acme-msa.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID. Takes precedence over path when both are sent.

Response​

  • Name
    versions
    Type
    array<object>
    Description

    version, sizeBytes, sha256, createdAt, createdBy, and current (true for the current content).

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/versions/list?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "nodeId": "4182"
  }'
Response
{
  "versions": [
    {
      "version": 2,
      "sizeBytes": 482113,
      "sha256": "9b74c9897bac770ffc029102a200c5de...",
      "createdAt": "2026-09-28T17:04:11Z",
      "createdBy": {
        "userId": "u8Kd2LmQ4x",
        "name": "Dana Ortiz"
      },
      "current": true
    },
    {
      "version": 1,
      "sizeBytes": 479920,
      "sha256": "3f786850e387550fdab836ed7e6dc881...",
      "createdAt": "2026-09-02T11:30:05Z",
      "createdBy": {
        "userId": "u8Kd2LmQ4x",
        "name": "Dana Ortiz"
      },
      "current": false
    }
  ]
}

Restore a version​

POST/versions/restore

Makes a previous version current again. The restore itself creates a new version, so nothing is lost.

Permission: WRITE, and Editor on the file

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    nodeId
    Type
    string
    Description

    The file's ID.

  • Name
    version
    Type
    integer
    Description

    The version to restore.

Response​

  • Name
    node
    Type
    object
    Description

    The file with its new version.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/versions/restore?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "nodeId": "4182",
    "version": 1
  }'
Response
{
  "node": {
    "nodeId": "4182",
    "name": "acme-msa.pdf",
    "nodeType": "FILE",
    "parentId": "4170",
    "sizeBytes": 479920,
    "mimeType": "application/pdf",
    "version": 3,
    "contentUpdatedAt": "2026-09-28T17:04:11Z",
    "updatedAt": "2026-09-28T17:04:11Z",
    "owner": {
      "userId": "u8Kd2LmQ4x",
      "name": "Dana Ortiz"
    },
    "extractionStatus": "EXTRACTED"
  }
}

Who has access​

POST/shares/list

Lists everyone who can reach an item: its owner, Drive managers, direct shares, shares inherited from parent folders (deepest folder first, with the folder they come from), and active links. Drive members are listed separately in members, because membership doesn't give access to an item. Send path: "/" to list the Drive's members.

Permission: READ, and the ability to see the item

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the item, e.g. /Contracts/acme-msa.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID. Takes precedence over path when both are sent.

Response​

  • Name
    owner
    Type
    object
    Description

    The item's owner: userId and name.

  • Name
    managers
    Type
    array<object>
    Description

    Drive managers, who can see and manage everything.

  • Name
    shares
    Type
    array<object>
    Description

    One entry per person, team, or company-wide share that gives access to this item: principal (type of USER, TEAM, or COMPANY, with userId or teamId and name), role, direct (true if shared on this item), inheritedFrom (nodeId and path of the folder it comes from; null when direct), expiresAt, and alsoVia (other folders that grant the same principal a weaker or equal role). With path: "/", the Drive's members.

  • Name
    links
    Type
    array<object>
    Description

    Active links on this item or a parent folder. Same shape as List links.

  • Name
    members
    Type
    array<object>
    Description

    The Drive's members, in the same shape as shares, with each member's Drive role. Members see the Drive in their list but only the items shared with them. Returned to members and Drive managers; absent for callers who only have items shared with them.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/shares/list?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "nodeId": "4182"
  }'
Response
{
  "owner": {
    "userId": "u8Kd2LmQ4x",
    "name": "Dana Ortiz"
  },
  "managers": [
    {
      "userId": "k3Jd8sLq2W",
      "name": "Priya Natarajan"
    }
  ],
  "shares": [
    {
      "principal": {
        "type": "USER",
        "userId": "pQ7wR2tY9z",
        "name": "Sam Lee"
      },
      "role": "EDITOR",
      "direct": true,
      "inheritedFrom": null,
      "expiresAt": null,
      "alsoVia": []
    },
    {
      "principal": {
        "type": "TEAM",
        "teamId": "3b1f6a2e-7c41-4d55-9a0e-58c2b7f1d903",
        "name": "Legal"
      },
      "role": "VIEWER",
      "direct": false,
      "inheritedFrom": {
        "nodeId": "4101",
        "path": "/Shared/Legal"
      },
      "expiresAt": null,
      "alsoVia": []
    },
    {
      "principal": {
        "type": "COMPANY",
        "name": "Anyone at Acme Corp"
      },
      "role": "VIEWER",
      "direct": false,
      "inheritedFrom": {
        "nodeId": "4175",
        "path": "/Shared/Legal/Policies"
      },
      "expiresAt": null,
      "alsoVia": []
    }
  ],
  "links": [],
  "members": [
    {
      "principal": {
        "type": "TEAM",
        "teamId": "3b1f6a2e-7c41-4d55-9a0e-58c2b7f1d903",
        "name": "Legal"
      },
      "role": "VIEWER",
      "direct": true,
      "inheritedFrom": null,
      "expiresAt": null,
      "alsoVia": []
    }
  ]
}

Share an item​

POST/shares/upsert

Shares a folder or a file with people, teams, or everyone at your company, adds members to the Drive, or changes the role of an existing share. Sharing a folder shares everything inside it, including items added later. Sharing the Drive itself (path: "/", or scope: "drive") adds members: the Drive appears in their list of Drives and an EDITOR member can add items at the top level, but members see no folder or file until it is shared with them. To share a folder or file with every current member, send "principals": "members"; each member gets their own share on the item. You can grant up to your own role.

Permission: WRITE, and Owner on the item, Drive manager, or Editor when Editors can share is on

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the item, e.g. /Contracts/acme-msa.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID. Takes precedence over path when both are sent.

  • Name
    scope
    Type
    string
    Description

    drive to add members to the Drive. Same as sending path: "/".

  • Name
    principals
    Type
    array<object> | string
    Description

    Who to share with. Each entry is {"type": "USER", "userId": ...}, {"type": "TEAM", "teamId": ...}, or {"type": "COMPANY"}. Users and teams must belong to your company. Send the string "members" (or an entry {"type": "MEMBERS"}) to share a folder or file with every current member of the Drive; not allowed with path: "/".

  • Name
    role
    Type
    string
    Description

    VIEWER or EDITOR.

  • Name
    expiresAt
    Type
    string
    Description

    ISO-8601 UTC time when the share ends.

Response​

  • Name
    shares
    Type
    array<object>
    Description

    The resulting shares, same shape as Who has access.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/shares/upsert?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "path": "/Shared/Legal/Contracts",
    "principals": [
      {
        "type": "TEAM",
        "teamId": "3b1f6a2e-7c41-4d55-9a0e-58c2b7f1d903"
      },
      {
        "type": "USER",
        "userId": "pQ7wR2tY9z"
      }
    ],
    "role": "EDITOR"
  }'
Response
{
  "shares": [
    {
      "principal": {
        "type": "TEAM",
        "teamId": "3b1f6a2e-7c41-4d55-9a0e-58c2b7f1d903",
        "name": "Legal"
      },
      "role": "EDITOR",
      "direct": true,
      "inheritedFrom": null,
      "expiresAt": null,
      "alsoVia": []
    },
    {
      "principal": {
        "type": "USER",
        "userId": "pQ7wR2tY9z",
        "name": "Sam Lee"
      },
      "role": "EDITOR",
      "direct": true,
      "inheritedFrom": null,
      "expiresAt": null,
      "alsoVia": []
    }
  ]
}

Stop sharing​

POST/shares/remove

Removes one direct share, by its grantId (from Who has access). Access ends immediately. To remove inherited access, remove the share on the folder it comes from.

Permission: WRITE, and the same rights as sharing

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    grantId
    Type
    string
    Description

    The share to remove: a grantId from Who has access.

Response​

  • Name
    ok
    Type
    boolean
    Description

    true when the share was removed.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/shares/remove?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "grantId": "6f1c2b9e-4d7a-4f0e-9b2a-1c3d5e7f9a0b"
  }'
Response
{
  "ok": true
}

Shared with me​

POST/shared-with-me

Lists items other people have shared with the caller, directly, through one of their teams, or with everyone at the company. Only the shared item itself is listed, not its contents; browse into a shared folder with List a folder. When the caller is a member of the Drive, the Drive is listed as one entry whose node is the Drive itself (path /, named after the Drive) and whose role is the caller's Drive role. Membership shows only the Drive, not its contents.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    limit
    Type
    integer
    Description

    Maximum entries to return. Default 200, maximum 1000.

  • Name
    cursor
    Type
    string
    Description

    The nextCursor from the previous page. Send the same other arguments as the first call.

Response​

  • Name
    items
    Type
    array<object>
    Description

    One entry per shared item: node (see The item object), role (your role), grantedBy and createdAt.

  • Name
    nextCursor
    Type
    string
    Description

    Cursor for the next page; absent on the last page.

  • Name
    hasMore
    Type
    boolean
    Description

    true when another page exists.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/shared-with-me?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5"
  }'
Response
{
  "items": [
    {
      "node": {
        "nodeId": "4101",
        "path": "/Shared/Legal",
        "name": "Legal",
        "nodeType": "FOLDER",
        "parentId": "4001",
        "updatedAt": "2026-09-21T09:12:40Z",
        "owner": {
          "userId": "u8Kd2LmQ4x",
          "name": "Dana Ortiz"
        }
      },
      "role": "VIEWER",
      "sharedBy": {
        "userId": "k3Jd8sLq2W",
        "name": "Priya Natarajan"
      },
      "sharedAt": "2026-08-14T10:02:00Z",
      "via": {
        "type": "TEAM",
        "name": "Legal"
      }
    }
  ],
  "nextCursor": null,
  "truncated": false
}

Check access​

POST/access

Returns the caller's effective role on an item and their Drive membership. To see every share on an item, use Who has access.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the item, e.g. /Contracts/acme-msa.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID. Takes precedence over path when both are sent.

Response​

  • Name
    effectiveRole
    Type
    string
    Description

    OWNER, EDITOR, VIEWER, or NONE.

  • Name
    driveRole
    Type
    string
    Description

    The caller's Drive membership: OWNER (owner or Drive admin), EDITOR or VIEWER (a member), or NONE. Membership alone gives no access to files and folders.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/access?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "nodeId": "4182"
  }'
Response
{
  "effectiveRole": "EDITOR",
  "driveRole": "VIEWER"
}

Transfer ownership​

POST/transfer-owner

Makes another person in your company the owner of an item. The previous owner keeps Editor access.

Permission: WRITE, and Owner on the item or Drive manager

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID.

  • Name
    newOwnerUserId
    Type
    string
    Description

    The new owner: a member of your company.

Response​

  • Name
    node
    Type
    object
    Description

    The item with its new owner.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/transfer-owner?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "nodeId": "4182",
    "newOwnerUserId": "pQ7wR2tY9z"
  }'
Response
{
  "node": {
    "nodeId": "4182",
    "name": "acme-msa.pdf",
    "nodeType": "FILE",
    "parentId": "4170",
    "sizeBytes": 482113,
    "mimeType": "application/pdf",
    "version": 2,
    "contentUpdatedAt": "2026-09-28T17:04:11Z",
    "updatedAt": "2026-09-28T17:04:11Z",
    "owner": {
      "newOwnerUserId": "pQ7wR2tY9z",
      "name": "Sam Lee"
    },
    "extractionStatus": "EXTRACTED"
  }
}
POST/links/create

Creates a link to a file, a folder, or the whole Drive (path: "/"). A folder or Drive link opens a read-only view of everything inside it. Links keep working when the item is moved or renamed and stop working when it is trashed.

The link url is returned only by this call. Autessa does not store it in readable form, so save it if you need it again; otherwise revoke the link and create a new one.

Permission: WRITE, and the same rights as sharing

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Absolute path of the item, e.g. /Contracts/acme-msa.pdf. Send path or nodeId.

  • Name
    nodeId
    Type
    string
    Description

    The item's ID. Takes precedence over path when both are sent.

  • Name
    scope
    Type
    string
    Description

    drive to link the whole Drive. Same as sending path: "/".

  • Name
    audience
    Type
    string
    Description

    COMPANY (default): only signed-in people at your company. ANYONE: anyone with the link, no sign-in.

  • Name
    role
    Type
    string
    Description

    VIEWER (default).

  • Name
    allowDownload
    Type
    boolean
    Description

    Let link visitors download files. Default false (preview only).

  • Name
    allowSearch
    Type
    boolean
    Description

    Let link visitors search inside the shared folder. Default true.

  • Name
    expiresAt
    Type
    string
    Description

    ISO-8601 UTC time when the link stops working.

Response​

  • Name
    url
    Type
    string
    Description

    The link. Shown only once.

  • Name
    link
    Type
    object
    Description

    The link's settings, same shape as List links.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/links/create?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "path": "/Shared/Legal/Contracts",
    "audience": "ANYONE",
    "allowDownload": false,
    "expiresAt": "2026-12-31T23:59:59Z"
  }'
Response
{
  "url": "https://app.autessa.com/public/drive/Xk9vQ2...",
  "link": {
    "linkId": "c6e2d9a4-0f3b-4a71-9e58-7d1b2c4f6a80",
    "target": {
      "nodeId": "4170",
      "path": "/Shared/Legal/Contracts"
    },
    "role": "VIEWER",
    "audience": "ANYONE",
    "allowDownload": false,
    "allowSearch": true,
    "expiresAt": "2026-12-31T23:59:59Z",
    "createdBy": {
      "userId": "u8Kd2LmQ4x",
      "name": "Dana Ortiz"
    },
    "createdAt": "2026-10-02T14:58:00Z",
    "accessCount": 0,
    "lastAccessedAt": null
  }
}
POST/links/list

Lists active links, for one item or for everything the caller can manage. Link URLs are not included.

Permission: READ

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    path
    Type
    string
    Description

    Only links on this item.

  • Name
    nodeId
    Type
    string
    Description

    Only links on this item.

Response​

  • Name
    links
    Type
    array<object>
    Description

    Each link: linkId, target (nodeId and path), role, audience, allowDownload, allowSearch, expiresAt, createdBy, createdAt, accessCount, and lastAccessedAt.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/links/list?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "path": "/Shared/Legal/Contracts"
  }'
Response
{
  "links": [
    {
      "linkId": "c6e2d9a4-0f3b-4a71-9e58-7d1b2c4f6a80",
      "target": {
        "nodeId": "4170",
        "path": "/Shared/Legal/Contracts"
      },
      "role": "VIEWER",
      "audience": "ANYONE",
      "allowDownload": false,
      "allowSearch": true,
      "expiresAt": "2026-12-31T23:59:59Z",
      "createdBy": {
        "userId": "u8Kd2LmQ4x",
        "name": "Dana Ortiz"
      },
      "createdAt": "2026-10-02T14:58:00Z",
      "accessCount": 14,
      "lastAccessedAt": "2026-10-02T13:20:44Z"
    }
  ]
}
POST/links/revoke

Revokes a link. It stops working immediately, including for anyone who already has it open.

Permission: WRITE, and the same rights as sharing

Request parameters​

  • Name
    tableId
    Type
    string
    Description

    The Drive's ID. Must match the resourceId query parameter.

  • Name
    linkId
    Type
    string
    Description

    The link to revoke.

Response​

  • Name
    revoked
    Type
    boolean
    Description

    true when the link was revoked.

curl -X POST 'https://api.autessa.com/clients/autessadb-drive/links/revoke?resourceId=V1StGXR8Z5' \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "V1StGXR8Z5",
    "linkId": "c6e2d9a4-0f3b-4a71-9e58-7d1b2c4f6a80"
  }'
Response
{
  "revoked": true
}

Comments​

Comments live under /comments/* and need the Commenter role or higher on the item (owners and Drive managers always qualify). All calls take tableId and identify the item by nodeId or path.

  • POST /comments/list with includeResolved and cursor: threads with their replies, each with the author's display name, time, body, anchor, and resolved.
  • POST /comments/add with body, optional anchor, and optional parentId to reply.
  • POST /comments/edit with commentId and body (authors only).
  • POST /comments/resolve with commentId and resolved (Editors, owners, and managers).
  • POST /comments/delete with commentId (authors; Drive managers for any comment).

An anchor is one of { "kind": "page", "page": 3, "quote": "..." }, { "kind": "text", "from": 120, "to": 164, "quote": "..." } (offsets into the file's extracted text), { "kind": "cell", "sheet": "Q1", "range": "B2:D9" }, { "kind": "slide", "slide": 2 }, or omitted for the whole file. Anchors carry the version they were made on; a text anchor whose quote no longer matches a newer version is returned with stale: true. stat includes commentCount and openCommentCount.

Live co-editing uses a WebSocket at /ws/autessadb/drive/collab with the same session parameters as other sockets; only Editors and above may send changes.

Errors​

Failed calls return an error code, a plain-language message and a hint with the next step. Some errors add details:

Error response
{
  "errorCode": "VERSION_CONFLICT",
  "errors": ["/Shared/notes/plan.md is now at version 5"],
  "hint": "Read the file again, then retry with expectedVersion=5.",
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "/Shared/notes/plan.md is now at version 5",
    "hint": "Read the file again, then retry with expectedVersion=5.",
    "details": { "path": "/Shared/notes/plan.md", "currentVersion": 5 }
  }
}
StatusError codeWhen
400INVALID_PATHThe path is malformed, contains . or .., or exceeds the length or depth limits.
400INVALID_PATTERNA glob or regular expression is invalid, too broad (fewer than 3 literal characters over a large scope), or longer than 1,000 characters.
400INVALID_CURSORThe cursor is malformed, expired, or was sent with different arguments than the call that produced it.
400INVALID_MOVEA folder was moved into itself or one of its own subfolders.
401—Missing or invalid API key.
403FORBIDDENThe key lacks the table permission for the operation, the body's tableId does not match resourceId, the caller's role on the item is too low, or a folder contains items the caller cannot see.
404NOT_FOUNDThe item does not exist or the caller cannot open it.
409NAME_CONFLICTThe name is already taken in the folder and the conflict rule is FAIL, or a write with mode: create found the file.
409VERSION_CONFLICTA write or edit named an expectedVersion the file is no longer at. error.details.currentVersion holds the current version.
409EDIT_NO_MATCHAn edit's oldText does not occur in the file.
409EDIT_AMBIGUOUSAn edit's oldText occurs more than once and replaceAll is not set. error.details.matches holds the count.
413FILE_TOO_LARGEA write or edit would make the file larger than 5 MB. Upload large files instead.
413QUOTA_EXCEEDEDThe upload would exceed your storage allowance, the per-file size limit, or the file-count limit.
413TOO_MANY_ITEMSA move or trash would touch more than 100,000 items at once.
415UNSUPPORTED_TYPEThe file type is not allowed in a Drive.
429RATE_LIMITEDToo many search, grep, or read calls; retry after a short wait. Semantic search also counts toward your company's search limits.