> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage files using 1Password SDKs
> Use 1Password SDKs to read, save, and delete files in your 1Password account.
You can store files in 1Password in two ways:
* [**Field file**](#field-file-operations): A file attachment stored as a custom field in any item. You can attach multiple field files to each item.
* [**Document file**](#document-operations): A file stored as a [Document item](https://support.1password.com/item-categories#document). Document items can only store a single document file.
## Before you get started
Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance. For example:
{/* markdownlint-disable MD046 */}
```go theme={null}
package main
import (
"context"
"github.com/1password/onepassword-sdk-go"
)
func main() {
// TODO: Initialize client using your preferred authentication method (see Overview > Get started)
client, err := onepassword.NewClient(context.Background(),
)
if err != nil {
panic(err)
}
// Your code here
}
```
{/* markdownlint-disable MD046 */}
```javascript theme={null}
import sdk from "@1password/sdk";
async function main() {
const client = await sdk.createClient({
// TODO: Initialize client using your preferred authentication method (see Overview > Get started)
});
// Your code here
}
main().catch(console.error);
```
```javascript theme={null}
const sdk = require("@1password/sdk");
async function main() {
const client = await sdk.createClient({
// TODO: Initialize client using your preferred authentication method (see Overview > Get started)
});
// Your code here
}
main().catch(console.error);
```
{/* markdownlint-disable MD046 */}
```python theme={null}
import asyncio
from onepassword import Client # Also import DesktopAuth for desktop app authentication.
async def main():
# TODO: Initialize client using your preferred authentication method (see Overview > Get started)
client = await Client.authenticate(...)
# Your code here
asyncio.run(main())
```
See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for full example code you can quickly clone and test in your project.
## Read a file
You can read any file saved in 1Password using the [`Items().Files().Read`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L51) method with the attributes of the file you want to retrieve, and the IDs for the [item and vault](/sdks/list-vaults-items/) where the file is stored. 1Password returns the file content as an array of bytes.
You can get the file attributes for a file from its parent item by [retrieving it](/sdks/manage-items#get-an-item).
```go theme={null}
// Read the file field from an item
retrievedFileContent, err := client.Items().Files().Read(context.Background(), item.VaultID, item.ID, item.Files[0].Attributes)
if err != nil {
panic(err)
}
```
```go theme={null}
// Read the document item
content, err := client.Items().Files().Read(context.Background(), replacedDocItem.VaultID, replacedDocItem.ID, *replacedDocItem.Document)
if err != nil {
panic(err)
}
```
You can read any file saved in 1Password using the [`items.files.read()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L68) method with the attributes of the file you want to retrieve, and the IDs for the [item and vault](/sdks/list-vaults-items/) where the file is stored. 1Password returns the file content as an array of bytes.
You can get the file attributes for a file from its parent item by [retrieving it](/sdks/manage-items#get-an-item).
```js theme={null}
// Read the content of the file field on the Item
let content = await client.items.files.read(
item.vaultId,
item.id,
item.files[0].attributes,
);
```
```js theme={null}
// Read the content of the Document Item
let content = await client.items.files.read(
replacedDocumentItem.vaultId,
replacedDocumentItem.id,
replacedDocumentItem.document,
);
```
You can read any file saved in 1Password using the [`items.files.read()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L37) method with the attributes of the file you want to retrieve, and the IDs for the [item and vault](/sdks/list-vaults-items/) where the file is stored. 1Password returns the file content as an array of bytes.
You can get the file attributes for a file from its parent item by [retrieving it](/sdks/manage-items#get-an-item).
```python theme={null}
item = await client.items.get("your-vault-id", "your-item-id")
# Read the content of the file field from an item
content = await client.items.files.read(
item.vault_id, item.id, item.files[0].attributes
)
print(content.decode())
```
```python theme={null}
item = await client.items.get("your-vault-id", "your-item-id")
# Read the content of the Document item
content = await client.items.files.read(
item.vault_id, item.id, item.document
)
print(content.decode())
```
## Field file operations
### Save a file
You can save field files when you create an item or modify an existing item.
To save a file in 1Password as a field file, you'll need to read the file locally then pass the file contents and name using the `FileCreateParams` parameter.
Field file parameters include:
| Parameter | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Name | The name of the file. |
| Content | The file contents. |
| Section ID | The ID for the custom section where the file will be saved. If the section the ID points to does not exist in the item, a new section will be created. |
| Field ID | The ID for the field where the file will be saved. Must be unique within the `Fields` and `Files` of the item. |
You can add files to a new item when you [create the item](/sdks/manage-items#create-an-item) by including them in the [`ItemCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L373) struct.
```go theme={null}
fileContent, err := os.ReadFile("./example/service_account/file.txt")
if err != nil {
panic(err)
}
// Create the File Field item
item, err := client.Items().Create(context.Background(), onepassword.ItemCreateParams{
Title: "Login with File Field created with SDK",
Category: onepassword.ItemCategoryLogin,
VaultID: vaultID,
Sections: []onepassword.ItemSection{
{
ID: sectionID,
},
},
Files: []onepassword.FileCreateParams{
{
Name: "file.txt",
Content: fileContent,
SectionID: sectionID,
FieldID: "file_field",
},
},
})
if err != nil {
panic(err)
}
```
You can add files to a new item when you [create the item](/sdks/manage-items#create-an-item) by including them in the [`ItemCreateParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L304) object.
```js theme={null}
// Create the file field item
let item = await client.items.create({
title: "Login with File Field Item Created With JS SDK",
category: sdk.ItemCategory.Login,
vaultId: vaultId,
fields: [
{
id: "username",
title: "username",
fieldType: sdk.ItemFieldType.Text,
value: "my username",
},
{
id: "password",
title: "password",
fieldType: sdk.ItemFieldType.Concealed,
value: "my secret value",
},
],
sections: [
{
id: "custom section",
title: "my section",
},
],
files: [
{
name: "file.txt",
content: new Uint8Array(fs.readFileSync("file.txt")),
sectionId: "custom section",
fieldId: "file_field",
},
],
});
```
You can add files to a new item when you [create the item](/sdks/manage-items#create-an-item) by including them in the [`ItemCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L553) object.
```python theme={null}
from pathlib import Path
from onepassword import (
FileCreateParams,
ItemCategory,
ItemCreateParams,
ItemField,
ItemFieldType,
ItemSection,
)
# Create an item with a file attached in a file field
to_create = ItemCreateParams(
title="FileField Item created with Python SDK",
category=ItemCategory.LOGIN,
vault_id="your-vault-id",
fields=[
ItemField(
id="username",
title="username",
field_type=ItemFieldType.TEXT,
value="my-username",
),
ItemField(
id="password",
title="password",
field_type=ItemFieldType.CONCEALED,
value="my-password",
),
],
sections=[
ItemSection(id="", title=""),
],
files=[
FileCreateParams(
name="file.txt",
content=Path("./example/file2.txt").read_bytes(),
sectionId="",
fieldId="file_field",
)
],
)
created_item = await client.items.create(to_create)
print(f'Created item with file attached "{created_item.title}" ({created_item.id})')
```
To save a file in an existing item, use the [`Items().Files().Attach()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L34) method.
```go theme={null}
file2Content, err := os.ReadFile("./example/service_account/file2.txt")
if err != nil {
panic(err)
}
// Attach a file field to an item
newItem, err := client.Items().Files().Attach(context.Background(), item, onepassword.FileCreateParams{
Name: "file2.txt",
Content: file2Content,
SectionID: sectionID,
FieldID: "new_file_field",
})
if err != nil {
panic(err)
}
```
To save a file in an existing item, use the [`items.files.attach()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L46) method.
```js theme={null}
// Attach a file field to the item
let attachedItem = await client.items.files.attach(item, {
name: "file2.txt",
content: new Uint8Array(fs.readFileSync("file2.txt")),
sectionId: "custom section",
fieldId: "new_file_field",
});
```
To save a file in an existing item, use the [`items.files.attach()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L13) method.
```python theme={null}
from pathlib import Path
from onepassword import FileCreateParams
item = await client.items.get("your-vault-id", "your-item-id")
# Attach a file field to the item
attached_item = await client.items.files.attach(
item,
FileCreateParams(
name="file2.txt",
content=Path("./example/file2.txt").read_bytes(),
sectionId="",
fieldId="new_file_field",
),
)
print(f'Attached "file2.txt" to item "{attached_item.title}".')
```
### Remove a file
You can delete field files using the [`Items().Files().Delete()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L69) method with the item, section, and field IDs for the file you want to delete. This will remove the file and return the modified item.
```go theme={null}
// Delete a file field from an item
updatedItemWithDeletedFile, err := client.Items().Files().Delete(context.Background(), newItem, newItem.Files[0].SectionID, newItem.Files[0].FieldID)
if err != nil {
panic(err)
}
```
You can delete field files using the [`items.files.delete()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L95) method with the item, section, and field IDs for the file you want to delete. This will remove the file and return the modified item.
```js theme={null}
// Delete a file field from an item
let deletedItem = await client.items.files.delete(
attachedItem,
attachedItem.files[1].sectionId,
attachedItem.files[1].fieldId,
);
```
You can delete field files using the [`items.files.delete()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L60) method with the item, section, and field IDs for the file you want to delete. This will remove the file and return the modified item.
```python theme={null}
item = await client.items.get("your-vault-id", "your-item-id")
# Delete a file field from an item
deleted_file_item = await client.items.files.delete(
item,
item.files[0].section_id,
item.files[0].field_id,
)
print(
f"Deleted file '{item.files[0].attributes.name}' from item '{deleted_file_item.title}'."
)
```
## Document operations
### Save a document
To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the [`Items().Create()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L63) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L24) struct. Make sure to specify `Document` as the item category.
```go theme={null}
fileContent, err := os.ReadFile("./example/service_account/file.txt")
if err != nil {
panic(err)
}
// Create the document item
documentItem, err := client.Items().Create(context.Background(), onepassword.ItemCreateParams{
Title: "Document Item Created With Go SDK",
Category: onepassword.ItemCategoryDocument,
VaultID: vaultID,
Document: &onepassword.DocumentCreateParams{
Name: "file.txt",
Content: fileContent,
},
})
if err != nil {
panic(err)
}
```
To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the [`items.create()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L87) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L21) object. Make sure to specify `Document` as the item category.
```js theme={null}
// Create a Document Item
let item = await client.items.create({
title: "Document Item Created With JS SDK",
category: sdk.ItemCategory.Document,
vaultId: vaultId,
document: {
name: "file.txt",
content: new Uint8Array(fs.readFileSync("file.txt")),
},
});
```
To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the [`items.create()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L31) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L76) object. Make sure to specify `Document` as the item category.
```python theme={null}
from pathlib import Path
from onepassword import (
DocumentCreateParams,
ItemCategory,
ItemCreateParams,
ItemSection,
)
vault_id = "your-vault-id"
# Create a Document item
to_create = ItemCreateParams(
title="Document Item Created with Python SDK",
category=ItemCategory.DOCUMENT,
vault_id=vault_id,
sections=[
ItemSection(id="", title=""),
],
document=DocumentCreateParams(
name="file.txt", content=Path("./example/file2.txt").read_bytes()
),
)
created_item = await client.items.create(to_create)
print(f'Created Document item "{created_item.title}" ({created_item.id})')
```
### Replace a document
To replace the file in a Document item, read the new file locally then pass the file contents to the [`Items().Files().ReplaceDocument()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L87) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L24) struct.
```go theme={null}
// Replace the document item
file2Content, err := os.ReadFile("./example/service_account/file2.txt")
if err != nil {
panic(err)
}
replacedDocItem, err := client.Items().Files().ReplaceDocument(context.Background(), documentItem, onepassword.DocumentCreateParams{
Name: "file2.txt",
Content: file2Content,
})
if err != nil {
panic(err)
}
```
To replace the file in a Document item, read the new file locally then pass the file contents to the [`items.files.replaceDocument()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L122) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L21) object.
```js theme={null}
// Replace the document in the Document Item
let replacedDocumentItem = await client.items.files.replaceDocument(item, {
name: "file2.txt",
content: new Uint8Array(fs.readFileSync("file2.txt")),
});
```
To replace the file in a Document item, read the new file locally then pass the file contents to the [`items.files.replace_document()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L85) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L76) object.
```python theme={null}
from pathlib import Path
from onepassword import DocumentCreateParams
item = await client.items.get("your-vault-id", "your-item-id")
# Replace the document in the Document item
replaced_item = await client.items.files.replace_document(
item,
DocumentCreateParams(
name="file2.txt", content=Path("./example/file2.txt").read_bytes()
),
)
print(f'Replaced document in item "{replaced_item.title}".')
```
## Limitations
1Password SDKs currently have a maximum message size of 50 MB, which impacts the following file operations:
* The SDK can't create files larger than 50 MB.
* The SDK can't retrieve file contents exceeding 50 MB.
* The SDK can't create items containing more than 50 MB of file content.
## Get help
1Password includes 1 GB of storage for individual accounts. Shared plans include:
| Plan | Storage |
| ------------------ | --------------- |
| 1Password Families | 1 GB per person |
| 1Password Teams | 1 GB per person |
| 1Password Business | 5 GB per person |
If you aren't able to save documents in a 1Password Business account, ask your administrator to [turn on file storage for team members](https://support.1password.com/files/?mac#manage-who-can-save-files).
## Learn more
* [Manage items using 1Password SDKs](/sdks/manage-items)
* [Share items using 1Password SDKs](/sdks/share-items)
* [List vaults and items using 1Password SDKs](/sdks/list-vaults-items)
* [End-to-end setup guide](/sdks/setup-tutorial)
* [Workflow: Build integrations with 1Password](/get-started/build-integrations)