Files API reference

Upload, read, organize and restore files.

Requests go to https://api.revdoku.com. Every path starts with /v1, for example https://api.revdoku.com/v1/buckets. Send Authorization: Bearer $REVDOKU_API_KEY from your server. Tables use JSON names; where TypeScript differs, a field shows json_name / typescriptName. Python uses the JSON names.

All operations · API guide · Errors · OpenAPI

• List files: GET /v1/buckets/{bucket_id}/files
• Save an uploaded file (step 3 of 3): POST /v1/buckets/{bucket_id}/files
• Find a file by path: GET /v1/buckets/{bucket_id}/files/by_path
• Append text to a file: POST /v1/buckets/{bucket_id}/files/append_text
• Read file metadata: GET /v1/buckets/{bucket_id}/files/{file_id}
• Delete a file: DELETE /v1/buckets/{bucket_id}/files/{file_id}
• Get a download link for a file: GET /v1/buckets/{bucket_id}/files/{file_id}/download
• Rename or move a file in the same bucket: POST /v1/buckets/{bucket_id}/files/{file_id}/rename
• Move a file: POST /v1/buckets/{bucket_id}/files/{file_id}/move
• Copy a file: POST /v1/buckets/{bucket_id}/files/{file_id}/copy
• List file versions: GET /v1/buckets/{bucket_id}/files/{file_id}/versions
• Restore a file version: POST /v1/buckets/{bucket_id}/files/{file_id}/versions/{version_id}/restore
• Prepare a file upload (step 1 of 3): POST /v1/buckets/{bucket_id}/uploads
• Start a batch upload: POST /v1/buckets/{bucket_id}/upload_sessions
• Get storage targets for a batch: POST /v1/buckets/{bucket_id}/upload_sessions/{session_id}/uploads
• Save uploaded files: POST /v1/buckets/{bucket_id}/upload_sessions/{session_id}/finalize_batch
• Finish or cancel a batch upload: POST /v1/buckets/{bucket_id}/upload_sessions/{session_id}/finalize

List files

GET /v1/buckets/{bucket_id}/files

Lists current files, including stored emails under _mailbox/. Listing never marks files read.

Parameters

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.listFiles({ bucketId: 'bkt_example' });
for (const file of data.files) {
  console.log(file.id, file.path);
}

Python

from revdoku import Revdoku

client = Revdoku()
response = client.list_files("bkt_example")
for file in response.data.files:
    print(file.id, file.path)

cURL

curl "https://api.revdoku.com/v1/buckets/bkt_example/files" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "files": [
      {
        "id": "df_example",
        "bucket_id": "bkt_example",
        "basename": "summary.txt",
        "path": "reports/summary.txt",
        "role": "source",
        "deleted": false,
        "lock": {"locked": false},
        "current_file_version": {
          "id": "dfrev_example",
          "file_id": "df_example",
          "version_number": 0,
          "name": "summary.txt",
          "mime_type": "text/plain",
          "byte_size": 1234,
          "sha256": "0d6a3c2b8f5e41a7c9b2d4e6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7",
          "deleted": false,
          "ready": true,
          "has_text": false,
          "created_at": "2026-10-11T12:20:00Z",
          "created_by": {
            "id": "user_example",
            "email": "ada@example.com",
            "name": "Ada Lovelace"
          },
          "updated_by": {
            "id": "user_example",
            "email": "ada@example.com",
            "name": "Ada Lovelace"
          },
          "created_by_api_key": {
            "id": "atok_example",
            "label": "Orders backend",
            "token_type": "api"
          },
          "created_by_agent": {"name": "Orders backend"},
          "updated_by_api_key": {
            "id": "atok_example",
            "label": "Orders backend",
            "token_type": "api"
          },
          "updated_by_agent": {"name": "Orders backend"},
          "read": false,
          "read_at": null,
          "read_by": null,
          "read_by_api_key": null
        },
        "created_by": {
          "id": "user_example",
          "email": "ada@example.com",
          "name": "Ada Lovelace"
        },
        "created_by_api_key": {
          "id": "atok_example",
          "label": "Orders backend",
          "token_type": "api"
        },
        "created_by_agent": {"name": "Orders backend"},
        "updated_by_api_key": {
          "id": "atok_example",
          "label": "Orders backend",
          "token_type": "api"
        },
        "updated_by_agent": {"name": "Orders backend"},
        "created_at": "2026-10-11T12:20:00Z",
        "updated_at": "2026-10-11T12:20:00Z",
        "read": false,
        "read_at": null,
        "read_by": null,
        "read_by_api_key": null
      }
    ],
    "pagination": {"limit": 50, "has_more": false, "next_cursor": null}
  }
}

