Documents API

The Documents API is a secure file management service that provides encrypted storage and retrieval capabilities for files. This feature allows you to upload documents, store them securely with encryption, and retrieve them when needed.

Uploading and downloading documents are rate limited to 10/minute/application.

Upload Document

Uploads a document.

POST

https://api.basistheory.com/documents

Permissions

documents:create

Request

cURL

curl --request POST \
  --url https://api.basistheory.com/documents \
  --header 'BT-API-KEY: <PRIVATE_API_KEY>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'request={"metadata": {"name":"value"}}' \
  --form document=@/path/to/file.pdf

Node

import { Blob } from "buffer";
const blob = new Blob(['Hello World'], { type: 'text/plain' });
const uploaded = await client.documents.upload({
        document: blob,
        request: {
            metadata: {
                "attribute 1": "value 1"
            }
        }
    }
);

C#

var uploaded = await client.Documents.UploadAsync(new DocumentsUploadRequest
{
    Document = new FileParameter
    {
        Stream = new MemoryStream(Encoding.UTF8.GetBytes("Hello World")),
        FileName = "hello.txt",
        ContentType = "text/plain"
    },
    Request = new CreateDocumentRequest
    {
        Metadata = new Dictionary<string, string?>
        {
           ["attribute 1"] = "value 1",
        }
    }
});

Python

document = client.documents.upload(
    document=("hello.txt", "Hello World", "text/plain"),
    request={
        "metadata": {
            "attribute 1": "value 1"
        }
    }
)

Java

File tempFile = Files.createTempFile("test", ".txt").toFile();
String originalContent = "Hello World";
try (FileWriter writer = new FileWriter(tempFile)) {
    writer.write(originalContent);
}
Map<String, Optional<String>> metadata = new HashMap<>();
metadata.put("attribute 1", Optional.of("value 1"));
DocumentsUploadRequest request = DocumentsUploadRequest.builder()
        .request(CreateDocumentRequest.builder()
                .metadata(metadata).build()).build();

Request Parameters

Parameter	Required	Type	Default	Description
request	false	string	null	JSON string containing request metadata. Must be provided as a form field.
document	true	file	null	The document file to upload. Must be provided as a multipart form field with file content.

The request parameter accepts a JSON string with the following properties:

Property	Required	Type	Default	Description
metadata	false	object	{}	Key-value pairs of metadata to associate with the document

Response

Returns a document information if the document was created successfully. Returns an error if there were validation errors, or the document failed to create.

{
  "id": "a05d2a09-b4f4-4ce7-9743-ab18d3aa8a43",
  "tenant_id": "064bbc70-204b-4ef1-a757-ec0878be5945",
  "metadata": {
    "name": "value"
  },
  "content_type": "application/pdf",
  "created_by": "f0f504e5-79c2-40a6-aad3-dbee7a692828",
  "created_at": "2025-07-18T14:41:08.254248+00:00"
}

Get Document Metadata

GET

https://api.basistheory.com/documents/{id}

Permissions

documents:read

Request

cURL

curl --request GET \
  --url https://api.basistheory.com/documents/79602dc6-ac0c-4fe0-9903-62fd88f1303a \
  --header 'BT-API-KEY: <PRIVATE_API_KEY>'

Node

await client.documents.get("c2995d93-600a-44a2-b6f1-2c25e46603a9");

C#

await client.Documents.GetAsync("c2995d93-600a-44a2-b6f1-2c25e46603a9");

Python

client.documents.get(
    id="c2995d93-600a-44a2-b6f1-2c25e46603a9"
)

Java

client.documents().get(uploaded.getId().get());

URI Parameters

Parameter	Required	Type	Default	Description
id	true	uuid	null	The ID of the document

Response

Returns a document with the id provided. Returns an error if the document could not be retrieved.

{
  "id": "79602dc6-ac0c-4fe0-9903-62fd88f1303a",
  "tenant_id": "6f5ea0c2-f1a6-46c2-ba36-8024cecfb2c3",
  "metadata": {
    "name": "value"
  },
  "content_type": "application/pdf",
  "created_by": "0bd433d3-e635-4a81-8263-bb13dcacfc79",
  "created_at": "2025-07-18T14:41:08.254248+00:00"
}

Download Document

GET

https://api.basistheory.com/documents/{id}/data

Permissions

documents:reveal

Request

cURL

curl --request GET \
  --url https://api.basistheory.com/documents/79602dc6-ac0c-4fe0-9903-62fd88f1303a/data \
  --header 'BT-API-KEY: <PRIVATE_API_KEY>'

Node

const download = await client.documents.data.get(uploaded.id!);
const stream: ReadableStream<Uint8Array> = download.stream();
const downloadedContent = await new Response(stream).text();

C#

var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("BT-API-KEY", "<API_KEY>");
var response = await httpClient.GetAsync($"https://api.basistheory.com/documents/{documentId}/data");
var downloadedContent = await response.Content.ReadAsStringAsync();

Python

data_bytes = b""
for chunk in client.documents.data.get(document_id=document_id):
    data_bytes += chunk

data_content = data_bytes.decode('utf-8')

Java

InputStream dataStream = client.documents().data().get(documentId);
ByteArrayOutputStream result = new ByteArrayOutputStream();
byte[] buffer = new byte[1024];
int length;
while ((length = dataStream.read(buffer)) != -1) {
    result.write(buffer, 0, length);
}

Response

Returns the raw, unencrypted binary content of the document file that was previously uploaded.

Delete Document

Deletes a document.

DELETE

https://api.basistheory.com/documents/{id}

Permissions

documents:delete

Request

cURL

curl --request DELETE \
  --url https://api.basistheory.com/documents/79602dc6-ac0c-4fe0-9903-62fd88f1303a \
  --header 'BT-API-KEY: <PRIVATE_API_KEY>'

Node

await client.documents.delete("c2995d93-600a-44a2-b6f1-2c25e46603a9");

C#

await client.Documents.DeleteAsync("c2995d93-600a-44a2-b6f1-2c25e46603a9");

Python

client.documents.delete(
    id="c2995d93-600a-44a2-b6f1-2c25e46603a9"
)

Java

client.documents().delete(documentId);

URI Parameters

Parameter	Required	Type	Default	Description
id	true	uuid	null	The ID of the document

Response

Returns 204 No Content if the document was deleted successfully. Returns an error if the document could not be deleted.