Interface: StorageActionWriter

For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.

server.StorageActionWriter

An interface to read and write files to storage within Convex actions and HTTP actions.

Example

// In an action, download and re-upload a file:
const blob = await ctx.storage.get(storageId);
if (blob) {
  const newStorageId = await ctx.storage.store(blob);
}

Hierarchy

• StorageWriter

  ↳ StorageActionWriter

Methods

getUrl

▸ getUrl(storageId): Promise<null | string>

Get the URL for a file in storage by its Id<"_storage">.

The GET response includes a standard HTTP Digest header with a sha256 checksum.

Example

const url = await ctx.storage.getUrl(storageId);

Parameters

Name	Type	Description
storageId	GenericId<"_storage">	The Id<"_storage"> of the file to fetch from Convex storage.

Returns

Promise<null | string>

• A URL which fetches the file via an HTTP GET, or null if the file no longer exists.

Inherited from

StorageWriter.getUrl

Defined in

server/storage.ts:91

▸ getUrl<T>(storageId): Promise<null | string>

Deprecated

Passing a string is deprecated, use storage.getUrl(Id<"_storage">) instead.

Get the URL for a file in storage by its StorageId.

The GET response includes a standard HTTP Digest header with a sha256 checksum.

Type parameters

Name	Type
T	extends string

Parameters

Name	Type	Description
storageId	T extends { __tableName: any } ? never : T	The StorageId of the file to fetch from Convex storage.

Returns

Promise<null | string>

• A url which fetches the file via an HTTP GET, or null if it no longer exists.

Inherited from

StorageWriter.getUrl

Defined in

server/storage.ts:103

---

getMetadata

▸ getMetadata(storageId): Promise<null | FileMetadata>

Deprecated

Use ctx.db.system.get("_storage", storageId) instead, which returns equivalent metadata from the _storage system table (with a slightly different shape):

const metadata = await ctx.db.system.get("_storage", storageId);
// { _id, _creationTime, sha256, size, contentType? }

Get metadata for a file.

Parameters

Name	Type	Description
storageId	GenericId<"_storage">	The Id<"_storage"> of the file.

Returns

Promise<null | FileMetadata>

• A FileMetadata object if found or null if not found.

Inherited from

StorageWriter.getMetadata

Defined in

server/storage.ts:120

▸ getMetadata<T>(storageId): Promise<null | FileMetadata>

Deprecated

Use ctx.db.system.get("_storage", storageId) instead.

Get metadata for a file.

Type parameters

Name	Type
T	extends string

Parameters

Name	Type	Description
storageId	T extends { __tableName: any } ? never : T	The StorageId of the file.

Returns

Promise<null | FileMetadata>

• A FileMetadata object if found or null if not found.

Inherited from

StorageWriter.getMetadata

Defined in

server/storage.ts:130

---

generateUploadUrl

▸ generateUploadUrl(): Promise<string>

Generate a short-lived URL for uploading a file into storage.

The client should make a POST request to this URL with the file as the body. The response will be a JSON object containing a newly allocated Id<"_storage"> ({ storageId: "..." }).

Example

// In a mutation, generate the upload URL:
export const generateUploadUrl = mutation({
  args: {},
  returns: v.string(),
  handler: async (ctx) => {
    return await ctx.storage.generateUploadUrl();
  },
});

// On the client, upload the file:
// const uploadUrl = await generateUploadUrl();
// const result = await fetch(uploadUrl, { method: "POST", body: file });
// const { storageId } = await result.json();

Returns

Promise<string>

• A short-lived URL for uploading a file via HTTP POST.

Inherited from

StorageWriter.generateUploadUrl

Defined in

server/storage.ts:170

---

delete

▸ delete(storageId): Promise<void>

Delete a file from Convex storage.

Once a file is deleted, any URLs previously generated by getUrl will return 404s.

Example

await ctx.storage.delete(storageId);

Parameters

Name	Type	Description
storageId	GenericId<"_storage">	The Id<"_storage"> of the file to delete from Convex storage.

Returns

Promise<void>

Inherited from

StorageWriter.delete

Defined in

server/storage.ts:183

▸ delete<T>(storageId): Promise<void>

Deprecated

Passing a string is deprecated, use storage.delete(Id<"_storage">) instead.

Delete a file from Convex storage.

Once a file is deleted, any URLs previously generated by getUrl will return 404s.

Type parameters

Name	Type
T	extends string

Parameters

Name	Type	Description
storageId	T extends { __tableName: any } ? never : T	The StorageId of the file to delete from Convex storage.

Returns

Promise<void>

Inherited from

StorageWriter.delete

Defined in

server/storage.ts:194

---

get

▸ get(storageId): Promise<null | Blob>

Download a file from storage as a Blob.

In mutations, files read count toward the transaction's filesRead and fileReadBytes limits. Use ctx.meta.getTransactionMetrics() to check the remaining headroom.

Parameters

Name	Type	Description
storageId	GenericId<"_storage">	The Id<"_storage"> of the file.

Returns

Promise<null | Blob>

A Blob containing the file contents, or null if the file doesn't exist.

Inherited from

StorageWriter.get

Defined in

server/storage.ts:208

▸ get<T>(storageId): Promise<null | Blob>

Deprecated

Passing a string is deprecated, use storage.get(Id<"_storage">) instead.

Get a Blob containing the file associated with the provided StorageId, or null if there is no file.

Type parameters

Name	Type
T	extends string

Parameters

Name	Type
storageId	T extends { __tableName: any } ? never : T

Returns

Promise<null | Blob>

Inherited from

StorageWriter.get

Defined in

server/storage.ts:215

---

store

▸ store(blob, options?): Promise<GenericId<"_storage">>

Upload a Blob directly to storage.

To upload files from a client, use generateUploadUrl instead.

In mutations, files stored count toward the transaction's filesWritten and fileWriteBytes limits. Use ctx.meta.getTransactionMetrics() to check the remaining headroom.

Example

const storageId = await ctx.storage.store(blob);
// If in an action, save storageId to the database via ctx.runMutation

Parameters

Name	Type	Description
blob	Blob	The Blob to store.
options?	Object	Optional settings. Pass sha256 to verify the file integrity.
options.sha256?	string	-

Returns

Promise<GenericId<"_storage">>

The Id<"_storage"> of the newly stored file.

Inherited from

StorageWriter.store

Defined in

server/storage.ts:239