Errors

Guide: Files

Save an uploaded file (step 3 of 3)

POST /v1/buckets/{bucket_id}/files

Saves the uploaded blob at path. An existing path gets a new version.

Parameters

Request body: TypeScript saveUploadedFileRequest: SaveUploadedFileRequest, Python save_uploaded_file_request=SaveUploadedFileRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
// uploadFile runs all three steps: prepare, PUT the bytes to storage, save.
const { data } = await client.uploadFile({
  bucketId: 'bkt_example',
  path: 'notes/todo.txt',
  content: 'Call the customer back.',
  contentType: 'text/plain',
});
console.log(data.file.id, data.version.id);

Python

from revdoku import Revdoku

client = Revdoku()
# upload_file runs all three steps: prepare, PUT the bytes to storage, save.
response = client.upload_file("bkt_example", "notes/todo.txt", "Call the customer back.", content_type="text/plain")
print(response.data.file.id, response.data.version.id)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/files" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "notes/todo.txt",
  "signed_blob_id": "SIGNED_ID_FROM_STEP_1"
}'

Response 201, 200

Example 201:

{
  "success": true,
  "data": {
    "file": {
      "id": "df_example",
      "bucket_id": "bkt_example",
      "basename": "summary.txt",
      "path": "reports/summary.txt",
      "role": "source",
      "deleted": false,
      "version_reasons": [],
      "lock": {"locked": false},
      "current_file_version": {
        "id": "dfrev_example",
        "file_id": "df_example",
        "version_number": 0,
        "name": "summary.txt",
        "mime_type": "text/plain",
        "byte_size": 1234,
        "sha256": "0d6a3c2b8f5e41a7c9b2d4e6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7",
        "deleted": false,
        "ready": true,
        "has_text": false,
        "created_at": "2026-10-11T12:20:00Z",
        "created_by": {
          "id": "user_example",
          "email": "ada@example.com",
          "name": "Ada Lovelace"
        },
        "updated_by": {
          "id": "user_example",
          "email": "ada@example.com",
          "name": "Ada Lovelace"
        },
        "created_by_api_key": {
          "id": "atok_example",
          "label": "Orders backend",
          "token_type": "api"
        },
        "created_by_agent": {"name": "Orders backend"},
        "updated_by_api_key": {
          "id": "atok_example",
          "label": "Orders backend",
          "token_type": "api"
        },
        "updated_by_agent": {"name": "Orders backend"},
        "read": false,
        "read_at": null,
        "read_by": null,
        "read_by_api_key": null
      },
      "created_by": {
        "id": "user_example",
        "email": "ada@example.com",
        "name": "Ada Lovelace"
      },
      "created_by_api_key": {"id": "atok_example", "label": "Orders backend", "token_type": "api"},
      "created_by_agent": {"name": "Orders backend"},
      "updated_by_api_key": {"id": "atok_example", "label": "Orders backend", "token_type": "api"},
      "updated_by_agent": {"name": "Orders backend"},
      "created_at": "2026-10-11T12:20:00Z",
      "updated_at": "2026-10-11T12:20:00Z",
      "read": false,
      "read_at": null,
      "read_by": null,
      "read_by_api_key": null
    },
    "version": {
      "id": "dfrev_example",
      "file_id": "df_example",
      "version_number": 0,
      "name": "summary.txt",
      "mime_type": "text/plain",
      "byte_size": 1234,
      "sha256": "0d6a3c2b8f5e41a7c9b2d4e6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7",
      "deleted": false,
      "ready": true,
      "has_text": false,
      "created_at": "2026-10-11T12:20:00Z",
      "created_by": {
        "id": "user_example",
        "email": "ada@example.com",
        "name": "Ada Lovelace"
      },
      "updated_by": {
        "id": "user_example",
        "email": "ada@example.com",
        "name": "Ada Lovelace"
      },
      "created_by_api_key": {"id": "atok_example", "label": "Orders backend", "token_type": "api"},
      "created_by_agent": {"name": "Orders backend"},
      "updated_by_api_key": {"id": "atok_example", "label": "Orders backend", "token_type": "api"},
      "updated_by_agent": {"name": "Orders backend"},
      "read": false,
      "read_at": null,
      "read_by": null,
      "read_by_api_key": null
    },
    "created": true
  }
}

Errors

Guide: Upload a file

Find a file by path

GET /v1/buckets/{bucket_id}/files/by_path

Returns file metadata only. Read content with the download endpoint. The disposition and content_url parameters return INVALID_ARGUMENT.

Parameters

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.getFileByPath({
  bucketId: 'bkt_example',
  path: 'notes/todo.txt',
});
console.log(data);

Python

from revdoku import Revdoku

client = Revdoku()
response = client.api.get_file_by_path("bkt_example", path="notes/todo.txt")
print(response.data)

cURL

curl -G "https://api.revdoku.com/v1/buckets/bkt_example/files/by_path" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  --data-urlencode "path=notes/todo.txt"

Response 200

Errors

Error codes named above: INVALID_ARGUMENT.

Guide: Files

Append text to a file

POST /v1/buckets/{bucket_id}/files/append_text

Appends UTF-8 text to an existing text file and creates a new version. A missing file returns BUCKET_FILE_NOT_FOUND.

Parameters

Request body: TypeScript appendTextRequest: AppendTextRequest, Python append_text_request=AppendTextRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.appendText({
  bucketId: 'bkt_example',
  appendTextRequest: { path: 'notes/todo.txt', content: 'Call the customer back.' },
});
console.log(data);

Python

from revdoku import Revdoku, AppendTextRequest

client = Revdoku()
response = client.api.append_text(
    "bkt_example",
    AppendTextRequest(
        path="notes/todo.txt",
        content="Call the customer back.",
    ),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/files/append_text" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "notes/todo.txt", "content": "Call the customer back."}'

Response 200

Errors

Error codes named above: BUCKET_FILE_NOT_FOUND.

Guide: Files

Read file metadata

GET /v1/buckets/{bucket_id}/files/{file_id}

Reading metadata never marks the file read.

Parameters

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.getFile({
  bucketId: 'bkt_example',
  fileId: 'df_example',
});
console.log(data);

Python

from revdoku import Revdoku

client = Revdoku()
response = client.api.get_file("bkt_example", "df_example")
print(response.data)

cURL

curl "https://api.revdoku.com/v1/buckets/bkt_example/files/df_example" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Response 200

Errors

Guide: Files

Delete a file

DELETE /v1/buckets/{bucket_id}/files/{file_id}

Requires bucket-admin permission.

Files under _mailbox/ return MAILBOX_PATH_READ_ONLY; delete the ticket message instead. Files under _agents/ and _revdoku/ return RESERVED_PATH.

Parameters

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.deleteFile({
  bucketId: 'bkt_example',
  fileId: 'df_example',
});
console.log(data);

Python

from revdoku import Revdoku

client = Revdoku()
response = client.api.delete_file("bkt_example", "df_example")
print(response.data)

cURL

curl -X DELETE "https://api.revdoku.com/v1/buckets/bkt_example/files/df_example" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Response 200

Errors

Error codes named above: MAILBOX_PATH_READ_ONLY, RESERVED_PATH.

Guide: Files

Get a download link for a file

GET /v1/buckets/{bucket_id}/files/{file_id}/download

Returns a temporary link and marks this version read. Send version_id for an older version.

Parameters

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.getFileDownload({
  bucketId: 'bkt_example',
  fileId: 'df_example',
});
console.log(data);

Python

from revdoku import Revdoku

client = Revdoku()
response = client.api.get_file_download("bkt_example", "df_example")
print(response.data)

cURL

curl "https://api.revdoku.com/v1/buckets/bkt_example/files/df_example/download" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Response 200

Errors

Guide: Files

Rename or move a file in the same bucket

POST /v1/buckets/{bucket_id}/files/{file_id}/rename

Changes the path without uploading the content again.

Parameters

Request body: TypeScript renameFileRequest: RenameFileRequest, Python rename_file_request=RenameFileRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.renameFile({
  bucketId: 'bkt_example',
  fileId: 'df_example',
  renameFileRequest: { newPath: 'notes/done.txt' },
});
console.log(data);

Python

from revdoku import Revdoku, RenameFileRequest

client = Revdoku()
response = client.api.rename_file(
    "bkt_example",
    "df_example",
    RenameFileRequest(new_path="notes/done.txt"),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/files/df_example/rename" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"new_path": "notes/done.txt"}'

Response 200

Errors

Guide: Files

Move a file

POST /v1/buckets/{bucket_id}/files/{file_id}/move

Works in the same bucket or into target_bucket_id. Content is not uploaded again. Send target_path for an exact path or target_folder to keep the name.

Parameters

Request body: TypeScript moveFileRequest: MoveFileRequest, Python move_file_request=MoveFileRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.moveFile({
  bucketId: 'bkt_example',
  fileId: 'df_example',
  moveFileRequest: { targetFolder: 'archive' },
});
console.log(data);

Python

from revdoku import Revdoku, MoveFileRequest

client = Revdoku()
response = client.api.move_file(
    "bkt_example",
    "df_example",
    MoveFileRequest(target_folder="archive"),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/files/df_example/move" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_folder": "archive"}'

Response 201

Errors

Guide: Files

Copy a file

POST /v1/buckets/{bucket_id}/files/{file_id}/copy

Works in the same bucket or into target_bucket_id. Content is not uploaded again. Send target_path for an exact path or target_folder to keep the name.

Parameters

Request body: TypeScript moveFileRequest: MoveFileRequest, Python move_file_request=MoveFileRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.copyFile({
  bucketId: 'bkt_example',
  fileId: 'df_example',
  moveFileRequest: { targetPath: 'notes/todo-copy.txt' },
});
console.log(data);

Python

from revdoku import Revdoku, MoveFileRequest

client = Revdoku()
response = client.api.copy_file(
    "bkt_example",
    "df_example",
    MoveFileRequest(target_path="notes/todo-copy.txt"),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/files/df_example/copy" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_path": "notes/todo-copy.txt"}'

Response 201

Errors

Guide: Files

List file versions

GET /v1/buckets/{bucket_id}/files/{file_id}/versions

Newest first.

Parameters

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.listFileVersions({
  bucketId: 'bkt_example',
  fileId: 'df_example',
});
console.log(data);

Python

from revdoku import Revdoku

client = Revdoku()
response = client.api.list_file_versions("bkt_example", "df_example")
print(response.data)

cURL

curl "https://api.revdoku.com/v1/buckets/bkt_example/files/df_example/versions" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Response 200

Errors

Guide: Files

Restore a file version

POST /v1/buckets/{bucket_id}/files/{file_id}/versions/{version_id}/restore

Creates a new current version with the content of the selected version. History is kept. Requires a plan with version restore.

Parameters

Request body: TypeScript actionRequest: ActionRequest, Python action_request=ActionRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.restoreFileVersion({
  bucketId: 'bkt_example',
  fileId: 'df_example',
  versionId: 'dfrev_example',
  actionRequest: {},
});
console.log(data);

Python

from revdoku import Revdoku, ActionRequest

client = Revdoku()
response = client.api.restore_file_version(
    "bkt_example",
    "df_example",
    "dfrev_example",
    ActionRequest(),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/files/df_example/versions/dfrev_example/restore" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 201

Errors

Guide: Files

Prepare a file upload (step 1 of 3)

POST /v1/buckets/{bucket_id}/uploads

Returns a storage URL. Then PUT the bytes to direct_upload.url with exactly direct_upload.headers and no API key (step 2), and save the file with POST /v1/buckets/{bucket_id}/files (step 3). Identical content at the same path returns skipped=true and duplicate=true without an upload.

Parameters

Request body: TypeScript prepareFileUploadRequest: PrepareFileUploadRequest, Python prepare_file_upload_request=PrepareFileUploadRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
// uploadFile runs all three steps: prepare, PUT the bytes to storage, save.
const { data } = await client.uploadFile({
  bucketId: 'bkt_example',
  path: 'notes/todo.txt',
  content: 'Call the customer back.',
  contentType: 'text/plain',
});
console.log(data.file.id, data.version.id);

Python

from revdoku import Revdoku

client = Revdoku()
# upload_file runs all three steps: prepare, PUT the bytes to storage, save.
response = client.upload_file("bkt_example", "notes/todo.txt", "Call the customer back.", content_type="text/plain")
print(response.data.file.id, response.data.version.id)

cURL

# Step 1: prepare. checksum is the base64 MD5 and sha256 the hex SHA-256 of the bytes.
curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/uploads" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "notes/todo.txt",
  "blob": {
    "filename": "todo.txt",
    "byte_size": 23,
    "content_type": "text/plain",
    "checksum": "BASE64_MD5_OF_CONTENT",
    "sha256": "HEX_SHA256_OF_CONTENT",
    "purpose": "bucket_file"
  }
}'

# Step 2: PUT the bytes to direct_upload.url with exactly direct_upload.headers. Send no API key.
curl -X PUT "DIRECT_UPLOAD_URL" \
  -H "Content-Type: text/plain" \
  -H "Content-MD5: BASE64_MD5_OF_CONTENT" \
  --data-binary @todo.txt

# Step 3: save the file with signed_id from step 1.
curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/files" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "notes/todo.txt", "signed_blob_id": "SIGNED_ID_FROM_STEP_1"}'

Response 201, 200

Example 201:

{
  "success": true,
  "data": {
    "signed_id": "eyJfcmFpbHMi...",
    "filename": "document_7a77539cbd6d02a5.txt",
    "byte_size": 1234,
    "checksum": "rL0Y20zC+Fzt72VPzMSk2A==",
    "content_type": "text/plain",
    "direct_upload": {
      "url": "https://storage.example/upload",
      "headers": {
        "Content-Type": "text/plain",
        "Content-MD5": "rL0Y20zC+Fzt72VPzMSk2A==",
        "Content-Disposition": "inline; filename=\"document_7a77539cbd6d02a5.txt\"; filename*=UTF-8''document_7a77539cbd6d02a5.txt"
      }
    }
  }
}

Errors

Guide: Upload a file

Start a batch upload

POST /v1/buckets/{bucket_id}/upload_sessions

Starts an upload session for many files and returns storage targets for the first files. The session locks the bucket for other writers; incoming email still arrives. Send files in batches with POST …/uploads, PUT the bytes to each upload.url, save each batch with POST …/finalize_batch, then call POST …/finalize. Unsaved uploads are discarded when the session expires.

Parameters

Request body: TypeScript createUploadSessionRequest: CreateUploadSessionRequest, Python create_upload_session_request=CreateUploadSessionRequest(...).

Examples

TypeScript

import { createHash } from 'node:crypto';
import { Revdoku } from 'revdoku';

const client = new Revdoku();
const bucketId = 'bkt_example';
const bytes = Buffer.from('Quarterly numbers');
// 1. Start the session with the first batch. Send more files later with client.api.addUploadSessionFiles.
const { data: started } = await client.api.createUploadSession({
  bucketId,
  createUploadSessionRequest: {
    expectedFileCount: 1,
    files: [{
      path: 'reports/q3.txt',
      byteSize: bytes.length,
      contentType: 'text/plain',
      checksum: createHash('md5').update(bytes).digest('base64'),
      sha256: createHash('sha256').update(bytes).digest('hex'),
    }],
  },
});
const sessionId = started.bucketUploadSession.id;
// 2. PUT the bytes to each storage target with exactly its headers. Send no API key.
for (const item of started.uploads ?? []) {
  const response = await fetch(item.upload.url, { method: 'PUT', headers: item.upload.headers, body: new Uint8Array(bytes) });
  if (!response.ok) throw new Error(`Storage upload failed: HTTP ${response.status}`);
}
// 3. Save the uploaded batch, then finish the session.
await client.api.saveUploadSessionBatch({ bucketId, sessionId });
const { data: finished } = await client.api.finalizeUploadSession({
  bucketId,
  sessionId,
  finalizeUploadSessionRequest: { complete: true },
});
console.log(finished.bucketUploadSession.status);

Python

import base64
import hashlib

import urllib3
from revdoku import CreateUploadSessionRequest, FinalizeUploadSessionRequest, Revdoku, UploadSessionFile

client = Revdoku()
bucket_id = "bkt_example"
data = b"Quarterly numbers"
# 1. Start the session with the first batch. Send more files later with client.api.add_upload_session_files.
started = client.api.create_upload_session(bucket_id, CreateUploadSessionRequest(
    expected_file_count=1,
    files=[UploadSessionFile(
        path="reports/q3.txt",
        byte_size=len(data),
        content_type="text/plain",
        checksum=base64.b64encode(hashlib.md5(data).digest()).decode(),
        sha256=hashlib.sha256(data).hexdigest(),
    )],
)).data
session_id = started.bucket_upload_session.id
# 2. PUT the bytes to each storage target with exactly its headers. Send no API key.
for item in started.uploads or []:
    response = urllib3.request("PUT", item.upload.url, body=data, headers=item.upload.headers)
    if response.status >= 300:
        raise RuntimeError(f"Storage upload failed: HTTP {response.status}")
# 3. Save the uploaded batch, then finish the session.
client.api.save_upload_session_batch(bucket_id, session_id)
finished = client.api.finalize_upload_session(bucket_id, session_id, FinalizeUploadSessionRequest(complete=True))
print(finished.data.bucket_upload_session.status)

cURL

# 1. Start the session. checksum is the base64 MD5 and sha256 the hex SHA-256 of each file.
curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/upload_sessions" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_file_count": 1,
  "files": [{"path": "reports/q3.txt", "byte_size": 17, "content_type": "text/plain", "checksum": "BASE64_MD5", "sha256": "HEX_SHA256"}]
}'

# 2. PUT the bytes to each uploads[].upload.url with exactly uploads[].upload.headers. Send no API key.

# 3. Save the uploaded batch, then finish the session.
curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/upload_sessions/bus_example/finalize_batch" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"
curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/upload_sessions/bus_example/finalize" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"complete": true}'

Response 201

{
  "success": true,
  "data": {
    "bucket_upload_session": {
      "id": "bus_example",
      "bucket_id": "bkt_example",
      "status": "pending",
      "base_bucket_version_id": "bktrv_example",
      "target_bucket_version_id": null,
      "uploads_expire_at": "2026-10-11T14:00:00Z",
      "session_closed_at": null,
      "files_count": 2,
      "pending_files_count": 2,
      "uploaded_files_count": 0,
      "finalized_files_count": 0,
      "skipped_files_count": 0,
      "skipped_code_counts": {},
      "failed_files_count": 0
    },
    "uploads": [
      {
        "input_index": 0,
        "path": "reports/q3.pdf",
        "name": "q3.pdf",
        "signed_blob_id": "eyJfcmFpbHMi...",
        "upload": {
          "url": "https://storage.example/upload",
          "headers": {
            "Content-Type": "application/pdf",
            "Content-MD5": "rL0Y20zC+Fzt72VPzMSk2A=="
          }
        }
      }
    ],
    "uploaded": [],
    "uploaded_count": 0,
    "uploaded_truncated": false,
    "created_count": 0,
    "updated_count": 0,
    "skipped": [],
    "skipped_count": 0,
    "skipped_truncated": false
  }
}

Errors

Guide: Upload many files

Get storage targets for a batch

POST /v1/buckets/{bucket_id}/upload_sessions/{session_id}/uploads

Returns upload.url and upload.headers for each file that needs bytes. Repeating a path returns a fresh target, for example after a failed PUT. Files with identical content are skipped.

Parameters

Request body: TypeScript addUploadSessionFilesRequest: AddUploadSessionFilesRequest, Python add_upload_session_files_request=AddUploadSessionFilesRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.addUploadSessionFiles({
  bucketId: 'bkt_example',
  sessionId: 'bus_example',
  addUploadSessionFilesRequest: {
    files: [
      {
        path: 'notes/todo.txt',
        byteSize: 23,
        contentType: 'text/plain',
        checksum: 'BASE64_MD5_OF_CONTENT',
        sha256: 'HEX_SHA256_OF_CONTENT',
      },
    ],
  },
});
console.log(data);

Python

from revdoku import Revdoku, AddUploadSessionFilesRequest, UploadSessionFile

client = Revdoku()
response = client.api.add_upload_session_files(
    "bkt_example",
    "bus_example",
    AddUploadSessionFilesRequest(
        files=[
            UploadSessionFile(
                path="notes/todo.txt",
                byte_size=23,
                content_type="text/plain",
                checksum="BASE64_MD5_OF_CONTENT",
                sha256="HEX_SHA256_OF_CONTENT",
            ),
        ],
    ),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/upload_sessions/bus_example/uploads" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "files": [
    {
      "path": "notes/todo.txt",
      "byte_size": 23,
      "content_type": "text/plain",
      "checksum": "BASE64_MD5_OF_CONTENT",
      "sha256": "HEX_SHA256_OF_CONTENT"
    }
  ]
}'

Response 201

Errors

Guide: Upload many files

Save uploaded files

POST /v1/buckets/{bucket_id}/upload_sessions/{session_id}/finalize_batch

Saves up to limit files whose bytes were uploaded. Call it after each batch to keep each request short. DIRECT_UPLOAD_NOT_FOUND names a file whose bytes are missing in error.details.path; upload it again and retry.

Parameters

Request body (optional): TypeScript saveUploadSessionBatchRequest: SaveUploadSessionBatchRequest, Python save_upload_session_batch_request=SaveUploadSessionBatchRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.saveUploadSessionBatch({
  bucketId: 'bkt_example',
  sessionId: 'bus_example',
});
console.log(data);

Python

from revdoku import Revdoku

client = Revdoku()
response = client.api.save_upload_session_batch("bkt_example", "bus_example")
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/upload_sessions/bus_example/finalize_batch" \
  -H "Authorization: Bearer $REVDOKU_API_KEY"

Response 200

Errors

Error codes named above: DIRECT_UPLOAD_NOT_FOUND.

Guide: Upload many files

Finish or cancel a batch upload

POST /v1/buckets/{bucket_id}/upload_sessions/{session_id}/finalize

complete=true saves the remaining uploaded files, creates one bucket version and releases the lock. A 202 response with finalize_pending=true means more files remain: call finalize again after Retry-After. complete=false cancels the session and discards its unsaved files. Finalizing a finished session returns it unchanged.

Parameters

Request body (optional): TypeScript finalizeUploadSessionRequest: FinalizeUploadSessionRequest, Python finalize_upload_session_request=FinalizeUploadSessionRequest(...).

Examples

TypeScript

import { Revdoku } from 'revdoku';

const client = new Revdoku();
const { data } = await client.api.finalizeUploadSession({
  bucketId: 'bkt_example',
  sessionId: 'bus_example',
  finalizeUploadSessionRequest: { complete: true },
});
console.log(data);

Python

from revdoku import Revdoku, FinalizeUploadSessionRequest

client = Revdoku()
response = client.api.finalize_upload_session(
    "bkt_example",
    "bus_example",
    FinalizeUploadSessionRequest(complete=True),
)
print(response.data)

cURL

curl -X POST "https://api.revdoku.com/v1/buckets/bkt_example/upload_sessions/bus_example/finalize" \
  -H "Authorization: Bearer $REVDOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"complete": true}'

Response 200, 202

Errors

Guide: Upload many files